API Reference v1

Documentacao 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 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.

Sessao

Gerenciar a conexao da sua instancia com o WhatsApp.

POST/session/connect

Conectar ao WhatsApp. Inicia a sessao e retorna as informacoes de conexao. Se nao houver sessao ativa, retorna um QR code para escaneamento.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{}

Response

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

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 atual, incluindo estado de conexao, JID, nome, QR code (se disponivel) e configuracoes de webhook.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "connected": true,
  "loggedIn": true,
  "jid": "5511999999999@s.whatsapp.net",
  "qrcode": "",
  "name": "Minha Empresa",
  "webhook": "https://seu-servidor.com/webhook",
  "events": ["Message", "ReadReceipt", "ChatPresence"]
}

GET/session/qr

Retorna o QR code atual em formato base64 (imagem PNG). Use apos /session/connect quando a sessao ainda nao foi autenticada.

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

Enviar Mensagens

Endpoints para enviar diferentes tipos de mensagem. Todos retornam o ID da mensagem enviada e timestamp.

POST/chat/send/text

Enviar mensagem de texto. Suporta preview de links e resposta a mensagens.

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. Aceita URL publica ou base64 da imagem.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

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

POST/chat/send/audio

Enviar audio. Use PTT=true para enviar como mensagem de voz (bolinha verde). Suporta metadados de duracao e waveform.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Audio": "https://exemplo.com/audio.ogg",
  "PTT": true,
  "MimeType": "audio/ogg; codecs=opus",
  "Seconds": 15,
  "Waveform": [0, 5, 12, 25, 40, 55, 60, 45, 30, 15, 5],
  "Id": "",
  "ContextInfo": {}
}

Response

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

POST/chat/send/video

Enviar video com legenda opcional e thumbnail JPEG.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

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

POST/chat/send/document

Enviar documento (PDF, DOCX, XLSX, etc). O campo FileName define o nome exibido no WhatsApp.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Document": "https://exemplo.com/contrato.pdf",
  "FileName": "contrato-2026.pdf",
  "Id": "",
  "ContextInfo": {}
}

Response

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

POST/chat/send/sticker

Enviar sticker (figurinha). Aceita WebP, PNG ou GIF. Campos opcionais de metadados do pack.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Sticker": "https://exemplo.com/sticker.webp",
  "PngThumbnail": "",
  "MimeType": "image/webp",
  "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. O campo 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/template

Enviar mensagem com botoes interativos (template). Cada botao pode ser URL, numero de telefone ou resposta rapida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Content": "Como podemos ajudar voce hoje?",
  "Footer": "Fala Comigo API",
  "Buttons": [
    {
      "DisplayText": "Visitar site",
      "Type": "url",
      "Url": "https://falacomigo.com"
    },
    {
      "DisplayText": "Ligar para suporte",
      "Type": "phone",
      "PhoneNumber": "+5511999999999"
    },
    {
      "DisplayText": "Responder",
      "Type": "quick_reply"
    }
  ],
  "Id": ""
}

Response

{
  "Details": "Sent",
  "Id": "3EB0C7E9A3B5D2F4C8E1",
  "Timestamp": 1711324460
}

POST/chat/send/buttons

Enviar mensagem simples com botoes de resposta rapida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "Body": "Escolha uma opcao abaixo:",
  "Id": "",
  "ContextInfo": {}
}

Response

{
  "Details": "Sent",
  "Id": "3EB0D1F2A4B6C3E5D9F2",
  "Timestamp": 1711324485
}

POST/chat/send/list

Enviar lista selecionavel com titulo, descricao e itens agrupados.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999",
  "ButtonText": "Ver opcoes",
  "Desc": "Selecione um servico",
  "TopText": "Nossos Servicos",
  "FooterText": "Fala Comigo",
  "List": [
    {
      "title": "Plano Basico",
      "desc": "Ate 1.000 mensagens/mes",
      "RowId": "plano_basico"
    },
    {
      "title": "Plano Pro",
      "desc": "Ate 10.000 mensagens/mes",
      "RowId": "plano_pro"
    },
    {
      "title": "Plano Enterprise",
      "desc": "Mensagens ilimitadas",
      "RowId": "plano_enterprise"
    }
  ]
}

Response

{
  "Details": "Sent",
  "Id": "3EB0E4A5B7C8D1F3E2A6",
  "Timestamp": 1711324510
}

POST/chat/send/poll

