API Reference v1

Documentação da API

Referencia completa dos endpoints da API WhatsApp do Fala Comigo. Todos os endpoints requerem autenticacao via header token. Use o token da sua instancia obtido no dashboard.

Autenticacao Sessao Enviar Mensagens Chat Download de Midia Usuarios Grupos Newsletter (Canais)Chamadas de Voz Motor de Voz Webhook Config Webhook Payload Eventos Formato de Numero ContextInfo

Autenticacao

Todas as requisicoes devem incluir o header token com o token da sua instancia.

Voce obtem o token no dashboard ao criar ou acessar uma instancia. O token e unico por instancia e deve ser mantido em segredo.

Exemplo de header

GET /session/status HTTP/1.1
Host: api.falacomigo.io
token: fc_inst_a1b2c3d4e5f6g7h8i9j0...
Content-Type: application/json

Nunca exponha seu token em codigo frontend ou repositorios publicos. Se o token for comprometido, gere um novo no dashboard.

Envelope de resposta

Por padrao, toda resposta e embrulhada em um envelope padrao com success, data e meta. O objeto documentado em cada endpoint fica em data.data. Adicione ?format=legacy a qualquer requisicao para receber a resposta sem o envelope externo.

Envelope

{
  "success": true,
  "data": {
    "code": 200,
    "success": true,
    "data": { /* o objeto documentado em cada endpoint */ }
  },
  "meta": { "timestamp": "2026-07-04T12:00:00Z", "request_id": "..." }
}

Sessao

Gerenciar a conexao da sua instancia com o WhatsApp.

POST/session/connect

Conectar ao WhatsApp e iniciar a sessao. Subscribe define os eventos que serao enviados ao webhook (ignora nomes invalidos). Com Immediate=false a API aguarda ate 10s para confirmar a conexao antes de responder. Apos conectar sem sessao autenticada, use /session/qr para obter o QR code.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Subscribe": ["Message", "ReadReceipt", "ChatPresence"],
  "Immediate": false
}

Response

{
  "webhook": "https://seu-servidor.com/webhook",
  "jid": "5511999999999@s.whatsapp.net",
  "events": "Message,ReadReceipt,ChatPresence",
  "details": "Connected!"
}

POST/session/disconnect

Desconectar a sessao ativa do WhatsApp. A sessao pode ser reconectada depois sem precisar escanear o QR code novamente.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Details": "Disconnected"
}

POST/session/logout

Fazer logout completo da sessao. Remove a autenticacao salva. Sera necessario escanear o QR code novamente na proxima conexao.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Details": "Logged out"
}

GET/session/status

Retorna o status completo da sessao: estado de conexao/login, JID, nome, webhook, eventos inscritos e configuracoes de proxy, S3 e HMAC.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Minha Empresa",
  "connected": true,
  "loggedIn": true,
  "token": "fc_inst_a1b2c3d4...",
  "jid": "5511999999999@s.whatsapp.net",
  "webhook": "https://seu-servidor.com/webhook",
  "events": "Message,ReadReceipt",
  "qrcode": "",
  "history": "0",
  "proxy_config": { "enabled": false, "proxy_url": "" },
  "s3_config": { "enabled": false, "bucket": "", "region": "" },
  "hmac_configured": false
}

GET/session/qr

Retorna o QR code atual (data URL de imagem PNG em base64). Use apos /session/connect enquanto a sessao ainda nao foi autenticada e nao esta logada.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "QRCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}

POST/session/pairphone

Gera um codigo de pareamento para conectar sem QR code. O usuario digita o codigo no WhatsApp do celular em Dispositivos Conectados > Conectar com Numero.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999"
}

Response

{
  "LinkingCode": "ABCD-EFGH"
}

POST/session/proxy

Configurar (ou remover) um proxy para a sessao. So pode ser alterado com a sessao desconectada. Sao aceitos apenas proxies http e socks5. Use enable=false para remover.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "proxy_url": "socks5://usuario:senha@host:1080",
  "enable": true
}

Response

{
  "Details": "Proxy configured successfully",
  "ProxyURL": "socks5://usuario:senha@host:1080"
}

POST/session/history

Definir quantas mensagens por conversa sao armazenadas para consulta via GET /chat/history. Use 0 para desativar o armazenamento de historico.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "history": 100
}

Response

{
  "Details": "History configured successfully",
  "History": 100
}

GET/session/history?count=50&chat_jid=...&oldest_msg_id=...&oldest_msg_timestamp=...

Solicita ao WhatsApp a sincronizacao de mensagens antigas (history sync). As mensagens chegam de forma assincrona pelo evento HistorySync no webhook. Todos os query params sao opcionais.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "details": "History sync request Sent",
  "timestamp": 1711324265,
  "count": 50,
  "chat_jid": "5511999999999@s.whatsapp.net",
  "oldest_msg_id": "",
  "oldest_msg_from_me": false,
  "oldest_msg_timestamp": 0
}

Enviar Mensagens

Endpoints para enviar diferentes tipos de mensagem. A maioria retorna { Details, Id, Timestamp } com o ID e o horario (epoch) da mensagem enviada. O campo Id no corpo e opcional: se vazio, a API gera um automaticamente. ContextInfo (opcional) permite responder mensagens e mencionar usuarios.

POST/chat/send/text

Enviar mensagem de texto. Com LinkPreview=true, a API busca a previa (Open Graph) do primeiro link do texto. QuotedText e um atalho para citar um texto sem informar o ContextInfo completo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Body": "Ola! Como posso ajudar?",
  "LinkPreview": true,
  "Id": "",
  "ContextInfo": {
    "StanzaId": "",
    "Participant": "",
    "MentionedJID": []
  }
}

Response

{
  "Details": "Sent",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Timestamp": 1711324265
}

POST/chat/send/image

Enviar imagem com legenda opcional. O campo Image aceita uma URL publica (http/https) ou um data URL base64 (data:image/...). A miniatura JPEG e gerada automaticamente.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Image": "https://exemplo.com/foto.jpg",
  "Caption": "Confira esta imagem",
  "MimeType": "",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0B7D1E4A3C2F5D8B1",
  "Timestamp": 1711324290
}

