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.

AutenticacaoSessaoEnviar MensagensChatDownload de MidiaUsuariosGruposNewsletter (Canais)Webhook ConfigWebhook PayloadEventosFormato de NumeroContextInfo

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
}

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.

CampoTipoDescricao
typestringTipo do evento (Message, ReadReceipt, etc)
eventobjectDados do evento (Info + Message)
event.InfoobjectMetadados: Chat, ID, Sender, Timestamp, Type, etc
event.MessageobjectConteudo da mensagem (conversation, imageMessage, etc)
instanceNamestringNome da instancia que gerou o evento
userIDstringUUID 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"
}

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.

EventoDescricao
MessageNova mensagem recebida (texto, midia, etc)
UndecryptableMessageMensagem recebida que nao pode ser descriptografada
ReceiptConfirmacao de entrega/leitura de mensagem
MediaRetryTentativa de reenvio de midia
ReadReceiptConfirmacao de leitura (tique azul)
GroupInfoAlteracao nas informacoes de um grupo (nome, topico, participantes, etc)
JoinedGroupA instancia entrou em um novo grupo
PictureFoto de perfil (de usuario ou grupo) alterada
BlocklistChangeAlteracao na lista de bloqueados
BlocklistEstado atual da lista de bloqueados
ConnectedSessao conectada ao WhatsApp
DisconnectedSessao desconectada
ConnectFailureFalha ao conectar
KeepAliveRestoredKeep-alive restaurado
KeepAliveTimeoutTimeout do keep-alive
QRTimeoutTempo do QR code expirou
LoggedOutLogout realizado (sessao encerrada pelo WhatsApp ou pelo usuario)
ClientOutdatedVersao do cliente desatualizada
TemporaryBanBanimento temporario da conta
StreamErrorErro no stream de conexao
StreamReplacedStream de conexao substituido (conectado em outro lugar)
PairSuccessPareamento bem-sucedido
PairErrorFalha no pareamento
QRNovo QR code disponivel para escaneamento
QRScannedWithoutMultideviceQR escaneado sem multidispositivo habilitado
PrivacySettingsAlteracao nas configuracoes de privacidade
PushNameSettingAlteracao do nome de exibicao (push name)
UserAboutAlteracao do status/recado de um usuario
AppStateAtualizacao de estado do app (app state)
AppStateSyncCompleteSincronizacao de app state concluida
HistorySyncSincronizacao de historico de mensagens
OfflineSyncCompletedSincronizacao offline concluida
OfflineSyncPreviewPrevia da sincronizacao offline
CallOfferOferta de chamada recebida
CallAcceptChamada aceita
CallTerminateChamada encerrada
CallOfferNoticeAviso de oferta de chamada
CallRelayLatencyLatencia de relay da chamada
PresencePresenca global de um contato (online/offline)
ChatPresenceIndicador de presenca em conversa (digitando, gravando)
IdentityChangeAlteracao de identidade (chave de seguranca) de um contato
CATRefreshErrorErro ao atualizar o token CAT
NewsletterJoinEntrada em canal (newsletter)
NewsletterLeaveSaida de canal (newsletter)
NewsletterMuteChangeAlteracao de mudo em canal
NewsletterLiveUpdateAtualizacao em tempo real de canal
NewsletterMessageNova mensagem em canal (inclua 'NewsletterMessage' nos events para receber)
FBMessageMensagem originada do Facebook/Messenger
AllInscreve-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.

FormatoExemploDescricao
5511999999999Brasil, SP, celular55 (BR) + 11 (SP) + 999999999
5521999999999Brasil, RJ, celular55 (BR) + 21 (RJ) + 999999999
14155552671EUA1 (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

CampoTipoDescricao
StanzaIdstringID da mensagem que esta sendo respondida (quote). Exige Participant.
ParticipantstringJID do autor da mensagem original. Obrigatorio junto com StanzaId.
MentionedJIDstring[]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"
  ]
}