Como configurar o get.chat: guia de API REST e múltiplos webhooks

Índice

Para configurar o get.chat, conecte-se com a chave de API do seu canal, envie uma primeira mensagem e registre um webhook para cada sistema que precisa dos eventos do seu WhatsApp. O get.chat é a camada de tecnologia por trás do 360Dialog Inbox, e a Inbox API dele acrescenta uma API REST, a distribuição de eventos para vários webhooks e uma interface de caixa de entrada incorporável sobre a WhatsApp Business API oficial.[1] Ele está incluído no plano Premium por €99 por número por mês.[2] Este guia vai da sua chave de API até um webhook verificado para mensagens recebidas.

Principais conclusões

Você precisa de um número do WhatsApp no plano Premium da 360Dialog com o Inbox ativado.
A primeira mensagem para um cliente que nunca escreveu para você precisa ser um modelo de mensagem aprovado, um formato que a Meta aprova com antecedência.
A sua chave de API atual basta para começar, e cada sistema que você adicionar depois recebe o próprio login para a API.
Escolha quais eventos cada webhook recebe ao criá-lo, começando pelas mensagens que seus clientes enviam.

O que você precisa antes de começar

Você precisa ter cinco coisas em mãos antes da primeira chamada de API:

Uma conta na 360Dialog com o seu número do WhatsApp conectado e ativo.
O Inbox ativado nesse número. Ele vem com o plano Premium; ative-o no seu canal pelo 360Dialog Hub.[3]
A URL do seu Inbox, no formato https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/. Abra o Inbox pelo 360Dialog Hub e copie o endereço do navegador. Cada número tem o próprio Inbox, com a própria URL.[4]
A chave de API do seu canal, gerada no Hub, que é o segredo que identifica o seu número quando você chama a API do WhatsApp. Gerar uma nova chave revoga a anterior, então reutilize a chave atual se outra integração depender dela.[5]
Um endereço HTTPS acessível publicamente para cada sistema que você quer alimentar.[6]

Todos os pontos de extremidade deste guia ficam em /api/v1/ no endereço do seu Inbox.

Se você está conectando seu número pela primeira vez, o próximo passo é começar a usar a API e escolher o plano Premium, que já inclui o Inbox e a API dele.

Como autenticar com a chave de API e os tokens de serviço

A Inbox API aceita a chave de API do seu canal para configuração e testes, e um token por serviço em produção. Confira a conexão enviando a chave no cabeçalho D360-Api-Key:

curl -H "D360-Api-Key: YOUR_API_KEY" \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/current/

A resposta traz o usuário administrador do Inbox, com o qual a chave de API faz o seu login. Uma chave de outro canal retorna 403.

Crie um usuário e um token para cada serviço

Cada sistema que se comunica com o Inbox precisa do próprio usuário, porque webhooks, contagens de mensagens novas, permissões e registros de auditoria pertencem a um usuário. Crie um com a função app, que tem acesso apenas à API:

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/users/ \
  -H "D360-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "crm-sync", "profile": {"role": "app"}}'

A resposta contém uma activation_url, retornada uma única vez. Chame essa URL para obter o token do serviço:

curl "ACTIVATION_URL"

{"token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"}

Guarde o token nos segredos do serviço, já que a URL de ativação funciona apenas uma vez. O serviço envia o token com o prefixo Token:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Como enviar sua primeira mensagem

O que você pode enviar depende da janela de atendimento ao cliente, o período em que o WhatsApp permite que uma empresa envie mensagens livres. A janela abre quando o cliente envia uma mensagem para você e dura 24 horas a partir da última mensagem dele, ou 72 horas em conversas iniciadas por um anúncio de clique para o WhatsApp ou pelo botão de chamada para ação de uma Página do Facebook ou do Instagram.[7] Leia o fim da janela em contact.messaging_window_expires_at no chat, já que a duração depende de como a conversa começou.[8]

Estado da conversa	O que você pode enviar
O cliente nunca escreveu para você	Apenas modelo de mensagem
O cliente escreveu dentro da janela	Texto, mídia, mensagem interativa ou modelo de mensagem
A janela expirou	Apenas modelo de mensagem

Enviar um modelo de mensagem abre uma nova janela.

Envie texto livre com a janela aberta

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/messages/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wa_id": "5511912345678", "type": "text", "text": {"body": "Olá, aqui é a Inbox API"}}'