POST/chat/send/audio

Enviar audio. O campo Audio deve ser um data URL base64 (data:audio/...); URL publica NAO e aceita aqui. Use ptt=true para nota de voz (bolinha verde) - nesse caso a API transcodifica para opus e calcula duracao/waveform automaticamente se omitidos.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Audio": "data:audio/ogg;base64,T2dnUwACAAAA...",
  "ptt": true,
  "mimetype": "audio/ogg; codecs=opus",
  "Seconds": 15,
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0C9E3A7B4D1F2E6C3",
  "Timestamp": 1711324310
}

POST/chat/send/video

Enviar video com legenda opcional. O campo Video aceita URL publica (http/https) ou data URL base64. JPEGThumbnail (base64) e opcional.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Video": "https://exemplo.com/video.mp4",
  "Caption": "Assista este video",
  "MimeType": "",
  "JPEGThumbnail": "",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0D2F4B8C5E3A1D7E2",
  "Timestamp": 1711324335
}

POST/chat/send/document

Enviar documento (PDF, DOCX, XLSX, etc). O campo Document deve ser um data URL base64 iniciando com data:application/octet-stream;base64,. FileName (obrigatorio) define o nome exibido no WhatsApp.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Document": "data:application/octet-stream;base64,JVBERi0xLjQK...",
  "FileName": "contrato-2026.pdf",
  "Caption": "",
  "MimeType": "",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0E5A1C9D6F4B2E8A3",
  "Timestamp": 1711324360
}

POST/chat/send/sticker

Enviar sticker (figurinha). O campo Sticker deve ser um data URL base64 (data:...). WebP e enviado direto; PNG, JPEG, GIF e video sao convertidos para WebP automaticamente. Campos de pack (PackId/PackName/PackPublisher/Emojis) sao opcionais.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Sticker": "data:image/webp;base64,UklGRlYAAABXRUJQ...",
  "MimeType": "",
  "PngThumbnail": "",
  "PackId": "com.exemplo.stickers",
  "PackName": "Meus Stickers",
  "PackPublisher": "Fala Comigo",
  "Emojis": ["😀", "👍"],
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0F8B2D1E7A5C3F9B4",
  "Timestamp": 1711324385
}

POST/chat/send/location

Enviar localizacao com coordenadas GPS e nome opcional do local.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Latitude": -23.5505,
  "Longitude": -46.6333,
  "Name": "Av Paulista, 1000 - Sao Paulo",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0A1C3E5D8B2F4A6C5",
  "Timestamp": 1711324410
}

POST/chat/send/contact

Enviar cartao de contato no formato vCard. Name e o nome exibido e Vcard deve conter o vCard completo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Name": "Joao Silva",
  "Vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Joao Silva\nTEL;type=CELL:+5511888888888\nEND:VCARD",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0B4D6F2A9C1E3B7D8",
  "Timestamp": 1711324435
}

POST/chat/send/poll

Enviar enquete (poll). Informe o destino em group (numero ou JID), o titulo em header e no minimo 2 options. Os participantes podem votar nas opcoes.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "group": "120363012345678901@g.us",
  "header": "Qual horario prefere para a reuniao?",
  "options": ["09:00", "14:00", "18:00"],
  "Id": ""
}

Response

{
  "Details": "Poll sent successfully",
  "Id": "3EB0F7B8C9D2E4A5F3B7"
}

POST/chat/send/edit

Editar uma mensagem ja enviada. Id (obrigatorio) e o ID da mensagem original e Body e o novo texto.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Body": "Texto corrigido da mensagem"
}

Response

{
  "Details": "Sent",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Timestamp": 1711324560
}

Chat

Acoes sobre conversas e mensagens existentes.

POST/chat/markread

Marcar mensagens como lidas (tique azul). Id e uma lista de IDs de mensagem. ChatPhone e o numero da conversa; SenderPhone e opcional (util em grupos). Alternativamente pode-se enviar Chat/Sender como JID.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Id": ["3EB0A8C2F6B2D4A1C3E5"],
  "ChatPhone": "5511999999999",
  "SenderPhone": ""
}

Response

{
  "Details": "Message(s) marked as read"
}

POST/chat/react

Enviar reacao (emoji) a uma mensagem. Body e o emoji (use "remove" para retirar a reacao). Id e o ID da mensagem alvo; prefixe com "me:" para reagir a uma mensagem enviada por voce. Participant e opcional (autor original em grupos).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Body": "👍",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Participant": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Timestamp": 1711324600
}

POST/chat/delete

Deletar (apagar para todos) uma mensagem enviada por voce.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Id": "3EB0A8C2F6B2D4A1C3E5"
}

Response

{
  "Details": "Deleted",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Timestamp": 1711324620
}

POST/chat/presence

Enviar indicador de presenca em uma conversa. State pode ser composing (digitando) ou paused. Para o indicador de gravacao de audio, use State=composing com Media=audio.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "State": "composing",
  "Media": ""
}

Response

{
  "Details": "Chat presence set successfuly"
}

POST/chat/archive

Arquivar ou desarquivar uma conversa. Jid e o JID da conversa e Archive=true arquiva, false desarquiva.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Jid": "5511999999999@s.whatsapp.net",
  "Archive": true
}

Response

{
  "success": true,
  "message": "Chat archived"
}

GET/chat/history?chat_jid=5511999999999@s.whatsapp.net&limit=50

Obter o historico de mensagens armazenado de uma conversa (requer historico habilitado via POST /session/history). chat_jid e obrigatorio; limit e opcional (padrao 50). Use chat_jid=index para listar as conversas com historico.

Header: token: {instance_token}

Mostrar exemplos

Response

[
  {
    "id": 1,
    "user_id": "a1b2c3d4-...",
    "chat_jid": "5511999999999@s.whatsapp.net",
    "sender_jid": "5511999999999@s.whatsapp.net",
    "message_id": "3EB0A8C2F6B2D4A1C3E5",
    "timestamp": "2026-03-24T23:51:05-03:00",
    "message_type": "text",
    "text_content": "Ola, tudo bem?",
    "media_link": "",
    "quoted_message_id": ""
  }
]