Enviar enquete (poll) em um grupo. 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": "Sent",
  "Id": "3EB0F7B8C9D2E4A5F3B7",
  "Timestamp": 1711324535
}

POST/chat/send/edit

Editar uma mensagem ja enviada. Informe o Id da mensagem original e o novo texto.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Id": "3EB0A8C2F6B2D4A1C3E5",
  "Phone": "5511999999999",
  "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. Envia o indicador de leitura (tique azul) ao remetente.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Read"
}

POST/chat/react

Enviar reacao (emoji) a uma mensagem. O campo Body deve conter o emoji da reacao.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Reacted"
}

POST/chat/delete

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

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Deleted"
}

POST/chat/presence

Enviar indicador de presenca. State pode ser: composing (digitando), recording (gravando audio) ou paused.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Set"
}

POST/chat/archive

Arquivar ou desarquivar uma conversa. Use Archive=true para arquivar e false para desarquivar.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Archived"
}

GET/chat/history?phone=5511999999999

Obter historico de mensagens de uma conversa. Passe o numero como query parameter.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "messages": [
    {
      "Id": "3EB0A8C2F6B2D4A1C3E5",
      "Timestamp": 1711324200,
      "FromMe": false,
      "Body": "Ola, tudo bem?",
      "Type": "text",
      "PushName": "Joao Silva"
    },
    {
      "Id": "3EB0B7D1E4A3C2F5D8B1",
      "Timestamp": 1711324265,
      "FromMe": true,
      "Body": "Tudo otimo! Como posso ajudar?",
      "Type": "text"
    }
  ]
}

Download de Midia

Baixar arquivos de midia recebidos em mensagens. Informe o Phone e o Id da mensagem que contem a midia.

POST/chat/downloadimage

Baixar imagem de uma mensagem recebida. Retorna a midia em base64.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "MimeType": "image/jpeg",
  "Data": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "Filename": ""
}

POST/chat/downloadvideo

Baixar video de uma mensagem recebida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "MimeType": "video/mp4",
  "Data": "AAAAIGZ0eXBpc29t...",
  "Filename": ""
}

POST/chat/downloadaudio

Baixar audio de uma mensagem recebida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "MimeType": "audio/ogg; codecs=opus",
  "Data": "T2dnUwACAAAAAAAA...",
  "Filename": ""
}

POST/chat/downloaddocument

Baixar documento de uma mensagem recebida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "MimeType": "application/pdf",
  "Data": "JVBERi0xLjQKJcfs...",
  "Filename": "relatorio.pdf"
}

POST/chat/downloadsticker

Baixar sticker de uma mensagem recebida.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "MimeType": "image/webp",
  "Data": "UklGRlYAAABXRUJQ...",
  "Filename": ""
}

Usuarios

Obter informacoes sobre contatos e usuarios do WhatsApp.

POST/user/info

Obter informacoes detalhadas de um usuario (nome, status, foto, etc).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999"
}

Response

{
  "JID": "5511999999999@s.whatsapp.net",
  "Status": "Disponivel",
  "PictureID": "1234567890",
  "Devices": [],
  "VerifiedName": ""
}

POST/user/check

Verificar se um numero possui conta no WhatsApp. Util para validar numeros antes de enviar mensagens.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999"
}

Response

{
  "IsOnWhatsApp": true,
  "JID": "5511999999999@s.whatsapp.net"
}

POST/user/avatar

Obter a foto de perfil de um usuario em URL publica.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Phone": "5511999999999"
}

Response

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

GET/user/contacts

Listar todos os contatos salvos na agenda do WhatsApp conectado.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "contacts": [
    {
      "JID": "5511999999999@s.whatsapp.net",
      "Name": "Joao Silva",
      "PushName": "Joao",
      "BusinessName": ""
    },
    {
      "JID": "5511888888888@s.whatsapp.net",
      "Name": "Maria Santos",
      "PushName": "Maria",
      "BusinessName": "Loja da Maria"
    }
  ]
}

POST/user/presence

Definir sua presenca no WhatsApp (disponivel ou indisponivel).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Presence": "available"
}

Response

{
  "Details": "Set"
}

Grupos

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

POST/group/create

Criar um novo grupo com os participantes informados.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Subject": "Equipe Comercial",
  "Participants": [
    "5511999999999",
    "5511888888888"
  ]
}

Response

{
  "Group": "120363012345678901@g.us",
  "Details": "Created"
}

GET/group/list

Listar todos os grupos em que a instancia participa.

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "groups": [
    {
      "JID": "120363012345678901@g.us",
      "Name": "Equipe Comercial",
      "ParticipantCount": 5
    }
  ]
}

