# Chamadas

**Evento:** `call` · **Transporte:** POST para o seu receptor

Acompanhe sinalização de chamadas e registros de chamadas de saída concluídas.

## Duas formas de evento

| `type` | O que representa | Onde correlacionar |
|---|---|---|
| `Call` | Sinalização ao vivo: oferta, aceite, encerramento, rejeição ou aviso | `event.CallID` e, quando disponível, `event.Data.Tag` |
| `CallLog` | Registro de chamada de saída concluída, recebido pelo fluxo de sincronização | `event.callID` e `event.callResult` |

Os subtipos incluem oferta, aceite, encerramento, rejeição, avisos de chamada e sinalização de latência, conforme os dados recebidos. Avisos de latência podem ser suprimidos quando já houve notificação para a chamada. Não espere uma sequência fixa nem um evento para cada transição interna.

## Como interpretar

- `EventType` é sempre `call`; `type` diferencia `Call` e `CallLog`.
- No fluxo ao vivo, o subtipo pode estar em `event.Data.Tag`. O campo `Reason` aparece em encerramentos quando fornecido.
- `fromMe` descreve a origem. `wasSentByAPI` aparece no fluxo ao vivo quando a API consegue classificar essa origem.
- Identidades PN/LID podem ser acrescentadas quando resolvidas. Em chamadas de grupo, também pode haver `chatid`/`chatlid` na raiz.

## Como processar

Correlacione a chamada pelo ID dentro da instância, mas não deduplique apenas pelo ID: oferta e encerramento da mesma chamada são eventos diferentes. Não interprete `CallLog` como uma nova chamada recebida. Estes eventos não contêm o áudio da ligação.

Os exemplos abaixo incluem sinalização ao vivo e um registro concluído. Campos remotos opcionais variam entre clientes e situações.

## Resultados em CallLog

O registro usa códigos numéricos: `0` conectado, `1` rejeitado, `2` cancelado, `3` aceito em outro dispositivo, `4` perdido, `5` inválido, `6` indisponível, `8` falha e `9` abandonado. Registros ainda em andamento ou futuros não são emitidos por esse fluxo de conclusão.


Quando disponível, `callState` informa offered, accepted, terminated ou rejected para o evento ao vivo.

## Habilitar este evento

Adicione `call` à lista `events` do webhook da instância. Preserve os outros eventos de que sua integração precisa.

```json
{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "call"
  ]
}
```

Envie essa configuração para [POST /webhook](/reference/updateWebhook.md), usando o header `token`. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

## Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

| Campo | Tipo | Significado |
|---|---|---|
| `EventType` | string | **Obrigatório.** Tipo de evento, por exemplo connection ou messages. |
| `owner` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `token` | string | **Obrigatório.** Token da instância; dado sensível. |
| `BaseUrl` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `instanceName` | string | Consulte o objeto ou exemplo correspondente. |
| `type` | string | Call para sinalização ao vivo; CallLog para registro de chamada de saída concluída. |
| `fromMe` | boolean | Chamada originada pela conta conectada. |
| `wasSentByAPI` | boolean | Indica início pela API quando informado no fluxo ao vivo. |
| `isGroup` | boolean | Presente em CallLog; no fluxo ao vivo também consulte event.GroupJID. |
| `chatid` | string | JID da conversa, quando resolvido. |
| `chatlid` | string / null | LID da conversa; pode ser ausente ou null. |
| `sender_pn` | string / null | JID por telefone, quando conhecido. |
| `sender_lid` | string / null | Identificador LID, quando conhecido. |
| `event` | object | Dados da sinalização ou do registro. O formato depende de type. |
| `event.CallID` | string | Identificador da chamada ao vivo. Use com o subtipo; uma chamada gera várias notificações. |
| `event.From` | string | JID de quem enviou a sinalização. |
| `event.CallCreator` | string | JID de quem criou a chamada. |
| `event.CallCreatorAlt` | string | Identidade alternativa, quando disponível. |
| `event.GroupJID` | string | JID do grupo quando aplicável; pode estar vazio. |
| `event.Timestamp` | string | Data/hora da sinalização ao vivo em formato textual. |
| `event.RemotePlatform` | string | Plataforma remota, quando disponível. |
| `event.RemoteVersion` | string | Versão do cliente remoto, quando disponível. |
| `event.Reason` | string | Motivo informado no encerramento, quando presente. |
| `event.Data` | object / null | Nó de sinalização; pode não estar presente em todas as variantes. |
| `event.Data.Tag` | string | Subtipo recebido, como offer, accept, terminate ou reject. |
| `event.Data.Attrs` | variável | Atributos do nó; formato variável. |
| `event.Data.Content` | variável | Conteúdo adicional do nó; formato variável. |
| `event.callID` | string | ID no registro CallLog (grafia diferente de CallID). |
| `event.callResult` | integer | Resultado numérico do registro CallLog. Não confundir com um status HTTP. |
| `event.Media` | string | Áudio ou vídeo em avisos de chamada, quando informado. |
| `event.Type` | string | Pode indicar group em avisos de chamada de grupo; é diferente do type da raiz. |
| `event.isIncoming` | boolean | Direção no registro CallLog; o fluxo documentado emite registros de saída. |
| `event.isVideo` | boolean | Indica vídeo no registro CallLog, quando presente. |
| `event.callCreatorJID` | string | Criador no registro CallLog. |
| `event.groupJID` | string | Grupo no registro CallLog, quando aplicável. |
| `callState` | string | Estado da chamada em um evento ao vivo, quando disponível. |

## Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

### Oferta de chamada recebida

```json
{
  "EventType": "call",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "Call",
  "fromMe": false,
  "wasSentByAPI": false,
  "sender_pn": "5511888888888@s.whatsapp.net",
  "event": {
    "From": "5511888888888@s.whatsapp.net",
    "Timestamp": "2026-09-08T12:00:00Z",
    "CallCreator": "5511888888888@s.whatsapp.net",
    "CallID": "CALL_EXEMPLO",
    "GroupJID": "",
    "RemotePlatform": "android",
    "RemoteVersion": "versão-do-cliente",
    "Data": {
      "Tag": "offer"
    }
  },
  "callState": "offered"
}
```

### Encerramento da mesma chamada

```json
{
  "EventType": "call",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "Call",
  "fromMe": false,
  "wasSentByAPI": false,
  "event": {
    "From": "5511888888888@s.whatsapp.net",
    "Timestamp": "2026-09-08T12:01:00Z",
    "CallCreator": "5511888888888@s.whatsapp.net",
    "CallID": "CALL_EXEMPLO",
    "GroupJID": "",
    "Data": {
      "Tag": "terminate"
    }
  },
  "callState": "terminated"
}
```

### Registro de chamada de saída concluída

```json
{
  "EventType": "call",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "type": "CallLog",
  "fromMe": true,
  "isGroup": false,
  "event": {
    "callID": "CALL_EXEMPLO",
    "callResult": 0,
    "isIncoming": false
  }
}
```

## Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta `2xx` rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte [diagnóstico de webhooks](/docs/integrations-webhooks#diagnostico) e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.

## Referências

- [Introdução, configuração e catálogo](/docs/integrations-webhooks)
- [Autenticação](/docs/authentication)
- [Contrato OpenAPI completo](/openapi-bundled.json)