Download de Midia

Baixar arquivos de midia recebidos em mensagens. Estes endpoints NAO usam Phone/Id: informe os metadados de midia entregues pelo webhook (Url, DirectPath, MediaKey, Mimetype, FileEncSHA256, FileSHA256, FileLength) - normalmente os mesmos campos do objeto imageMessage/videoMessage/etc. do payload. A resposta retorna Mimetype e Data como data URL base64.

POST/chat/downloadimage

Baixar imagem de uma mensagem recebida. Retorna a midia como data URL base64.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Url": "https://mmg.whatsapp.net/v/...",
  "DirectPath": "/v/t62.7118-24/...",
  "MediaKey": "base64_da_media_key",
  "Mimetype": "image/jpeg",
  "FileEncSHA256": "base64_do_hash",
  "FileSHA256": "base64_do_hash",
  "FileLength": 45230
}

Response

{
  "Mimetype": "image/jpeg",
  "Data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

POST/chat/downloadvideo

Baixar video de uma mensagem recebida. Mesmos campos de metadados do downloadimage.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Url": "https://mmg.whatsapp.net/v/...",
  "DirectPath": "/v/t62.7161-24/...",
  "MediaKey": "base64_da_media_key",
  "Mimetype": "video/mp4",
  "FileEncSHA256": "base64_do_hash",
  "FileSHA256": "base64_do_hash",
  "FileLength": 1048576
}

Response

{
  "Mimetype": "video/mp4",
  "Data": "data:video/mp4;base64,AAAAIGZ0eXBpc29t..."
}

POST/chat/downloadaudio

Baixar audio de uma mensagem recebida. Mesmos campos de metadados do downloadimage.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Url": "https://mmg.whatsapp.net/v/...",
  "DirectPath": "/v/t62.7117-24/...",
  "MediaKey": "base64_da_media_key",
  "Mimetype": "audio/ogg; codecs=opus",
  "FileEncSHA256": "base64_do_hash",
  "FileSHA256": "base64_do_hash",
  "FileLength": 8123
}

Response

{
  "Mimetype": "audio/ogg; codecs=opus",
  "Data": "data:audio/ogg; codecs=opus;base64,T2dnUwACAAAA..."
}

POST/chat/downloaddocument

Baixar documento de uma mensagem recebida. Mesmos campos de metadados do downloadimage.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Url": "https://mmg.whatsapp.net/v/...",
  "DirectPath": "/v/t62.7119-24/...",
  "MediaKey": "base64_da_media_key",
  "Mimetype": "application/pdf",
  "FileEncSHA256": "base64_do_hash",
  "FileSHA256": "base64_do_hash",
  "FileLength": 204800
}

Response

{
  "Mimetype": "application/pdf",
  "Data": "data:application/pdf;base64,JVBERi0xLjQKJcfs..."
}

POST/chat/downloadsticker

Baixar sticker de uma mensagem recebida. Mesmos campos de metadados do downloadimage.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Url": "https://mmg.whatsapp.net/v/...",
  "DirectPath": "/v/t62.15575-24/...",
  "MediaKey": "base64_da_media_key",
  "Mimetype": "image/webp",
  "FileEncSHA256": "base64_do_hash",
  "FileSHA256": "base64_do_hash",
  "FileLength": 15360
}

Response

{
  "Mimetype": "image/webp",
  "Data": "data:image/webp;base64,UklGRlYAAABXRUJQ..."
}

Usuarios

Obter informacoes sobre contatos e usuarios do WhatsApp.

POST/user/info

Obter informacoes detalhadas de um ou mais usuarios (status, foto, dispositivos, etc). Phone e uma lista de numeros. A resposta e um objeto Users indexado por JID.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": ["5511999999999", "5511888888888"]
}

Response

{
  "Users": {
    "5511999999999@s.whatsapp.net": {
      "Status": "Disponivel",
      "PictureID": "1234567890",
      "Devices": ["5511999999999.0:0@s.whatsapp.net"],
      "VerifiedName": null
    }
  }
}

POST/user/check

Verificar se numeros possuem conta no WhatsApp. Phone e uma lista de numeros. Util para validar numeros antes de enviar mensagens.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": ["5511999999999", "5511777777777"]
}

Response

{
  "Users": [
    {
      "Query": "5511999999999",
      "IsInWhatsapp": true,
      "JID": "5511999999999@s.whatsapp.net",
      "VerifiedName": ""
    },
    {
      "Query": "5511777777777",
      "IsInWhatsapp": false,
      "JID": "5511777777777@s.whatsapp.net",
      "VerifiedName": ""
    }
  ]
}

POST/user/avatar

Obter a foto de perfil de um usuario. Preview=true retorna a versao em baixa resolucao; false retorna a foto em alta resolucao.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Preview": false
}

Response

{
  "URL": "https://pps.whatsapp.net/v/t61.24694-24/...",
  "ID": "1234567890",
  "Type": "image",
  "DirectPath": "/v/t61.24694-24/..."
}

GET/user/contacts

Listar todos os contatos conhecidos pela instancia. Retorna um objeto indexado por JID com os dados de cada contato.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "5511999999999@s.whatsapp.net": {
    "Found": true,
    "FirstName": "Joao",
    "FullName": "Joao Silva",
    "PushName": "Joao",
    "BusinessName": ""
  }
}

POST/user/presence

Definir sua presenca global no WhatsApp. type deve ser available ou unavailable.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "type": "available"
}

Response

{
  "Details": "Presence set successfuly"
}

GET/user/lid/{jid}

Obter o LID (identificador interno do WhatsApp) associado a um numero de telefone. O JID vai na propria URL.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "jid": "5511999999999@s.whatsapp.net",
  "lid": "123456789012345@lid"
}

Grupos

Gerenciar grupos do WhatsApp: criar, listar, configurar e gerenciar participantes.

POST/group/create

Criar um novo grupo. name e o nome (assunto) e participants a lista de numeros.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "name": "Equipe Comercial",
  "participants": ["5511999999999", "5511888888888"]
}

