Aparência e comportamentos automáticos da instância.
Token da instância
Credencial desta instância pra integrações (header apikey).
Gerar um novo token invalida o atual na hora. Atualize as integrações que o usam.
Identidade
Nome e avatar exibidos no painel.
PNG, JPG, WebP ou SVG. Até ~1.5 MB.
Comportamentos automáticos
Saída da conexão
Aplicar encerra a conexão atual e reconecta pela saída escolhida, mantendo o pareamento. Com proxy, se ele cair a instância fica sem conexão (não sai pelo servidor).
Conversas
Selecione uma conversa para ver as mensagens.
0/0
Carregando mensagens antigas…
início da conversa
Solte aqui pra enviar
Imagens, vídeos, áudios ou documentos (até 16MB)
↩ resposta
📍 Localização compartilhada
👤 Contato ·
Sem mensagens ainda nesse chat.
Webhooks
Endpoints HTTP que recebem os eventos desta instância.
Adicionar webhook
Nenhum evento bate com ""
Alterações não salvas neste webhook.
Desativado, não recebe eventos
Carregando saúde…
✓ Teste OK✗ Teste falhou
Nenhum evento bate com a busca
Nenhum webhook configurado
Adicione uma URL pra receber eventos como mensagens recebidas, status de entrega e mudanças de conexão em tempo real.
Documentação da API
Integre seu sistema, n8n ou qualquer cliente HTTP. Corpo e respostas em JSON.
Base URL
ID desta instância
Autenticação
Toda chamada leva a credencial no header apikey (também vale Authorization: Bearer). Há duas credenciais:
ORGapi_key da organização
Cria, lista e apaga as instâncias da sua org. Também opera qualquer instância dela. Fica no painel, em Configurações, Chave de API (lá também dá pra gerar uma nova).
TOKENToken da instância
Opera uma instância só: conexão, mensagens, conversas e webhooks. Vem na resposta do POST /instance, no botão Token do Dashboard e em Configurações gerais, onde também dá pra gerar um novo.
{id}
Nas rotas, aceita o ID ou o nome da instância.
?apikey=
Alternativa ao header onde não dá para mandar header: <img>, <audio>, <video> e WebSocket.
master key
Existe só para o administrador da plataforma e não entra nesta documentação.
Exemplo
curl /instance \
-H "apikey: SUA_API_KEY"
Instâncias
POST/instanceORG
Cria uma instância na sua org (a org vem da api_key). Nome até 60 caracteres, único na org. Respeita o limite de instâncias da org.
Erros: 403 quota_exceeded (limite da org), 409 conflict (nome já existe).
GET/instanceORG
Lista as instâncias da org, com status real da conexão.
GET/instance/{id}TOKEN
Detalhes, status e settings. last_event_at é o último evento recebido do WhatsApp (ajuda a ver conexão parada).
DELETE/instance/{id}ORG
Desconecta, desfaz o pareamento e apaga a instância. Irreversível. Resposta 204.
POST/instance/{id}/rotate-tokenORG
Gera um novo token da instância e devolve a instância com ele. O token antigo para de valer na hora. Só com a api_key da org: o próprio token não troca a si mesmo (403).
GET/auth/org-api-keyORG
Devolve a api_key da org: { "api_key": "..." }.
POST/auth/org-rotate-keyORG
Gera uma nova api_key e devolve { "api_key": "..." }. A antiga para de valer na hora; os tokens das instâncias não mudam.
PUT/instance/{id}/nameTOKEN
{ "name": "loja-sp" }
PUT/instance/{id}/avatarTOKEN
Imagem da instância no painel. Aceita URL, data URI base64 (até 2 MB) ou preset. Vazio volta para as iniciais.
{ "avatar": "preset:flame" }
PUT/instance/{id}/settingsTOKEN
Atualização parcial: mande só o que muda, campos omitidos mantêm o valor atual. Devolve as settings completas já gravadas.
reject_calls
Rejeita chamadas automaticamente.
ignore_groups
Descarta mensagens de grupo: não grava e não dispara evento.
always_online
Mantém a presença como online.
auto_read_messages
Marca as mensagens recebidas como lidas.
auto_read_status
Marca os status recebidos como vistos.
typing_simulation
Antes de cada envio mostra "digitando" (ou "gravando" no áudio) por um tempo humano.
typing_min_ms
Espera mínima em ms. 0 usa o padrão (900).
typing_max_ms
Espera máxima em ms. 0 usa o padrão (6000).
daily_message_limit
Fica gravado, mas não bloqueia envio. O teto que bloqueia é o diário da org, definido pelo administrador.
Uma mensagem gravada, no mesmo formato do histórico.
GET/messages/{id}/searchTOKEN
Busca por texto. Parâmetros: q (obrigatório), chat (opcional), limit (padrão 50, máximo 200). Cada resultado traz snippet com o termo em <mark>.
GET/messages/{id}/storedTOKEN
Tudo que o servidor gravou desde um instante, na ordem de gravação. Serve para recuperar o que chegou durante uma queda (fila offline e histórico do celular).
since
RFC3339 (obrigatório): gravadas a partir deste instante.
min_timestamp
RFC3339: piso do horário da mensagem. Padrão = since, no máximo 31 dias atrás.
O teto de números por chamada e por minuto vem da configuração do servidor: 400 too_many_numbers e 429 rate_limited (Retry-After: 60). Consulta em massa parece lista fria e pode banir o número: confira só quem vai receber mensagem.
Avisos do WhatsApp (ban temporário, trava, restrição de contato novo) e falhas de envio, do mais novo ao mais antigo. ?limit= padrão 100, máximo 500. ?since= RFC3339.
Reenvia o payload guardado para a URL atual. Uma tentativa, sem nova fila. Como o histórico guarda só 8 KB, entrega maior (ex.: com base64) volta cortada.
POST/webhook/{id}/{webhookId}/testTOKEN
Manda um POST de teste (evento webhook.test). ?type=ctwa simula a primeira mensagem de um lead vindo de anúncio. Retry e teste respondem:
Saúde das entregas. ?since= é uma duração, padrão 24h (ex.: 168h para 7 dias). Campos: total, success, failed, success_rate (0 a 1, -1 sem entregas).
Entrega
POST com JSON. Por padrão: timeout de 10 s e até 3 tentativas, com espera de 1 s e depois 3 s. Resposta 2xx ou 3xx conta como sucesso. Toda entrega fica no histórico.
Para rotear, use o header X-Webhook-Event (ou event no WebSocket): ele sempre traz o nome desta lista. O campo type do corpo pode vir com nome antigo em alguns eventos.
Formato dos eventos
Corpo plano. Todo evento traz type, instanceId, instanceName, connectedPhone e timestamp em milissegundos. Em grupo vem também participantPhone (quem enviou).
message.received: texto
fromMe: true quando a mensagem saiu do celular ou de outro aparelho conectado. Envios pela API disparam message.sent. quotedStanzaId aparece quando a mensagem responde outra. offline: true quando chegou pela fila de recuperação após uma queda.
Quando o lead chega por um anúncio de clique para WhatsApp do Meta, a primeira mensagem dele vem com o bloco ad. As seguintes vêm sem. ctwaClid é a chave de atribuição do clique.
messageId é a mensagem que recebeu a reação. targetFromMe: true quando ela era desta instância. removed: true com reaction vazio quando a reação foi tirada.
Com secret, cada POST traz X-Webhook-Signature: sha256=<hex>, onde hex é o HMAC-SHA256 do corpo bruto com o secret. Calcule sobre os bytes recebidos, antes de fazer parse do JSON.
Ignite CoreGO