> For the complete documentation index, see [llms.txt](https://digitalsac.gitbook.io/digicalls/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://digitalsac.gitbook.io/digicalls/webphone-widget/recursos/eventos-em-tempo-real.md).

# Eventos em tempo real

O DigiCalls usa **Server-Sent Events (SSE)** em vez de WebSocket para notificações de chamada.

```
GET /api/events?token=dev_...&clientId=...
Authorization: Bearer dev_...
```

> `EventSource` não envia headers customizados — o SDK passa o token na **query** `token=`.

### Eventos principais

| Evento             | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `incoming`         | Chamada recebida                                       |
| `incoming-claimed` | Outro operador atendeu                                 |
| `call-status`      | Mudança de status (`connected`, …)                     |
| `call-ended`       | Chamada encerrada                                      |
| `call-peer`        | Nome/foto do contato                                   |
| `call-peer-mute`   | Interlocutor silenciou / reativou o microfone          |
| `call-list`        | Snapshot de chamadas ativas (pode incluir `peerMuted`) |
| `session-list`     | Lista de devices                                       |
| `session-qr`       | QR atualizado                                          |
| `auth-state`       | Pareamento / logout                                    |

### Formato

Cada mensagem SSE contém JSON:

```json
{ "type": "incoming", "sessionId": "...", "id": "call-uuid", "peer": "5511...@s.whatsapp.net" }
```

Exemplo de mute do interlocutor:

```json
{ "type": "call-peer-mute", "sessionId": "...", "id": "call-uuid", "muted": true }
```

No SDK: `call.onPeerMuteChange(muted)`. No webphone (≥ 0.3.3): badge na chamada ativa.

### Uso no SDK

Transparente — `onOffer`, `onEnd`, `onPeerMuteChange`, etc. já consomem SSE.

### Uso direto (sem SDK)

```javascript
const es = new EventSource(
  "https://calls.digitalsac.io/api/events?token=dev_xxx&clientId=crm-1"
);
es.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  if (ev.type === "incoming") showRinging(ev);
  if (ev.type === "call-peer-mute") showPeerMuteBadge(ev.id, ev.muted);
};
```

### Sessão de usuário (painel)

Operadores logados no painel usam o mesmo endpoint com token de **login**:

```
GET /api/events?token=<session_jwt>&clientId=...
```

Recebem eventos de **todos** os devices do usuário.

### vs. Webhook HTTP (cliente)

SSE é **pull persistente** do navegador/backend conectado. Para integrações server-to-server (CRM gravando histórico), use:

* Polling: `GET /api/devices/{token}/calls`
* Webhook outbound (planejado): Webhook de integração

### Reconexão

O SDK implementa backoff exponencial e detecção de stream stale (\~45s).