Response

{
  "JID": "120363012345678901@g.us",
  "Name": "Equipe Comercial",
  "OwnerJID": "5511999999999@s.whatsapp.net",
  "Participants": [
    { "JID": "5511999999999@s.whatsapp.net", "IsAdmin": true, "IsSuperAdmin": true }
  ]
}

GET/group/list

Listar todos os grupos em que a instancia participa (dados completos de cada grupo).

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Groups": [
    {
      "JID": "120363012345678901@g.us",
      "Name": "Equipe Comercial",
      "Topic": "Canal de vendas",
      "ParticipantCount": 5,
      "Participants": []
    }
  ]
}

GET/group/info?groupJID=120363012345678901@g.us

Obter informacoes detalhadas de um grupo especifico.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "JID": "120363012345678901@g.us",
  "Name": "Equipe Comercial",
  "Topic": "Canal de vendas",
  "OwnerJID": "5511999999999@s.whatsapp.net",
  "Participants": [
    { "JID": "5511999999999@s.whatsapp.net", "IsAdmin": true, "IsSuperAdmin": true },
    { "JID": "5511888888888@s.whatsapp.net", "IsAdmin": false, "IsSuperAdmin": false }
  ]
}

GET/group/invitelink?groupJID=120363012345678901@g.us&reset=false

Obter o link de convite do grupo. Use reset=true para invalidar o link anterior e gerar um novo.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "InviteLink": "https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv"
}

POST/group/inviteinfo

Obter informacoes de um grupo a partir do link/codigo de convite (sem entrar). Code aceita o link completo ou apenas o codigo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Code": "https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv"
}

Response

{
  "JID": "120363012345678901@g.us",
  "Name": "Equipe Comercial",
  "Topic": "Canal de vendas",
  "ParticipantCount": 5
}

POST/group/join

Entrar em um grupo usando o link/codigo de convite. Code aceita o link completo ou apenas o codigo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Code": "https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv"
}

Response

{
  "Details": "Group joined successfully"
}

POST/group/leave

Sair de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us"
}

Response

{
  "Details": "Group left successfully"
}

POST/group/name

Alterar o nome (assunto) de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us",
  "Name": "Equipe Comercial 2026"
}

Response

{
  "Details": "Group Name set successfully"
}

POST/group/topic

Alterar a descricao (topico) de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us",
  "Topic": "Canal oficial da equipe de vendas"
}

Response

{
  "Details": "Group Topic set successfully"
}

POST/group/photo

Alterar a foto de um grupo. Image deve ser um data URL base64 e a imagem precisa estar em formato JPEG (o WhatsApp so aceita JPEG para foto de grupo).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us",
  "Image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
}

Response

{
  "Details": "Group Photo set successfully",
  "PictureID": "9876543210"
}

POST/group/photo/remove

Remover a foto atual do grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "groupjid": "120363012345678901@g.us"
}

Response

{
  "Details": "Group Photo removed successfully"
}

POST/group/announce

Ativar ou desativar o modo de anuncio. Quando ativado (Announce=true), somente admins podem enviar mensagens.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us",
  "Announce": true
}

Response

{
  "Details": "Group Announce set successfully"
}

POST/group/locked

Bloquear ou desbloquear a edicao de informacoes do grupo. Quando bloqueado (locked=true), somente admins podem editar nome, foto e descricao.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "groupjid": "120363012345678901@g.us",
  "locked": true
}

Response

{
  "Details": "Group Locked setting updated successfully"
}

POST/group/ephemeral

Configurar mensagens temporarias (que desaparecem) do grupo. duration aceita 24h, 7d, 90d ou off.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "groupjid": "120363012345678901@g.us",
  "duration": "7d"
}

Response

{
  "Details": "Disappearing timer set successfully"
}

POST/group/updateparticipants

Adicionar, remover, promover ou rebaixar participantes. Phone e a lista de numeros e Action pode ser add, remove, promote ou demote.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "GroupJID": "120363012345678901@g.us",
  "Phone": ["5511777777777", "5511666666666"],
  "Action": "add"
}

Response

{
  "Details": "Group Participants updated successfully"
}

Newsletter (Canais)Beta

Endpoints para listar e publicar em canais (newsletters) do WhatsApp. A instancia conectada precisa ser admin do canal para conseguir publicar. Use o JID do canal no formato 120363xxxxxxxxxxxx@newsletter (obtido via GET /newsletter/list ou GET /jid/list).

GET/newsletter/list

Listar todos os canais (newsletters) em que a instancia esta inscrita.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Newsletter": [
    {
      "id": "120363012345678901@newsletter",
      "thread_metadata": {
        "name": { "text": "Meu Canal", "id": "0" },
        "description": { "text": "Descricao do canal", "id": "0" },
        "subscribers_count": "1234"
      }
    }
  ]
}

GET/jid/list?type=all|groups|channels

Listar de uma vez os JIDs de todos os grupos e canais da instancia. Atalho conveniente para nao precisar chamar /group/list e /newsletter/list separadamente. Use ?type=groups ou ?type=channels para retornar apenas um dos lados (default: all).

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Groups": [
    {
      "JID": "120363012345678901@g.us",
      "Name": "Equipe Comercial",
      "ParticipantCount": 5
    }
  ],
  "Channels": [
    {
      "JID": "120363012345678901@newsletter",
      "Name": "Meu Canal",
      "SubscriberCount": 1234,
      "Role": "admin"
    }
  ]
}

POST/newsletter/send/textBeta

Publicar mensagem de texto em um canal. Requer que a instancia seja admin do canal.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "JID": "120363012345678901@newsletter",
  "Body": "Novidade no canal!",
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Timestamp": 1711324265
}

POST/newsletter/send/imageBeta

Publicar imagem em um canal. Image aceita data URL (data:image/...) ou URL publica. Midia em canal nao e criptografada (e publica para inscritos).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "JID": "120363012345678901@newsletter",
  "Image": "https://exemplo.com/foto.jpg",
  "Caption": "Confira esta imagem",
  "MimeType": "",
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0B7D1E4A3C2F5D8B1",
  "Timestamp": 1711324290
}