GET/group/info?group=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",
  "Created": 1711324000,
  "Owner": "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?group=120363012345678901@g.us

Obter o link de convite do grupo.

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 de convite (sem entrar).

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "InviteLink": "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 de convite.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Joined",
  "Group": "120363012345678901@g.us"
}

POST/group/leave

Sair de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Left"
}

POST/group/name

Alterar o nome (assunto) de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Updated"
}

POST/group/topic

Alterar a descricao (topico) de um grupo.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Updated"
}

POST/group/photo

Alterar a foto de um grupo. Envie a imagem como URL ou base64.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Group": "120363012345678901@g.us",
  "Photo": "https://exemplo.com/grupo-foto.jpg"
}

Response

{
  "Details": "Updated",
  "PictureID": "9876543210"
}

POST/group/announce

Ativar ou desativar modo de anuncio. Quando ativado, somente admins podem enviar mensagens.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Updated"
}

POST/group/locked

Bloquear ou desbloquear edicao de informacoes do grupo. Quando bloqueado, somente admins podem editar.

Header: token: {instance_token}

Mostrar exemplos

Request Body

{
  "Group": "120363012345678901@g.us",
  "Locked": true
}

Response

{
  "Details": "Updated"
}

POST/group/updateparticipants

Adicionar, remover, promover ou rebaixar participantes. Action: add, remove, promote, demote.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Updated",
  "Participants": [
    {
      "JID": "5511777777777@s.whatsapp.net",
      "Status": "200"
    },
    {
      "JID": "5511666666666@s.whatsapp.net",
      "Status": "200"
    }
  ]
}

Webhook Config

Configurar o webhook da sua instancia para receber eventos em tempo real.

POST/webhook

Configurar a URL e os eventos do webhook. A URL deve ser HTTPS e acessivel publicamente.

Header: token: {instance_token}

Mostrar exemplos

Request Body

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

Response

{
  "Details": "Webhook updated"
}

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"
  ]
}

DELETE/webhook

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

Header: token: {instance_token}

Mostrar exemplos

Response

{
  "Details": "Webhook removed"
}

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/...",
        "mimetype": "image/jpeg",
        "caption": "Olha essa foto!",
        "fileSha256": "...",
        "fileLength": 45230,
        "height": 1080,
        "width": 1920,
        "mediaKey": "...",
        "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.

Evento	Descricao
`Message`	Nova mensagem recebida (texto, midia, etc)
`ReadReceipt`	Confirmacao de leitura (tique azul)
`ChatPresence`	Indicador de presenca (digitando, gravando)
`HistorySync`	Sincronizacao de historico de mensagens
`Receipt`	Confirmacao de entrega de mensagem
`Call`	Chamada de voz ou video recebida
`CallOffer`	Oferta de chamada recebida
`CallAccept`	Chamada aceita
`CallTerminate`	Chamada encerrada
`CallReject`	Chamada rejeitada
`GroupParticipants`	Alteracao de participantes em grupo
`GroupName`	Nome do grupo alterado
`GroupTopic`	Descricao do grupo alterada
`GroupAnnounce`	Modo de anuncio do grupo alterado
`GroupLocked`	Bloqueio de edicao do grupo alterado
`GroupPhoto`	Foto do grupo alterada
`GroupDelete`	Grupo excluido
`Picture`	Foto de perfil alterada
`PairSuccess`	Pareamento via codigo bem-sucedido
`Connected`	Sessao conectada ao WhatsApp
`Disconnected`	Sessao desconectada
`LoggedOut`	Logout realizado
`StreamReplaced`	Stream de conexao substituido
`KeepAliveTimeout`	Timeout do keep-alive
`KeepAliveRestored`	Keep-alive restaurado
`Reaction`	Reacao (emoji) em mensagem
`MediaRetry`	Tentativa de reenvio de midia
`BlocklistChange`	Alteracao na lista de bloqueados
`BlocklistEvent`	Evento de bloqueio/desbloqueio
`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
`PollVote`	Voto em enquete
`PrivacySettings`	Alteracao nas configuracoes de privacidade

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

Grupos usam o formato JID do WhatsApp, terminando em @g.us.

Formato de grupo

"Group": "120363012345678901@g.us"

Voce obtem o JID do grupo via GET /group/list ou GET /group/info.

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)
`Participant`	string	JID do autor da mensagem original (para grupos)
`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"
  ]
}