BR
Guia de integração CRM

Integração do Facebook Messenger com CRM: como incorporá-la ao seu produto

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.

Seu CRM · Messenger Sincronizado
Leo MartinVocês enviam a jaqueta de linho para Lyon?Associado · LeadCoveton Apparel
Sara KimObrigada, Anna, assino amanhã.Associado · NegócioPessoal
Omar HaddadVocê: Seu pedido saiu do depósito.Associado · ClienteCoveton Apparel
Webhooks message.new message.receipt.read
GET api.unipile.com/v2/{ACCOUNT_ID}/chats 200 OK
Resposta curta

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.

Com a Unipile

Crie com a Unipile em três etapas

  1. 1

    Conecte a conta do Facebook e as Páginas de cada usuário pelo Hosted Auth. Sem app da Meta, sem App Review.

  2. 2

    Recupere o histórico dos chats com GET /v2/{account_id}/chats, enviando o seu header X-API-KEY.

  3. 3

    Receba novas mensagens, edições e reações por webhook, a começar por message.new.

Definição

O que é uma integração do Facebook Messenger com CRM?

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.

Seu CRM · Contato Ao vivo
Leo MartinLead · Lyon
ResponsávelAnna Rossi
CanalMessenger · Página Coveton Apparel
ID do Facebook{FACEBOOK_USER_ID}
AtividadeE-mailMessenger 2Negócios
FacebookInbox da PáginaCoveton Apparel
Oi, vocês enviam a jaqueta de linho para Lyon?10:40
Sim, a entrega leva 3 dias. De qual tamanho você precisa?Coveton Apparel · 10:41
01

Ler

Histórico e novas mensagens, por usuário.

02

Associar

Cada conversa a um contato.

03

Responder

Pelo registro, como usuário ou como Página.

04

Tempo real

Webhooks, não polling.

Abordagens

Como conectar o Facebook Messenger a um CRM: três caminhos

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érioConector no-codeMessenger Platform da MetaConexão por usuário (Unipile)
ContasGeralmente uma Página do FacebookSomente Páginas do Facebook (Business Pages)Contas pessoais e as Páginas que elas gerenciam
DireçãoQuase sempre de mão única: mensagem vira leadBidirecional, dentro da janela de 24 horasSincronização bidirecional: ler, responder, reagir
Tempo realMuitas vezes polling, a cada 15 minutos em alguns planosWebhooks da MetaWebhooks como message.new
O que você operaUm workflow por configuraçãoApp da Meta, App Review, um token por PáginaUm link de Hosted Auth, um account_id por usuário
HistóricoVaria conforme o conectorConversas da PáginaChats pessoais e a inbox de cada Página
Outros canaisUm conector para cadaUma integração por produto da MetaA mesma API para LinkedIn, WhatsApp, Instagram e e-mail
Contas
No-codeGeralmente uma Página do Facebook
MetaSomente Páginas do Facebook
UnipileContas pessoais e as Páginas que elas gerenciam
Direção
No-codeQuase sempre de mão única: mensagem vira lead
MetaBidirecional, dentro da janela de 24 horas
UnipileSincronização bidirecional: ler, responder, reagir
Tempo real
No-codeMuitas vezes polling, a cada 15 minutos em alguns planos
MetaWebhooks da Meta
UnipileWebhooks como message.new
O que você opera
No-codeUm workflow por configuração
MetaApp da Meta, App Review, um token por Página
UnipileUm link de Hosted Auth, um account_id por usuário
Histórico
No-codeVaria conforme o conector
MetaConversas da Página
UnipileChats pessoais e a inbox de cada Página
Outros canais
No-codeUm conector para cada
MetaUma integração por produto da Meta
UnipileA mesma API para LinkedIn, WhatsApp, Instagram e e-mail

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

Conexão

Conecte a conta do Facebook e as Páginas de cada usuário

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.

1

Abrir um link de Hosted Auth

Seu backend solicita o link; o usuário o abre.

Hosted Auth
2

Fazer login e desbloquear o histórico

Credenciais, 2FA e, se quiser, desbloqueio do histórico.

ENCRYPTED_HISTORY
3

Armazenar o account_id

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

Sincronização

Sincronize o histórico de conversas e as novas mensagens em tempo real

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.

FacebookOrigemConta pessoal + PáginasUma por usuário do CRM
ConexãoUnipileUm account_id
EntradaBackfill e depois webhooksGET /chats uma vez, depois message.new
Seu códigoServiço de sincronizaçãoRoteia, associa, deduplica
Seus dadosBanco de dados do CRMContatos e mensagens