POST/newsletter/send/videoBeta

Publicar video em um canal. Video aceita data URL ou URL publica.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "JID": "120363012345678901@newsletter",
  "Video": "https://exemplo.com/video.mp4",
  "Caption": "Assista este video",
  "MimeType": "",
  "JPEGThumbnail": "",
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0D2F4B8C5E3A1D7E2",
  "Timestamp": 1711324335
}

POST/newsletter/send/audioBeta

Publicar audio (ou nota de voz com PTT=true) em um canal. Audio deve ser um data URL no formato data:audio/...

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "JID": "120363012345678901@newsletter",
  "Audio": "data:audio/ogg;base64,T2dnUwACAAAA...",
  "PTT": true,
  "MimeType": "",
  "Seconds": 15,
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0C9E3A7B4D1F2E6C3",
  "Timestamp": 1711324310
}

POST/newsletter/send/documentBeta

Publicar documento (PDF, DOCX, XLSX, etc) em um canal. Document deve ser um data URL base64. FileName define o nome exibido no WhatsApp.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "JID": "120363012345678901@newsletter",
  "Document": "data:application/octet-stream;base64,JVBERi0xLjQK...",
  "FileName": "comunicado-2026.pdf",
  "Caption": "Comunicado oficial",
  "MimeType": "",
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0E5A1C9D6F4B2E8A3",
  "Timestamp": 1711324360
}

Chamadas de VozBeta

Ligar, atender, recusar e encerrar chamadas de voz 1:1 pela instancia, tocando um audio na chamada e opcionalmente gravando o que o outro lado fala. Recurso experimental, liberado apenas para contas habilitadas: contas sem liberacao recebem HTTP 403 ("calls are not enabled for this account"). Fluxo de chamada recebida: o webhook CallOffer traz CallID e From; chame POST /call/answer (ou /call/reject) com esse call_id. Fluxo de chamada feita: POST /call/start devolve o CallID; acompanhe por GET /call/active. Ao terminar, de qualquer lado, chega o webhook CallEnded. Para conversar ao vivo (softphone no navegador, agente de IA de voz, discador), conecte o WebSocket GET /call/stream/{call_id}: ele recebe o audio da pessoa e envia para a chamada o audio que voce mandar, em PCM 16-bit 16 kHz mono. Audio aceito: mp3, wav PCM 16-bit ou ogg/opus, como data URL (data:audio/...;base64,...) ou URL publica (ate 10 MB); e convertido para 16 kHz mono e comeca a tocar quando a midia da chamada conecta.

POST/call/startBeta

Iniciar uma chamada de voz. phone e o numero no formato internacional (somente digitos). audio e record sao opcionais. A resposta volta assim que a oferta e enviada; o audio so toca depois que a pessoa atende. Retorna HTTP 429 quando o servidor atingiu o limite de chamadas simultaneas; nesse caso chamadas recebidas tambem sao recusadas automaticamente. Com relay=true, quem conversa e o agente do motor de voz (PUT /call/relay): o WebSocket do agente abre quando a pessoa atende e relay_params chega no setup em customParameters; audio e record sao ignorados (a gravacao segue a configuracao do motor).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "phone": "5511999999999",
  "audio": "https://exemplo.com/mensagem.mp3",
  "record": true
}
// ou, com o motor de voz:
{
  "phone": "5511999999999",
  "relay": true,
  "relay_params": { "conversation_id": "...", "reason": "confirmacao_consulta" }
}

Response

{
  "Details": "Calling",
  "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "Peer": "5511999999999@s.whatsapp.net",
  "Recording": true,
  "StreamPath": "/call/stream/A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

POST/call/answerBeta

Atender uma chamada recebida que esta tocando. call_id vem do webhook CallOffer (campo CallID) ou de GET /call/active. Retorna 404 se a chamada nao existe mais. Com relay=true, o motor de voz atende e o agente conversa (503 se o agente nao responder); com auto_answer ligado no motor, as chamadas sao atendidas sem chamar esta rota.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "call_id": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "audio": "data:audio/mpeg;base64,SUQzBAAAAAAA...",
  "record": true
}

Response

{
  "Details": "Answered",
  "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "Recording": true,
  "StreamPath": "/call/stream/A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

POST/call/reject

Recusar uma chamada recebida. call_from e o campo From do webhook CallOffer. Disponivel para todas as contas (nao exige liberacao).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "call_id": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "call_from": "5511999999999@s.whatsapp.net"
}

Response

{
  "Details": "Call rejected",
  "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

POST/call/hangupBeta

Encerrar uma chamada em andamento (ou cancelar uma que ainda esta chamando). Retorna 404 se a chamada nao existe mais.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "call_id": "A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

Response

{
  "Details": "Hung up",
  "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90"
}

GET/call/activeBeta

Listar as chamadas ativas da instancia. State pode ser calling, ringing, connecting, active, waiting_room ou ended. Peer pode vir como @lid em vez do numero.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Calls": [
    {
      "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
      "Peer": "123456789012345@lid",
      "State": "ringing",
      "Video": false
    }
  ]
}

GET/call/stream/{call_id}?token=SEU_TOKEN&hangup_on_close=trueBeta

