
Guias de integração
Guia da API do LinkedIn
Guia da API de e-mail
Guia da API do WhatsApp
Fale com vendas
Para equipes que criam um CRM ou SaaS: conecte a conta do Facebook e as Páginas de cada usuário, sincronize as conversas, associe os contatos e responda direto do registro.
api.unipile.com/v2/{ACCOUNT_ID}/chats
200 OK
Uma integração do Facebook Messenger com CRM sincroniza as conversas do Messenger de cada usuário nos registros de contato do CRM e permite responder pelo próprio CRM. Este guia é para equipes que incorporam essa integração ao próprio CRM ou produto SaaS, não para empresas que estão escolhendo um CRM.
São quatro blocos: uma conexão por usuário, histórico mais sincronização em tempo real, associação de contatos e respostas com a identidade certa.
Crie com a Unipile em três etapas
Conecte a conta do Facebook e as Páginas de cada usuário pelo Hosted Auth. Sem app da Meta, sem App Review.
Recupere o histórico dos chats com GET /v2/{account_id}/chats, enviando o seu header X-API-KEY.
Receba novas mensagens, edições e reações por webhook, a começar por message.new.
Uma integração do Facebook Messenger com CRM liga as conversas do Messenger a um CRM, para que cada mensagem caia no registro de contato certo e os usuários respondam sem sair do CRM. Para uma empresa, é um conector que ela ativa. Para uma equipe de produto, é uma funcionalidade que ela incorpora ao próprio CRM ou SaaS: este guia trata desse caso.
Nos dois casos: ler, associar a um contato e responder pelo CRM, em tempo real e por usuário. A nossa visão geral de como as APIs do Facebook se encaixam aborda as plataformas da Meta.
{FACEBOOK_USER_ID}Histórico e novas mensagens, por usuário.
Cada conversa a um contato.
Pelo registro, como usuário ou como Página.
Webhooks, não polling.
Um conector no-code é rápido, mas quase sempre de mão única. A Messenger Platform da Meta é bidirecional, mas só para Páginas e depois do App Review. Uma API de conexão por usuário cobre contas pessoais e Páginas, sem app da Meta.
| Critério | Conector no-code | Messenger Platform da Meta | Conexão por usuário (Unipile) |
|---|---|---|---|
| Contas | Geralmente uma Página do Facebook | Somente Páginas do Facebook (Business Pages) | Contas pessoais e as Páginas que elas gerenciam |
| Direção | Quase sempre de mão única: mensagem vira lead | Bidirecional, dentro da janela de 24 horas | Sincronização bidirecional: ler, responder, reagir |
| Tempo real | Muitas vezes polling, a cada 15 minutos em alguns planos | Webhooks da Meta | Webhooks como message.new |
| O que você opera | Um workflow por configuração | App da Meta, App Review, um token por Página | Um link de Hosted Auth, um account_id por usuário |
| Histórico | Varia conforme o conector | Conversas da Página | Chats pessoais e a inbox de cada Página |
| Outros canais | Um conector para cada | Uma integração por produto da Meta | A mesma API para LinkedIn, WhatsApp, Instagram e e-mail |
message.newaccount_id por usuárioZapier ou Make atendem uma empresa e uma Página, e o Meta Business Suite dá a essa empresa uma inbox para a própria Página. Um produto com vários clientes precisa da integração no próprio código.
Pela via da Meta, cada Página de cliente precisa de um Page access token e de permissões revisadas pela Meta, como mostra o nosso guia da API de Páginas do Facebook. As respostas seguem a janela de 24 horas e as message tags, várias delas retiradas pela Meta em 2026. E essa via nunca chega às contas pessoais que vendedores e consultores usam com os clientes.
Fontes: envio de mensagens na Messenger Platform (Meta) e recursos por provedor (Unipile). Última verificação: 17 de novembro de 2026.
Cada usuário do CRM abre um link de Hosted Auth e faz login no Facebook, incluindo a autenticação de dois fatores. Seu CRM recebe um único account_id, que cobre a conta pessoal e todas as Páginas que esse usuário administra, todas ativadas por padrão.
Seu backend solicita o link; o usuário o abre.
Hosted AuthCredenciais, 2FA e, se quiser, desbloqueio do histórico.
ENCRYPTED_HISTORYSalve-o no usuário do CRM. As Páginas dele vêm junto.
{ACCOUNT_ID}As Páginas são ativadas pelo produto page na conexão ou na reconexão; uma Página não ativada retorna 403 api/insufficient_permissions. O login é detalhado no nosso guia da API do Facebook Messenger para contas pessoais.
Fonte: documentação Facebook Pages da Unipile. Última verificação: 17 de novembro de 2026.
Primeiro, faça o backfill pela API: os chats pessoais e, depois, a inbox de cada Página. Em seguida, passe para os webhooks, para que cada nova mensagem, edição, confirmação ou reação chegue ao seu CRM em tempo real, como listado na nossa página da API do Facebook Messenger.
account_idGET /chats uma vez, depois message.newA lista de chats da conta contém apenas conversas pessoais; cada Página tem a própria inbox, PAGE_<page_id>_INBOX. As listas retornam até 100 itens por página, com as mensagens mais recentes primeiro: pagine para trás até onde o seu CRM precisar.
https://api.unipile.com · header X-API-KEYOs chats pessoais 1:1 e em grupo têm criptografia de ponta a ponta; as conversas de Páginas, não. As mensagens pessoais antigas ficam em um backup criptografado que o usuário desbloqueia com o código de recuperação ou o PIN do Messenger, em uma etapa que o Hosted Auth exibe na conexão. Sem isso, só ficam disponíveis as mensagens recebidas desde a conexão.
Uma única URL de webhook atende todas as contas conectadas. Os eventos de Página trazem o chat ID no escopo da Página, então roteie-os pelo prefixo PAGE_<page_id>_. Eventos disponíveis para o Facebook:
Fontes: documentação da Unipile sobre recuperar chats e mensagens, chats criptografados, recursos por provedor e configurar um webhook. Última verificação: 17 de novembro de 2026.
Conecte uma conta do Facebook no seu workspace de teste
Vincule uma conta, liste os chats e aponte um webhook para o seu serviço. Teste grátis de 7 dias, sem cartão de crédito.
Associe cada conversa a um contato pelo ID do Facebook da outra pessoa, nunca pelo nome exibido. Roteie as conversas de Página e as pessoais pelo prefixo PAGE_<page_id>_ do chat ID.
| Identificador | Onde armazenar | Atenção |
|---|---|---|
| ID do Facebook da outra pessoa | No contato: sua chave de associação | Nunca associe pelo nome exibido |
account_id | No usuário do CRM que conectou o Facebook | Cobre a conta pessoal e as Páginas |
| Chat ID pessoal | Na conversa | Não é chave de contato |
Chat ID de Página PAGE_<page_id>_<thread_key> | Na conversa e na Página dela | O prefixo faz a Unipile agir como a Página |
| ID da Página e ID de perfil da Página | O ID da Página, na inbox e no status | Autores de Página usam o ID de perfil: nunca compare os dois |
PAGE_<page_id>_<thread_key>)Uma armadilha: para a mesma conversa, o chat ID retornado pela API pode ser diferente do que vem em um evento de webhook. Armazene os dois na conversa e concilie-os do lado do CRM, ancorando no ID do Facebook do contato. “Find Chats by User” retorna os chats existentes de um contato, ou uma lista vazia.
readUnipileEvent representa o seu mapeamento do payload.
// One URL for every connected account
app.post("/webhooks/unipile", express.json(), async (req, res) => {
res.sendStatus(200); // acknowledge first, process after
// Your mapping of the payload documented in the webhook reference
const evt = readUnipileEvent(req.body);
if (evt.type !== "message.new") return;
// 1. Route: a PAGE_<page_id>_ prefix means a Page conversation
const page = evt.chatId.match(/^PAGE_([^_]+)_/);
const inbox = page ? { kind: "page", pageId: page[1] } : { kind: "personal" };
// 2. Owner: the CRM user who connected this account_id
const owner = await crm.users.findByAccountId(evt.accountId);
// 3. Contact: the other person's Facebook ID, never the name
const contact =
(await crm.contacts.findByFacebookId(owner.tenantId, evt.counterpartId)) ??
(await crm.contacts.createForReview({ facebookId: evt.counterpartId, owner }));
// 4. Keep the webhook chat ID next to the one from the backfill
await crm.conversations.addChatId(contact.id, inbox, evt.chatId, "webhook");
// 5. Write the message once, keyed by its message ID
await crm.messages.upsert({
contactId: contact.id, inbox, messageId: evt.messageId,
direction: evt.fromOwner ? "out" : "in", text: evt.text,
});
});
import re
from flask import request
PAGE_PREFIX = re.compile(r"^PAGE_([^_]+)_")
# One URL for every connected account
@app.post("/webhooks/unipile")
def unipile_webhook():
# Your mapping of the payload documented in the webhook reference
evt = read_unipile_event(request.get_json())
if evt.type != "message.new":
return "", 200
# 1. Route: a PAGE_<page_id>_ prefix means a Page conversation
page = PAGE_PREFIX.match(evt.chat_id)
inbox = {"kind": "page", "page_id": page.group(1)} if page else {"kind": "personal"}
# 2. Owner: the CRM user who connected this account_id
owner = crm.users.find_by_account_id(evt.account_id)
# 3. Contact: the other person's Facebook ID, never the name
contact = crm.contacts.find_by_facebook_id(owner.tenant_id, evt.counterpart_id) \
or crm.contacts.create_for_review(facebook_id=evt.counterpart_id, owner=owner)
# 4. Keep the webhook chat ID next to the one from the backfill
crm.conversations.add_chat_id(contact.id, inbox, evt.chat_id, source="webhook")
# 5. Write the message once, keyed by its message ID
crm.messages.upsert(
contact_id=contact.id, inbox=inbox, message_id=evt.message_id,
direction="out" if evt.from_owner else "in", text=evt.text,
)
return "", 200
Formatos de chat ID: documentação Facebook Pages; busca de chats: recuperar chats e mensagens.
Envie a resposta no chat ID da conversa. Um chat ID de Página responde como a Página; um chat ID pessoal envia pela própria conta do usuário. O editor mostra qual identidade se aplica.
Uma Página só responde a quem escreveu para ela.
/v2/{ACCOUNT_ID}/chats/{CHAT_ID}/messages/send
200 OK
501 api/not_implementedDesative “Nova conversa” para uma Página. Corpo da requisição, anexos e erros: veja como enviar uma mensagem do Messenger via API.
Mostre o estado de cada conexão. Cada Página informa o próprio status, então uma Página com problema não interrompe as mensagens pessoais nem as outras Páginas.
metadata.products_connection_status
por Página
Cada Página tem a própria chave em metadata.products_connection_status, chamada page_<page_id>. Quando uma Página cai, a conta passa para partial ou degraded. Uma Página que perdeu a função de admin fica disconnected até a reconexão: mostre isso e ofereça a reconexão.
Mostre as conversas pessoais ao dono e aos gestores escolhidos, e as conversas de Página à equipe da Página, em uma inbox unificada com atribuição e tags. É o mesmo modelo de uma API de mensagens para software de CRM que cobre LinkedIn, WhatsApp e e-mail, e é por isso que uma API de mensagens unificada permite adicionar o Messenger sem um novo conector.
Cada usuário conecta a própria conta
Para CRM, suporte, consultores ou um agente de IA cujos rascunhos uma pessoa aprova. Sem envio em massa.
Comece a criar a sua integração com o Messenger
Uma integração do Facebook Messenger com CRM se resume a uma conexão por usuário, um backfill seguido de webhooks, contatos associados pelo ID do Facebook e respostas com a identidade certa. O mesmo código atende LinkedIn, WhatsApp e e-mail. Teste grátis de 7 dias, sem cartão de crédito.
Cada usuário conecta a própria conta, sem armazenamento de perfis. A Unipile não é Meta Partner. Nossa abordagem do Digital Markets Act
Todos os endpoints da API do Facebook em um só lugar
O Messenger é só uma parte do panorama. Veja todos os endpoints do Facebook disponíveis com a Unipile, de posts e comentários a perfis, ou comece pelo nosso guia completo da API do Facebook.
Mensagens no CRM, respostas automatizadas e várias Páginas.
Para que as conversas deixem de ficar no celular de uma só pessoa. Cada mensagem cai no registro do contato, a equipe vê o histórico completo, e follow-ups, atribuição e relatórios funcionam no Messenger como no e-mail.
Enviar e receber mensagens no Messenger, WhatsApp, LinkedIn ou e-mail de dentro de um CRM, com cada conversa associada a um contato. Uma integração do Facebook Messenger com CRM cobre um canal; uma API de mensagens unificada traz os outros pelo mesmo modelo de dados.
Mantenha uma pessoa no circuito: um agente de IA redige uma resposta a partir do histórico do contato e um usuário a aprova antes do envio. Os usuários continuam sujeitos aos termos da Meta: nada de mensagens não solicitadas ou em massa.
Sim. Todas as Páginas que o usuário administra são ativadas por padrão no mesmo account_id, cada uma com a própria inbox (PAGE_<page_id>_INBOX) e o próprio status. Mostre cada Página como uma inbox separada no seu CRM.
Ainda tem dúvidas? Nossa equipe está aqui para ajudar.
Fale com um especialista