Backfill dos chats pessoais e das inboxes das Páginas

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

URL base https://api.unipile.com · header X-API-KEY
GET/v2/{account_id}/chatsChats pessoais da conta conectada
GET/v2/{account_id}/inboxes/{inbox_id}/chatsChats da inbox de uma Página
GET/v2/{account_id}/chats/{chat_id}/messagesMensagens de um chat, mais recentes primeiro

Chats criptografados e histórico

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

Webhooks

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:

message.new message.update message.delete message.receipt.read message.receipt.delivery message.reaction.new chat.update chat.delete

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.

Experimente

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.

Comece agora
Modelo de dados

Associe as conversas do Messenger aos contatos do CRM

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.

IdentificadorOnde armazenarAtenção
ID do Facebook da outra pessoaNo contato: sua chave de associaçãoNunca associe pelo nome exibido
account_idNo usuário do CRM que conectou o FacebookCobre a conta pessoal e as Páginas
Chat ID pessoalNa conversaNão é chave de contato
Chat ID de Página PAGE_<page_id>_<thread_key>Na conversa e na Página delaO prefixo faz a Unipile agir como a Página
ID da Página e ID de perfil da PáginaO ID da Página, na inbox e no statusAutores de Página usam o ID de perfil: nunca compare os dois
ID do Facebook da outra pessoa
Onde armazenarNo contato: sua chave de associação
AtençãoNunca associe pelo nome exibido
account_id
Onde armazenarNo usuário do CRM que conectou o Facebook
AtençãoCobre a conta pessoal e as Páginas
Chat ID pessoal
Onde armazenarNa conversa
Chat ID de Página
Onde armazenarNa conversa e na Página dela (PAGE_<page_id>_<thread_key>)
AtençãoO prefixo faz a Unipile agir como a Página
ID da Página e ID de perfil da Página
Onde armazenarO ID da Página, na inbox e no status
AtençãoAutores de Página usam o ID de perfil: nunca compare os dois

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.

Um handler de message.new que grava no registro do contato

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
200 OK · um contato por ID do Facebook, uma linha por message ID
200 OK · um contato por ID do Facebook, uma linha por message ID

Formatos de chat ID: documentação Facebook Pages; busca de chats: recuperar chats e mensagens.

Resposta

Responda pelo registro do contato, como usuário ou como Página

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.

Seu CRM · Leo Martin Conversa de Página
Tamanho M, por favor. Chega até sexta?10:42
Sim, se você fizer o pedido hoje antes das 14h.Coveton Apparel · 10:44
Perfeito, vou pedir agora.10:46
Responder comoAnna RossiFacebookPágina Coveton Apparel
Obrigada, Leo, seu pedido está confirmado. O link de rastreio vem em seguida.
Nova conversaEnviar

Uma Página só responde a quem escreveu para ela.

POST /v2/{ACCOUNT_ID}/chats/{CHAT_ID}/messages/send 200 OK
Em um chat de Página
  • As respostas saem como a Página
  • Sem nova conversa: 501 api/not_implemented
  • Sem excluir as mensagens dela: mesmo erro
Em um chat pessoal
  • As respostas saem da conta do usuário
  • Pode iniciar uma conversa quando o Facebook permite

Desative “Nova conversa” para uma Página. Corpo da requisição, anexos e erros: veja como enviar uma mensagem do Messenger via API.

Operação

Opere para todos os clientes: status, permissões e regras da Meta

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.

Admin · Contas conectadas Parcial
ConexãoStatus
FacebookAnna RossiMensagens · conta pessoalrunning
Página Coveton Apparelpage_<page_id>running
Página Coveton OutletFunção de admin removidadisconnectedReconectar
STATUS 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.

Defina quem vê quais conversas

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.

Conformidade

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.

App da Meta ou App Review?Não é necessário: os usuários se conectam pelo Hosted Auth.
Parceiro oficial da Meta?Não. A Unipile não é um app oficial da Meta nem Meta Partner.
Termos da Meta?Todo usuário continua sujeito a eles.
Digital Markets Act?Sem armazenamento de perfis. Veja a nossa página sobre o Digital Markets Act.

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.

Comissão Europeia
Regulamentado pela UE Digital Markets Act (DMA)

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.

Perguntas frequentes sobre a integração do Facebook Messenger com CRM

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