WebSocket de audio ao vivo da chamada (wss:// em producao). Autentique com o header token ou, no navegador, com ?token= na URL. Conecte antes de chamar /call/answer para nao perder o inicio, ou logo apos /call/start. Mensagens binarias sao audio PCM s16le, 16 kHz, mono, nos dois sentidos: o servidor envia frames de 60 ms (960 amostras, 1920 bytes) com a voz da pessoa; voce envia audio em qualquer tamanho de pacote, que e bufferizado (ate 60 s) e tocado em tempo real, com silencio quando o buffer esvazia. Mensagens de texto sao JSON de controle. Uma conexao por chamada: uma nova substitui a anterior (codigo 1008). Por padrao, fechar o socket nao desliga a chamada; use hangup_on_close=true para desligar junto. Com stream ativo, o audio de arquivo (campo audio) e ignorado. A gravacao (record) continua funcionando em paralelo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

// Voce -> servidor
<binario>  audio PCM s16le 16 kHz mono (qualquer tamanho)
{"type": "clear"}    // descarta o audio ainda nao tocado (ex.: usuario interrompeu o agente)
{"type": "hangup"}   // desliga a chamada
{"type": "ping"}     // responde pong com o audio pendente em ms

Response

// Servidor -> voce
{"type": "hello", "call_id": "A1B2...", "peer": "5511999999999@s.whatsapp.net",
 "state": "ringing", "format": {"encoding": "pcm_s16le", "sample_rate": 16000,
 "channels": 1, "frame_samples": 960}}
{"type": "ready"}                       // midia conectada: audio comeca a fluir
{"type": "state", "state": "active"}
{"type": "peer_mute", "muted": true}
{"type": "pong", "buffered_ms": 420}
{"type": "error", "error": "unknown control type: x"}
{"type": "ended", "reason": "hangup"}   // seguido do fechamento normal (1000)
<binario>  frames de 60 ms com a voz da pessoa (1920 bytes)

GET/call/recording/{call_id}Beta

Baixar a gravacao de uma chamada feita ou atendida com record=true. WAV estereo 16 kHz: canal esquerdo e a pessoa no WhatsApp, canal direito e o audio enviado pela plataforma (arquivo, microfone ou stream). Ao terminar a chamada, a gravacao vai para o S3 da instancia (objeto privado, sem link publico) e o webhook CallEnded traz recording_url, um link assinado valido por 24 h. Esta rota devolve um link novo (URL e ExpiresIn em segundos); enquanto o envio ao S3 nao terminou, devolve o arquivo audio/wav direto. 409 enquanto a chamada esta em andamento, 404 se nao houver gravacao.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "URL": "https://synthor-tmp.sfo3.digitaloceanspaces.com/users/.../calls/A1B2....wav?X-Amz-Signature=...",
  "ExpiresIn": 86400
}

Motor de VozBeta

Um agente de IA (da Synthor ou seu) atende e faz ligacoes conversando por voz. O Fala Comigo transcreve a pessoa (STT), manda o texto ao agente num WebSocket e fala a resposta (TTS), cuidando de interrupcao e gravacao. O WebSocket usa o mesmo protocolo do ConversationRelay da Twilio: o agente e o servidor e o Fala Comigo conecta nele. Fala Comigo -> agente: setup (callSid, from, to, direction, callerName, customParameters), prompt (voicePrompt, last=true), interrupt (utteranceUntilInterrupt, durationUntilInterruptMs), hangup (reason), error. Agente -> Fala Comigo: text (token, last, interruptible; pode vir em pedacos), clear, play (source mp3/wav), end (handoffData). A abertura do WebSocket traz x-fc-call-id, x-fc-timestamp e x-hmac-signature = HMAC-SHA256 de '{timestamp}.{call_id}.{path}' com a chave HMAC da instancia; recuse fora da janela de 300 s. Requer conta liberada, chave HMAC configurada na instancia e o servidor com o motor ligado.

PUT/call/relayBeta

Ligar ou atualizar o motor de voz da instancia. url e o WebSocket do seu agente (wss://). auto_answer atende sozinho as chamadas recebidas. tts_provider: edge (padrao, gratis) ou openrouter (Microsoft MAI-Voice); os dois usam a voz pt-BR-FranciscaNeural por padrao e um e reserva do outro. silence_end_ms (200-3000, padrao 600) e o silencio que encerra a fala da pessoa. custom_parameters vai no setup de toda chamada. 412 sem chave HMAC na instancia, 503 sem o motor no servidor, 403 conta nao liberada.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "url": "wss://seu-agente.com/voz",
  "auto_answer": true,
  "welcome_greeting": "Ola! Aqui e a assistente da Clinica X. Esta ligacao pode ser gravada.",
  "language": "pt-BR",
  "tts_provider": "edge",
  "voice": "pt-BR-FranciscaNeural",
  "interruptible": true,
  "record": true,
  "silence_end_ms": 600,
  "custom_parameters": { "canal": "atendimento" }
}

Response

{
  "Details": "Relay configured",
  "Relay": { "url": "wss://seu-agente.com/voz", "auto_answer": true, "tts_provider": "edge", "...": "..." }
}

GET/call/relayBeta

Ver a configuracao do motor de voz da instancia. 404 quando desligado.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Relay": { "url": "wss://seu-agente.com/voz", "auto_answer": true, "...": "..." }
}

DELETE/call/relayBeta

Desligar o motor de voz da instancia.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Details": "Relay removed"
}

GET/call/transcript/{call_id}Beta

Transcricao, uso e metricas de uma chamada com o motor de voz, durante a chamada (InProgress=true) ou depois dela (as ultimas 20 por instancia, em memoria; o registro definitivo vem no webhook CallEnded).

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
  "InProgress": false,
  "Result": {
    "transcript": [
      { "side": "agent", "start_ms": 300, "end_ms": 3100, "text": "Ola! Aqui e a assistente da Clinica X." },
      { "side": "caller", "start_ms": 4200, "end_ms": 6100, "text": "quero remarcar a consulta" }
    ],
    "usage": { "stt": { "provider": "openrouter", "audio_seconds": 1.9, "cost_usd": 0.00001 }, "tts": [ { "provider": "edge", "characters": 61, "cost_usd": 0 } ], "total_cost_usd": 0.00001 },
    "turns": { "turns": 1, "latency_p50_ms": 1650, "latency_p95_ms": 1650, "interruptions": 0 },
    "end_reason": "caller_hangup"
  }
}

Webhook Config

Configurar o webhook da sua instancia para receber eventos em tempo real. events aceita apenas os nomes listados na secao Eventos Disponiveis (nomes invalidos sao ignorados).

POST/webhook

Definir a URL e os eventos do webhook. A URL deve comecar com http:// ou https://.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "webhookurl": "https://seu-servidor.com/webhook",
  "events": ["Message", "ReadReceipt", "ChatPresence", "HistorySync"]
}

Response

{
  "webhook": "https://seu-servidor.com/webhook"
}

GET/webhook