O campo wa_id identifica o destinatário: um número de telefone em formato internacional sem o sinal de mais, ou um ID de usuário vinculado à empresa (Business-Scoped User ID, BSUID) quando o WhatsApp não compartilha o número da pessoa. Repasse o valor exatamente como você o recebeu do chat.

Para um primeiro teste, abra a janela você mesmo: escaneie com o seu celular pessoal o código QR em Abrir no WhatsApp, no Inbox, e envie uma mensagem.

Envie um modelo de mensagem para abrir uma nova janela

Busque seus modelos de mensagem aprovados em GET /api/v1/templates/ e envie um deles pelo nome, no mesmo formato da API do WhatsApp:

{
  "wa_id": "5511912345678",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": {"code": "pt_BR"}
  }
}

Entenda os códigos de resposta

Os status de enviada, entregue e lida chegam depois no seu webhook, assim como o erro 470, de destinatário sem WhatsApp.[9]

Código	Significado	O que fazer
202	Aceita e na fila para entrega	Aguarde os eventos de status no seu webhook
400	Há algo errado na requisição	Leia o campo reason
403	Sem login ou sem permissão para este chat	Confira o cabeçalho e as permissões de leitura e escrita do usuário
452	O destinatário não é um usuário válido do WhatsApp	Confira o wa_id
453	Janela de atendimento ao cliente fechada	Envie um modelo de mensagem aprovado

Como configurar vários webhooks em um número

Um webhook é o endereço para onde o WhatsApp entrega os eventos do seu número, e cada número tem um webhook principal. A 360Dialog também pode vincular URLs de webhook adicionais diretamente a um número, com entrega mais lenta à medida que mais URLs entram, e recomenda um único webhook para contas de alto volume.[10] O Inbox recebe o webhook principal e chama o webhook de cada serviço que você conecta, com um HTTP POST e um corpo JSON no formato padrão de webhook do WhatsApp.[11]

Os webhooks pertencem a usuários. O usuário cujo token cria um webhook é o dono dele, e usuários sem direitos de administrador veem apenas os próprios.[12]

Crie um ponto de extremidade

curl -X POST \
  https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/api/v1/webhooks/waba/ \
  -H "Authorization: Token YOUR_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-backend.example.com/whatsapp", "on_incoming_message": true, "on_outgoing_message": true, "on_assigned": false, "headers": {"Authorization": "Bearer your-own-shared-secret"}}'

Defina os sinalizadores de evento

Cada sinalizador ativa ou desativa um tipo de evento, então defina todos os sinalizadores explicitamente ao criar um webhook.

Campo	Entrega
on_incoming_message	Cada mensagem que um cliente envia para o seu número
on_outgoing_message	Cada mensagem enviada pelo Inbox, pela caixa de entrada hospedada ou pela API, para sistemas que guardam cópias completas das conversas
on_assigned	Um chat atribuído ao usuário deste webhook, ou uma nova mensagem em um chat já atribuído a ele; ative quando um bot cuida dos chats atribuídos a ele
on_message_echo	Mensagens enviadas do seu número pela Messaging API da 360Dialog fora do Inbox, no formato message_echoes da Meta
headers	Cabeçalhos personalizados enviados em cada entrega

Gerencie seus pontos de extremidade

Chamada	O que faz
GET /api/v1/webhooks/waba/	Lista os webhooks: administradores veem os de todos os usuários, os demais usuários veem os próprios
POST /api/v1/webhooks/waba/	Cria um webhook, que pertence ao usuário do token
GET /api/v1/webhooks/waba/{id}/	Inspeciona um webhook
PUT /api/v1/webhooks/waba/{id}/	Atualiza um webhook: o endereço, os eventos e os cabeçalhos
DELETE /api/v1/webhooks/waba/{id}/	Remove um webhook
GET /api/v1/webhooks/waba/{id}/test/	Envia uma entrega simulada do tipo statuses para o endereço de destino

As mesmas configurações ficam em WABA Webhooks, nas configurações da caixa de entrada (WABA é a conta do WhatsApp Business). Um pipeline de vendas no WhatsApp pode rodar no próprio ponto de extremidade, independente dos outros sistemas do número.

Se você está planejando vários sistemas em um número e quer uma segunda opinião sobre a organização de usuários e tokens, fale conosco antes de construir.

