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.

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

Envie essa configuração para POST /webhook, 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

{
  "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

{
  "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

{
  "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 e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.