Ver a configuracao atual do webhook (URL e eventos inscritos).

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "webhook": "https://seu-servidor.com/webhook",
  "subscribe": ["Message", "ReadReceipt", "ChatPresence", "HistorySync"]
}

PUT/webhook

Atualizar parcialmente a configuracao do webhook. Envie webhook e/ou events para altera-los. Use active=false para desativar (limpa URL e eventos) sem apagar o registro.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "webhook": "https://seu-servidor.com/novo-webhook",
  "events": ["Message"],
  "active": true
}

Response

{
  "webhook": "https://seu-servidor.com/novo-webhook",
  "events": ["Message"],
  "active": true
}

DELETE/webhook

Remover a configuracao de webhook. Voce deixara de receber eventos.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Details": "Webhook and events deleted successfully"
}

Webhook Payload

Quando um evento ocorre, a API envia um POST para a URL do seu webhook com o payload abaixo. Seu servidor deve retornar status 200 para confirmar o recebimento.

Estrutura do Payload

Todos os eventos seguem a mesma estrutura base. O campo type identifica o tipo de evento e event contem os dados.

Campo	Tipo	Descricao
`type`	string	Tipo do evento (Message, ReadReceipt, etc)
`event`	object	Dados do evento (Info + Message)
`event.Info`	object	Metadados: Chat, ID, Sender, Timestamp, Type, etc
`event.Message`	object	Conteudo da mensagem (conversation, imageMessage, etc)
`instanceName`	string	Nome da instancia que gerou o evento
`userID`	string	UUID da instancia

Exemplo: Mensagem de Texto

POST para seu webhook