Como proteger e tratar as entregas

Seu ponto de extremidade é um endereço público que aceita gravações, então autentique cada entrega com um destes dois métodos:

Cabeçalhos personalizados. O campo headers é enviado em cada entrega, então seu ponto de extremidade pode exigir o próprio token do tipo bearer.
Um segredo compartilhado no endereço, como https://your-backend.example.com/whatsapp?auth=SHARED_SECRET, para sistemas que não leem cabeçalhos personalizados.

Cada entrega chega no formato padrão de webhook do WhatsApp. De forma resumida, uma mensagem recebida fica assim:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "contacts": [{"profile": {"name": "Ana"}, "wa_id": "5511912345678", "user_id": "BR.13491208655302741918"}],
        "messages": [{"from": "5511912345678", "id": "wamid.ID", "type": "text", "text": {"body": "Oi"}}]
      }
    }]
  }]
}

A mensagem fica em messages[] e o remetente, em contacts[]. O BSUID em user_id está sempre presente, mesmo quando o WhatsApp oculta o número de telefone, então use-o primeiro para identificar os clientes.

Responda 200 rapidamente e deixe o trabalho demorado para depois. As mensagens entregues a um webhook com 200 ficam marcadas como recebidas para o usuário desse webhook, o que mantém corretas as contagens de não lidas em GET /api/v1/chats/.

Como incorporar o Inbox na sua aplicação

A caixa de entrada dos atendentes é uma aplicação React de código aberto que você pode incorporar a uma ferramenta existente com uma única tag iframe.[13] Ela atende equipes que estão gerenciando as conversas do WhatsApp em equipe dentro de uma ferramenta interna ou de um portal do cliente.

<iframe
  src="https://YOUR_STACK_NAME.inbox.getchat.360dialog.io/?chat_only=1&hide_logo=1"
  allow="clipboard-write"
  width="420" height="700">
</iframe>

Sem allow=”clipboard-write”, os navegadores bloqueiam as ações de copiar dentro do iframe.

Parâmetro	Efeito
chat_only=1	Oculta a lista de chats e mostra uma única conversa
hide_logo=1	Remove o logotipo do get.chat da tela de carregamento
lng=de	Define o idioma da interface pelo código ISO 639-1
bg_color=ff0000	Define a cor de fundo como valor hexadecimal, sem o sinal #
maximize=1	Remove as margens do contêiner para que a caixa de entrada ocupe todo o iframe
cf_<filter>	Aplica um filtro de chats ao carregar, com qualquer filtro aceito pelo ponto de extremidade de chats

Para usar seu próprio logotipo, título da página, ícone do site e manifesto do app, é preciso hospedar por conta própria a interface de código aberto, com variáveis como REACT_APP_TITLE, REACT_APP_LOGO_URL e REACT_APP_FAVICON_URL definidas na compilação.[14]

Checklist de testes: verifique sua configuração de ponta a ponta

Faça estas verificações na ordem, já que uma falha em qualquer etapa isola o problema naquela camada.

O Inbox está saudável. GET /api/v1/status/health/ retorna um status para cada verificação interna.
As credenciais são válidas. GET /api/v1/users/current/ retorna o usuário administrador da sua chave de API, ou o próprio usuário do serviço no caso de um token de serviço.
A janela está aberta. Envie uma mensagem para o número da empresa a partir de uma conta pessoal do WhatsApp, ou escaneie o código QR em Abrir no WhatsApp, no Inbox.
A mensagem é enviada. POST /api/v1/messages/ com um corpo de texto retorna 202, e a mensagem chega ao celular.
Os webhooks aparecem na lista. GET /api/v1/webhooks/waba/ mostra cada ponto de extremidade e o valor de on_incoming_message.
O ponto de extremidade está acessível. GET /api/v1/webhooks/waba/{id}/test/ envia uma entrega simulada do tipo statuses, sem nenhuma mensagem; seu servidor registra a entrega e retorna 200.
A distribuição funciona. Uma mensagem recebida do celular de teste chega a todos os pontos de extremidade registrados, e esta é a única etapa que testa seus sinalizadores.
O Inbox mostra o chat. Abra o Inbox pelo 360Dialog Hub e confira a conversa.

