Desenvolvedores

Guia passo a passo para criar cada tipo de conexão e integrar sua aplicação ao hub. Use seu token da empresa e os endpoints abaixo — não é necessário configurar app na Meta.

Pré-requisitos

Para quem usa este hub

Você não precisa criar app na Meta nem configurar nada no Facebook for Developers. O hub já possui a integração com WhatsApp, Instagram e Facebook. Basta usar seu token da empresa (company token) e os endpoints abaixo.

Crie uma conta na plataforma e faça login no Dashboard.
Obtenha o token da empresa (company token, UUID) para autenticar as requisições. Use no header Authorization: Bearer <uuid> ou X-Company-Token: <uuid>. O token está disponível no Dashboard (Perfil / configurações da conta).
Base URL da API: use a URL do hub (ex: https://seu-hub.com.br).

As conexões são criadas pelo Dashboard ou via API. Este guia descreve o fluxo de cada canal para você integrar sua aplicação ao hub.

Webhook (URL 1 e URL 2)

Para receber no seu sistema as mensagens e eventos da conexão (entrada, envio, status, exclusão etc.), configure uma ou duas URLs de webhook na conexão. O hub fará POST para essas URLs sempre que ocorrer um evento.

Configurar as URLs de webhook

POST/api/subscriptions

Header	Valor
`Authorization`	Bearer <company_token_uuid>
`X-Company-Token`	Alternativa: token UUID da empresa
`Content-Type`	application/json

Body

Campo	Tipo	Descrição
`channel`	string	Token (UUID) da conexão obrigatório
`webhooks.url`	string	URL 1 — endpoint que receberá os POSTs do hub (ex: `https://seu-servidor.com/webhook`)
`webhooks.url2`	string	URL 2 — opcional; segunda URL para receber os mesmos eventos (útil para réplica ou log)

{
  "channel": "uuid-da-conexao",
  "webhooks": {
    "url": "https://seu-servidor.com/webhook",
    "url2": "https://outro-servidor.com/webhook"
  }
}

Resposta (sucesso):{"success": true, "message": "Webhooks configurados com sucesso", "data": { "connectionId": "...", "webhooks": { "url": "...", "url2": "..." } }}

Consultar e remover webhooks

GET/api/subscriptions/:channel

Retorna as URLs configuradas para a conexão :channel (token da conexão).

DELETE/api/subscriptions/:channel

Remove as URLs de webhook (url e url2) da conexão. O hub deixa de enviar eventos para suas URLs.

O que o hub envia no POST

Cada evento é enviado com POST no corpo em JSON. Seu endpoint deve responder com status 2xx para o hub considerar entrega ok (há retentativas em caso de falha).

Header	Descrição
`Content-Type`	application/json
`X-Webhook-Event`	Tipo do evento (ex: `message.received`, `message.sent`)
`X-Webhook-Timestamp`	Data/hora do evento (ISO 8601)

Eventos:message.received, message.sent, message.status, message.deleted, template.status.

Exemplo de payload (mensagem recebida):

{
  "event": "message.received",
  "timestamp": "2025-02-24T12:00:00.000Z",
  "connection": {
    "id": "uuid-da-conexao",
    "channel": "whatsapp",
    "businessName": "Minha Empresa"
  },
  "chat": {
    "id": 123,
    "phoneNumber": "5511999999999",
    "contactName": "João"
  },
  "message": {
    "id": 456,
    "direction": "in",
    "type": "text",
    "text": "Olá!",
    "mediaUrl": null,
    "mediaType": null,
    "timestamp": "2025-02-24T12:00:00.000Z",
    "status": null
  }
}

Dica

A URL deve ser HTTPS em produção e acessível pela internet. O hub envia para url e url2 em paralelo; você pode usar url2 para backup, log ou outro sistema.

Conexão via WhatsApp Cloud API (Embedded Signup). O usuário vincula o número no popup da Meta. Você só precisa chamar a API do hub com seu token.

Passos para criar a conexão WhatsApp

Obter a URL do Embedded Signup

Chame o endpoint abaixo com seu company token. O hub retorna a URL para o usuário vincular o número no WhatsApp. Seu frontend deve abrir essa URL em um popup.

GET/api/embedded-signup/start

Header	Valor
`Authorization`	Bearer <company_token_uuid> obrigatório
`X-Company-Token`	Alternativa: token UUID da empresa

Resposta (sucesso):{"success": true, "url": "...", "state": "...", "redirectUri": "..."}

Abrir popup e concluir o fluxo na Meta

Abra a url retornada em uma janela popup (ex.: 600x700). O usuário faz login na Meta, seleciona a conta WhatsApp Business e autoriza. O hub processa o callback e cria a conexão automaticamente.

Detectar sucesso no frontend

O frontend pode detectar sucesso via postMessage (tipo EMBEDDED_SIGNUP_SUCCESS) ou quando a URL do popup contém status=success. A partir daí, atualize a lista de conexões (ex.: chamando novamente a API de listagem).

Dica

Permita popups para o domínio do hub. Se o popup for bloqueado, o fluxo pode ser aberto na mesma aba (redirecionamento).

Instagram

Conexão com Instagram Messaging API via OAuth. O usuário autoriza a página/conta Instagram no popup. Nenhuma configuração na Meta é necessária da sua parte — o hub já cuida disso.

Passos para criar a conexão Instagram

Obter a URL de início do login

Chame o endpoint abaixo com seu company token. O hub retorna a URL de autorização. Seu frontend abre essa URL em popup.

GET/api/instagram/start

Header	Valor
`Authorization`	Bearer <company_token_uuid> obrigatório
`X-Company-Token`	Alternativa: token UUID da empresa

Resposta:{"success": true, "url": "...", "state": "...", "redirectUri": "..."}

Popup e conclusão

Abra a url em popup. O usuário autoriza a conta Instagram. O hub processa o callback e cria a conexão. O popup pode enviar postMessage com type: "OAUTH_SUCCESS" para você atualizar a lista de conexões.

Facebook

Conexão com Facebook Messenger via OAuth. O usuário autoriza uma Página do Facebook para receber e enviar mensagens. Não é necessário ter app na Meta — o hub já oferece a integração.

Passos para criar a conexão Facebook

Obter a URL do OAuth

Chame o endpoint abaixo com seu company token. O hub retorna a URL de autorização para o usuário vincular uma Página.

GET/api/facebook/start

Header	Valor
`Authorization`	Bearer <company_token_uuid> obrigatório
`X-Company-Token`	Alternativa: token UUID da empresa

Resposta:{"success": true, "url": "...", "state": "...", "redirectUri": "..."}

Abrir popup e concluir

Abra a url em popup (ou na mesma aba se popup for bloqueado). Após o usuário autorizar a Página, o hub processa o callback e cria a conexão. O frontend pode escutar OAUTH_SUCCESS via postMessage.

Conexão via Bot do Telegram. Não usa Meta nem app externo do hub: você cria um bot no Telegram (gratuito) e envia o token e o nome do canal para a API do hub.

Passos para criar a conexão Telegram

Criar um bot no Telegram

Abra o @BotFather no Telegram. Envie /newbot, defina nome e username do bot. O BotFather retorna o token do bot (ex.: 1234567890:ABCdefGHI...). Guarde esse token.

Definir o nome do canal

Anote o nome do canal ou grupo onde o bot atuará (com ou sem @). Ex.: meucanal ou @meucanal.

Criar a conexão via API

Envie um POST com o token do bot e o nome do canal. A plataforma valida o token e registra o webhook no Telegram.

POST/api/connections/telegram

Header	Valor
`Authorization`	Bearer <company_token_uuid>
`X-Company-Token`	Alternativa: token UUID da empresa
`Content-Type`	application/json

Body

Campo	Tipo	Descrição
`accessToken`	string	Token do bot (BotFather) obrigatório
`telegramBotToken`	string	Mesmo token do bot
`telegramChannelName`	string	Nome do canal (com ou sem @) obrigatório
`businessName`	string	Nome exibido (ex.: nome do canal)

{
  "accessToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
  "telegramBotToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
  "telegramChannelName": "meucanal",
  "businessName": "Meu Canal"
}

Atenção

Após criar a conexão, o bot pode ser iniciado ou pausado pelo Dashboard. Use Reiniciar para ativar o bot e Pausar para parar de receber atualizações.

WWebchat

Conexão Webchat para embedar um chat ao vivo no seu site. Não depende de Meta nem Telegram: você cria a conexão direto pela API do hub e incorpora o widget no seu site.

Passos para criar a conexão Webchat

Preencher dados do widget

No Dashboard, ao escolher o canal Webchat, informe: Nome do negócio, Título do widget (ex.: "Atendimento"), Cor primária e Mensagem de boas-vindas. Ou envie os mesmos campos via API.

Criar a conexão via API

POST para /api/connections/webchat. A resposta retorna o token (connection token) e a webchatApiKey. A API Key é exibida apenas uma vez — guarde-a em local seguro.

POST/api/connections/webchat

Header	Valor
`Authorization`	Bearer <company_token_uuid>
`X-Company-Token`	Alternativa: token UUID da empresa
`Content-Type`	application/json

Body

Campo	Tipo	Descrição
`channel`	string	`"webchat"`
`businessName`	string	Nome do negócio obrigatório
`webchatWidgetTitle`	string	Ex.: "Atendimento"
`webchatWidgetColor`	string	Cor hex (ex.: #4F46E5)
`webchatWelcomeMessage`	string	Mensagem de boas-vindas

{
  "channel": "webchat",
  "businessName": "Minha Loja",
  "webchatWidgetTitle": "Atendimento",
  "webchatWidgetColor": "#4F46E5",
  "webchatWelcomeMessage": "Olá! Como podemos ajudar?"
}

Incorporar o chat no site

Use o connectionToken e a webchatApiKey no script do widget. A documentação completa do widget, endpoints de envio de mensagem e polling está em:

Documentação de Integração Webchat →

Resumo

Para WhatsApp, Instagram e Facebook: use apenas seu company token e os endpoints do hub; não é necessário criar app na Meta. Para Telegram: crie um bot no @BotFather e envie o token na API. Para Webchat: crie a conexão pela API e incorpore o widget no site.