{
  "event": {
    "Info": {
      "Chat": "5521999999999@s.whatsapp.net",
      "ID": "3A2C03BB065D687AF9F8",
      "IsFromMe": false,
      "IsGroup": false,
      "PushName": "Joao Silva",
      "Sender": "5521999999999@lid",
      "SenderAlt": "5521999999999@s.whatsapp.net",
      "Timestamp": "2026-03-24T23:51:05-03:00",
      "Type": "text"
    },
    "Message": {
      "conversation": "Ola, tudo bem?"
    }
  },
  "instanceName": "minha-instancia",
  "type": "Message",
  "userID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Exemplo: Mensagem com Imagem

POST para seu webhook

{
  "event": {
    "Info": {
      "Chat": "5521999999999@s.whatsapp.net",
      "ID": "3A5B07CC189E2D4AF1C3",
      "IsFromMe": false,
      "IsGroup": false,
      "PushName": "Maria Santos",
      "Sender": "5521999999999@lid",
      "SenderAlt": "5521999999999@s.whatsapp.net",
      "Timestamp": "2026-03-24T23:55:12-03:00",
      "Type": "image",
      "MediaType": "image"
    },
    "Message": {
      "imageMessage": {
        "url": "https://mmg.whatsapp.net/v/...",
        "directPath": "/v/t62.7118-24/...",
        "mimetype": "image/jpeg",
        "caption": "Olha essa foto!",
        "fileSha256": "...",
        "fileEncSha256": "...",
        "mediaKey": "...",
        "fileLength": 45230,
        "height": 1080,
        "width": 1920,
        "jpegThumbnail": "/9j/4AAQ..."
      }
    }
  },
  "instanceName": "minha-instancia",
  "type": "Message",
  "userID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Exemplo: Mensagem em Grupo

POST para seu webhook

{
  "event": {
    "Info": {
      "Chat": "120363012345678901@g.us",
      "ID": "3A7D09EE291F4B6AC5E7",
      "IsFromMe": false,
      "IsGroup": true,
      "PushName": "Carlos Souza",
      "Sender": "5511777777777@lid",
      "SenderAlt": "5511777777777@s.whatsapp.net",
      "Timestamp": "2026-03-25T10:30:00-03:00",
      "Type": "text"
    },
    "Message": {
      "conversation": "Bom dia pessoal!"
    }
  },
  "instanceName": "minha-instancia",
  "type": "Message",
  "userID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Exemplo: Chamada Recebida (CallOffer)

POST para seu webhook

{
  "event": {
    "From": "5511999999999@s.whatsapp.net",
    "Timestamp": "2026-10-09T12:40:00-03:00",
    "CallCreator": "123456789012345@lid",
    "CallCreatorAlt": "5511999999999@s.whatsapp.net",
    "CallID": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
    "GroupJID": "",
    "RemotePlatform": "android",
    "RemoteVersion": "2.26.20.1",
    "Data": { "Tag": "offer", "Attrs": { "...": "..." }, "Content": ["..."] }
  },
  "instanceName": "minha-instancia",
  "type": "CallOffer",
  "userID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Exemplo: Chamada Finalizada (CallEnded)Beta

POST para seu webhook

{
  "event": {
    "call_id": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
    "peer": "123456789012345@lid",
    "reason": "hangup",
    "duration_s": 42,
    "direction": "inbound",
    "recording_url": "https://...digitaloceanspaces.com/users/.../calls/A1B2....wav?X-Amz-Signature=...",
    "relay": true,
    "transcript": [
      { "side": "caller", "start_ms": 4200, "end_ms": 6100, "text": "quero remarcar a consulta" },
      { "side": "agent", "start_ms": 7800, "end_ms": 10400, "text": "Claro! Tenho terca as 10h." }
    ],
    "usage": { "stt": { "provider": "openrouter", "model": "openai/whisper-large-v3-turbo", "audio_seconds": 18.4, "requests": 6, "cost_usd": 0.00009 }, "tts": [ { "provider": "edge", "model": "pt-BR-FranciscaNeural", "characters": 412, "requests": 7, "cost_usd": 0 } ], "total_cost_usd": 0.00009 },
    "turns": { "turns": 6, "latency_p50_ms": 1700, "latency_p95_ms": 2400, "interruptions": 1 },
    "end_reason": "caller_hangup"
  },
  "instanceName": "minha-instancia",
  "type": "CallEnded",
  "userID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Eventos Disponiveis

Lista completa de eventos que podem ser configurados no webhook. Use o array events no POST /webhook para se inscrever nos eventos desejados.

Evento	Descricao
`Message`	Nova mensagem recebida (texto, midia, etc)
`UndecryptableMessage`	Mensagem recebida que nao pode ser descriptografada
`Receipt`	Confirmacao de entrega/leitura de mensagem
`MediaRetry`	Tentativa de reenvio de midia
`ReadReceipt`	Confirmacao de leitura (tique azul)
`GroupInfo`	Alteracao nas informacoes de um grupo (nome, topico, participantes, etc)
`JoinedGroup`	A instancia entrou em um novo grupo
`Picture`	Foto de perfil (de usuario ou grupo) alterada
`BlocklistChange`	Alteracao na lista de bloqueados
`Blocklist`	Estado atual da lista de bloqueados
`Connected`	Sessao conectada ao WhatsApp
`Disconnected`	Sessao desconectada
`ConnectFailure`	Falha ao conectar
`KeepAliveRestored`	Keep-alive restaurado
`KeepAliveTimeout`	Timeout do keep-alive
`QRTimeout`	Tempo do QR code expirou
`LoggedOut`	Logout realizado (sessao encerrada pelo WhatsApp ou pelo usuario)
`ClientOutdated`	Versao do cliente desatualizada
`TemporaryBan`	Banimento temporario da conta
`StreamError`	Erro no stream de conexao
`StreamReplaced`	Stream de conexao substituido (conectado em outro lugar)
`PairSuccess`	Pareamento bem-sucedido
`PairError`	Falha no pareamento
`QR`	Novo QR code disponivel para escaneamento
`QRScannedWithoutMultidevice`	QR escaneado sem multidispositivo habilitado
`PrivacySettings`	Alteracao nas configuracoes de privacidade
`PushNameSetting`	Alteracao do nome de exibicao (push name)
`UserAbout`	Alteracao do status/recado de um usuario
`AppState`	Atualizacao de estado do app (app state)
`AppStateSyncComplete`	Sincronizacao de app state concluida
`HistorySync`	Sincronizacao de historico de mensagens
`OfflineSyncCompleted`	Sincronizacao offline concluida
`OfflineSyncPreview`	Previa da sincronizacao offline
`CallOffer`	Oferta de chamada recebida
`CallAccept`	Chamada aceita
`CallTerminate`	Chamada encerrada
`CallOfferNotice`	Aviso de oferta de chamada
`CallRelayLatency`	Latencia de relay da chamada
`CallEnded`	BETA: chamada de voz finalizada (so para contas com Chamadas de Voz liberadas). Traz call_id, peer, reason (hangup quando encerrada pela API, rejected, offer_failed ou o motivo enviado pelo WhatsApp) e duration_s
`Presence`	Presenca global de um contato (online/offline)
`ChatPresence`	Indicador de presenca em conversa (digitando, gravando)
`IdentityChange`	Alteracao de identidade (chave de seguranca) de um contato
`CATRefreshError`	Erro ao atualizar o token CAT
`NewsletterJoin`	Entrada em canal (newsletter)
`NewsletterLeave`	Saida de canal (newsletter)
`NewsletterMuteChange`	Alteracao de mudo em canal
`NewsletterLiveUpdate`	Atualizacao em tempo real de canal
`NewsletterMessage`	Nova mensagem em canal (inclua 'NewsletterMessage' nos events para receber)
`FBMessage`	Mensagem originada do Facebook/Messenger
`All`	Inscreve-se em todos os eventos disponiveis

Formato de Numero

Todos os campos de telefone devem seguir o formato internacional sem o sinal de +.

Numeros individuais

Codigo do pais + DDD + numero, sem espacos, tracos ou parenteses.

Formato	Exemplo	Descricao
`5511999999999`	Brasil, SP, celular	55 (BR) + 11 (SP) + 999999999
`5521999999999`	Brasil, RJ, celular	55 (BR) + 21 (RJ) + 999999999
`14155552671`	EUA	1 (US) + 415 + 5552671

Grupos e Canais

Grupos usam JID terminando em @g.us e canais (newsletters) terminando em @newsletter.

Formato de grupo e canal

"Group": "120363012345678901@g.us"
"JID":   "120363012345678901@newsletter"

Voce obtem os JIDs via GET /group/list, GET /newsletter/list ou GET /jid/list.

Nao use o sinal de + no inicio do numero. Nao inclua espacos, tracos ou parenteses. O formato incorreto causara erro na API.

ContextInfo (Respostas e Mencoes)

O campo ContextInfo e usado para responder a mensagens especificas e mencionar usuarios. E opcional em todos os endpoints de envio.

Campos

Campo	Tipo	Descricao
`StanzaId`	string	ID da mensagem que esta sendo respondida (quote). Exige Participant.
`Participant`	string	JID do autor da mensagem original. Obrigatorio junto com StanzaId.
`MentionedJID`	string[]	Lista de JIDs dos usuarios mencionados na mensagem

Exemplo: Responder a uma mensagem

Para responder (quote) uma mensagem, inclua o ContextInfo com StanzaId e Participant.

Request Body com resposta

{
  "Phone": "5511999999999",
  "Body": "Respondendo a sua mensagem!",
  "ContextInfo": {
    "StanzaId": "3EB0A8C2F6B2D4A1C3E5",
    "Participant": "5521999999999@s.whatsapp.net"
  }
}

Exemplo: Mencionar usuarios

Para mencionar usuarios, inclua o MentionedJID. Use @numero no texto para exibir a mencao.

Request Body com mencoes

{
  "Phone": "120363012345678901@g.us",
  "Body": "Ola @5521999999999 e @5511888888888, vamos alinhar?",
  "ContextInfo": {
    "MentionedJID": [
      "5521999999999@s.whatsapp.net",
      "5511888888888@s.whatsapp.net"
    ]
  }
}

Estrutura completa do ContextInfo

ContextInfo

{
  "StanzaId": "3EB0A8C2F6B2D4A1C3E5",
  "Participant": "5521999999999@s.whatsapp.net",
  "MentionedJID": [
    "5521999999999@s.whatsapp.net",
    "5511888888888@s.whatsapp.net"
  ]
}