Se o evento de teste nunca chegar, confira se o endereço HTTPS está acessível, se a resposta 200 é rápida e se há alguma lista de IPs permitidos. Depois, confira o ponto de extremidade em WABA Webhooks, nas configurações da caixa de entrada.

Com a chave de API, os tokens de serviço, os sinalizadores de webhook e o checklist prontos, ative seu Inbox no plano Premium para rodar essa configuração no seu próprio número.

Perguntas frequentes

Qual método de autenticação a API do get.chat usa?

A Inbox API aceita duas credenciais. A chave de API do seu canal, enviada no cabeçalho D360-Api-Key, faz o login como administrador do Inbox e serve para configuração e testes. Em produção, cada serviço usa o próprio usuário app e o próprio token, enviado como Authorization: Token YOUR_TOKEN em todas as chamadas.

Posso registrar vários pontos de extremidade de webhook em um número do WhatsApp?

Sim. O Inbox recebe o único webhook do WhatsApp e entrega cada evento de novo a todos os pontos de extremidade registrados, cada um com os próprios sinalizadores de evento e cabeçalhos. Os webhooks pertencem a cada usuário, então dê a cada sistema que consome os eventos o próprio usuário e token.

Por que meu webhook não está recebendo as mensagens dos clientes?

Busque o ponto de extremidade com GET /api/v1/webhooks/waba/{id}/ e confira se on_incoming_message está como true. Depois, confirme que o ponto de extremidade aceita requisições HTTPS POST e retorna 200 rapidamente, e envie uma entrega simulada com GET /api/v1/webhooks/waba/{id}/test/ para testar a conexão.

O que acontece se eu enviar uma mensagem fora da janela de atendimento ao cliente?

A API retorna 453 com o motivo “Customer care messaging window expired.” e nada é entregue. Envie um modelo de mensagem aprovado, que abre uma nova janela.

Incorporar o Inbox exige hospedagem própria?

A incorporação funciona com o seu Inbox hospedado: aponte um iframe para o endereço do Inbox e ajuste-o com parâmetros de consulta. Hospedar por conta própria a interface de código aberto só é necessário para a marca definida na compilação, como seu próprio logotipo, título da página e ícone do site.

Uma instância do get.chat pode atender vários números do WhatsApp?

Cada número tem o próprio Inbox, com endereço, servidores, banco de dados e usuários próprios. Vários números significam vários Inboxes, e o seu serviço se conecta a cada um separadamente.

Fontes

[1] 360Dialog Documentation, “Inbox API.” https://docs.360dialog.com/docs/inbox/inbox-api Accessed September 30, 2026.

[2] 360Dialog, “WhatsApp Business Platform Pricing.” https://360dialog.com/pricing Accessed September 25, 2026.

[3] 360Dialog Documentation, “Quickstart” (Hosted Inbox). https://docs.360dialog.com/docs/inbox/hosted-inbox/quickstart Accessed September 30, 2026.

[4] 360Dialog Documentation, “Quickstart” (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/quickstart Accessed September 30, 2026.

[5] 360Dialog Documentation, “Authentication” (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/authentication Accessed September 30, 2026.

[6] 360Dialog Documentation, “Making Requests” (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/reference/making-requests Accessed September 30, 2026.

[7] 360Dialog Documentation, “The Customer Service Window.” https://docs.360dialog.com/docs/inbox/the-customer-service-window Accessed September 30, 2026.

[8] 360Dialog Documentation, “Sending Messages” (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/sending-messages Accessed September 30, 2026.

[9] 360Dialog Documentation, “Messages” (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/messages Accessed September 30, 2026.

[10] 360Dialog Partner Documentation, “Set multiple webhooks for Phone Number.” https://docs.360dialog.com/partner/onboarding/webhook-events-and-setup/set-multiple-webhooks-for-phone-number Accessed September 28, 2026.

[11] 360Dialog Documentation, “Receiving Messages” (Inbox API). https://docs.360dialog.com/docs/inbox/inbox-api/receiving-messages Accessed September 30, 2026.

[12] 360Dialog Documentation, “Webhooks” (Inbox API reference). https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/webhooks Accessed September 30, 2026.

[13] get.chat documentation, “Embed and White-Label the Inbox.” https://docs.getchat.360dialog.io/guides/2-embedding-the-inbox/ Accessed September 25, 2026.

[14] get.chat, “get.chat Web App” README. https://github.com/get-chat/web-app Accessed September 25, 2026.