EN
CRM integration guide

Facebook Messenger CRM Integration: How to Build It into Your Product

For teams building a CRM or SaaS: connect each user's Facebook account and Pages, sync conversations, match contacts, reply from the record.

Your CRM · Messenger Synced
Leo MartinDo you ship the linen jacket to Lyon?Matched · LeadCoveton Apparel
Sara KimThanks Anna, I'll sign tomorrow.Matched · DealPersonal
Omar HaddadYou: Your order left the warehouse.Matched · CustomerCoveton Apparel
Webhooks message.new message.receipt.read
GET api.unipile.com/v2/{ACCOUNT_ID}/chats 200 OK
Short answer

A Facebook Messenger CRM integration syncs each user's Messenger conversations onto CRM contact records and lets them reply from the CRM. This guide is for teams building that integration into their own CRM or SaaS product, not for businesses choosing a CRM.

It takes four building blocks: one connection per user, history plus real-time sync, contact matching, and replies as the right identity.

With Unipile

Build it with Unipile in three steps

  1. 1

    Connect each user's Facebook account and Pages through Hosted Auth. No Meta app, no App Review.

  2. 2

    Backfill their chats with GET /v2/{account_id}/chats, sending your X-API-KEY header.

  3. 3

    Receive new messages, edits and reactions by webhook, starting with message.new.

Definition

What Is a Facebook Messenger CRM Integration?

A Facebook Messenger CRM integration links Messenger conversations to a CRM, so each message lands on the right contact record and users reply without leaving the CRM. For a business, it is a connector it switches on. For a product team, it is a feature it builds into its own CRM or SaaS: this guide covers that case.

Either way: read, attach to a contact, reply from the CRM, in real time, per user. Our overview of how the Facebook APIs fit together covers Meta's platforms.

Your CRM · Contact Live
Leo MartinLead · Lyon
OwnerAnna Rossi
ChannelMessenger · Coveton Apparel page
Facebook ID{FACEBOOK_USER_ID}
ActivityEmailMessenger 2Deals
FacebookPage inboxCoveton Apparel
Hi, do you ship the linen jacket to Lyon?10:40
Yes, delivery takes 3 days. Which size do you need?Coveton Apparel · 10:41
01

Read

History and new messages, per user.

02

Attach

Each conversation to one contact.

03

Reply

From the record, as the user or as the Page.

04

Stay live

Webhooks, not polling.

Approaches

How to Connect Facebook Messenger to a CRM: Three Ways

A no-code connector is quick but mostly one way. Meta's Messenger Platform is two way but Pages only, behind App Review. A per-user connection API covers personal accounts and Pages, with no Meta app.

QuestionNo-code connectorMeta Messenger PlatformPer-user connection (Unipile)
AccountsUsually one Facebook PageFacebook Pages (Business Pages) onlyPersonal accounts and the Pages they manage
DirectionMostly one way: message to leadTwo way, inside the 24-hour windowTwo-way sync: read, reply, react
Real timeOften polling, every 15 minutes on some plansMeta webhooksWebhooks such as message.new
You operateOne workflow per setupMeta app, App Review, a token per PageA Hosted Auth link, one account_id per user
HistoryVaries by connectorPage conversationsPersonal chats and each Page inbox
Other channelsOne connector eachOne integration per Meta productSame API for LinkedIn, WhatsApp, Instagram, email
Accounts
No-codeUsually one Facebook Page
MetaFacebook Pages only
UnipilePersonal accounts and the Pages they manage
Direction
No-codeMostly one way: message to lead
MetaTwo way, inside the 24-hour window
UnipileTwo-way sync: read, reply, react
Real time
No-codeOften polling, every 15 minutes on some plans
MetaMeta webhooks
UnipileWebhooks such as message.new
You operate
No-codeOne workflow per setup
MetaMeta app, App Review, a token per Page
UnipileA Hosted Auth link, one account_id per user
History
No-codeVaries by connector
MetaPage conversations
UnipilePersonal chats and each Page inbox
Other channels
No-codeOne connector each
MetaOne integration per Meta product
UnipileSame API for LinkedIn, WhatsApp, Instagram, email

Zapier or Make suit one business and one Page, and Meta Business Suite gives that business an inbox for its own Page. A multi-customer product needs the integration in its own code.

On Meta's route, every customer Page needs a Page access token and permissions reviewed by Meta, as our Facebook Page API guide shows. Replies follow the 24-hour window and message tags, several of which Meta retired in 2026. And it never reaches the personal accounts sales reps and advisors use with clients.

Sources: Meta's Messenger Platform send messages, Unipile's provider features. Last verified: November 17, 2026.

Connection

Connect Each User's Facebook Account and Pages

Each CRM user opens a Hosted Auth link and signs in to Facebook, two-factor authentication included. Your CRM receives one account_id that covers their personal account and every Page they administer, all activated by default.

1

Open a Hosted Auth link

Your backend requests it; the user opens it.

Hosted Auth
2

Sign in and unlock history

Credentials, 2FA, then optional history unlock.

ENCRYPTED_HISTORY
3

Store the account_id

Save it on the CRM user. Their Pages come with it.

{ACCOUNT_ID}

Pages are activated through the page product at link or reconnection; a Page not activated returns 403 api/insufficient_permissions. The sign-in is detailed in our guide to the Facebook Messenger API for personal accounts.

Source: Unipile Facebook Pages documentation. Last verified: November 17, 2026.

Sync

Sync Conversation History and New Messages in Real Time

Backfill through the API first: personal chats, then each Page inbox. Then switch to webhooks, so every new message, edit, receipt or reaction reaches your CRM in real time, as listed on our Facebook Messenger API page.

FacebookSourcePersonal account + PagesOne per CRM user
ConnectionUnipileOne account_id
Data inBackfill, then webhooksGET /chats once, message.new after
Your codeSync serviceRoutes, matches, dedupes
Your dataCRM databaseContacts and messages

Backfill personal chats and Page inboxes

The account's chat list holds personal conversations only; each Page has its own inbox, PAGE_<page_id>_INBOX. Lists return up to 100 items per page, newest messages first: page back as deep as your CRM needs.

Base URL https://api.unipile.com · header X-API-KEY
GET/v2/{account_id}/chatsPersonal chats of the connected account
GET/v2/{account_id}/inboxes/{inbox_id}/chatsChats of one Page inbox
GET/v2/{account_id}/chats/{chat_id}/messagesMessages of a chat, newest first

Encrypted chats and history

Personal 1:1 and group chats are end-to-end encrypted; Page conversations are not. Past personal messages sit in an encrypted backup the user unlocks with their recovery code or Messenger PIN, in a step Hosted Auth shows at connection. Without it, only messages since the connection are available.

Webhooks

One webhook URL serves every connected account. Page events carry the Page-scoped chat ID, so route them by the PAGE_<page_id>_ prefix. Events available for Facebook:

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

Sources: Unipile retrieve chats and messages, encrypted chats, provider features and configure a webhook. Last verified: November 17, 2026.

Try it

Connect a Facebook account in your trial workspace

Link an account, list its chats and point a webhook at your service. 7-day free trial, no credit card.

Build Now
Data model

Match Messenger Conversations to CRM Contacts

Attach each conversation to a contact through the Facebook ID of the other person, never through the display name. Route Page and personal conversations by the PAGE_<page_id>_ prefix of the chat ID.

IdentifierStore it onWatch out
Facebook ID of the other personThe contact: your matching keyNever match on the display name
account_idThe CRM user who connected FacebookCovers the personal account and Pages
Personal chat IDThe conversationNot a contact key
Page chat ID PAGE_<page_id>_<thread_key>The conversation and its PageThe prefix makes Unipile act as the Page
Page ID and Page profile IDThe Page ID, on inbox and statusPage authors use the profile ID: never compare the two
Facebook ID of the other person
Store it onThe contact: your matching key
Watch outNever match on the display name
account_id
Store it onThe CRM user who connected Facebook
Watch outCovers the personal account and Pages
Personal chat ID
Store it onThe conversation
Page chat ID
Store it onThe conversation and its Page (PAGE_<page_id>_<thread_key>)
Watch outThe prefix makes Unipile act as the Page
Page ID and Page profile ID
Store it onThe Page ID, on inbox and status
Watch outPage authors use the profile ID: never compare the two

One trap: for the same conversation, the chat ID returned by the API can differ from the one in a webhook event. Store both on the conversation and reconcile them on the CRM side, anchored on the contact's Facebook ID. "Find Chats by User" returns a contact's existing chats, or an empty list.

A message.new handler that writes to the contact record

readUnipileEvent stands for your payload mapping.

// 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 · one contact per Facebook ID, one row per message ID
200 OK · one contact per Facebook ID, one row per message ID

Chat ID formats from the Facebook Pages documentation, chat lookups from retrieve chats and messages.

Reply

Reply from the Contact Record, as the User or as the Page

Send the reply into the conversation's chat ID. A Page chat ID replies as the Page; a personal chat ID sends from the user's own account. The composer shows which identity applies.

Your CRM · Leo Martin Page conversation
Size M, please. Can it arrive by Friday?10:42
Yes, if you order before 2pm today.Coveton Apparel · 10:44
Perfect, ordering now.10:46
Reply asAnna RossiFacebookCoveton Apparel page
Thanks Leo, your order is confirmed. Tracking link to follow.
New conversationSend

A Page only answers people who wrote to it.

POST /v2/{ACCOUNT_ID}/chats/{CHAT_ID}/messages/send 200 OK
From a Page chat
  • Replies go out as the Page
  • No new conversation: 501 api/not_implemented
  • No deleting its messages: same error
From a personal chat
  • Replies go out from the user's account
  • Can start a conversation when Facebook allows it

Grey out "New conversation" for a Page. Request body, attachments and errors: see how to send a Messenger message via API.

Operations

Run It for Every Customer: Status, Permissions and Meta's Rules

Show the state of every connection. Each Page reports its own status, so one broken Page does not stop personal messages or other Pages.

Admin · Connected accounts Partial
ConnectionStatus
FacebookAnna RossiMessaging · personal accountrunning
Coveton Apparel pagepage_<page_id>running
Coveton Outlet pageAdmin role removeddisconnectedReconnect
STATUS metadata.products_connection_status per Page

Each Page has its own key in metadata.products_connection_status, named page_<page_id>. When a Page goes down, the account turns partial or degraded. A Page whose admin role was lost stays disconnected until reconnection: show it and offer a reconnect.

Decide who sees which conversations

Show personal conversations to their owner and chosen managers, Page conversations to the Page team, in a unified inbox with assignment and tags. Same model as a messaging API for CRM software covering LinkedIn, WhatsApp and email, and the reason a unified messaging API lets you add Messenger without a new connector.

Compliance

Each user connects their own account

For CRM, support, advisors or an AI agent whose drafts a person approves. No bulk sending.

Meta app or App Review?Not needed: users connect through Hosted Auth.
Official Meta partner?No. Unipile is neither an official Meta app nor a Meta Partner.
Meta's terms?Every user remains bound by them.
Digital Markets Act?No profile storage. See our Digital Markets Act page.

Start building your Messenger integration

A Facebook Messenger CRM integration is one connection per user, a backfill then webhooks, contacts matched on Facebook IDs and replies as the right identity. The same code serves LinkedIn, WhatsApp and email. 7-day free trial, no credit card.

European Commission
EU Regulated Digital Markets Act (DMA)

Each user connects their own account, with no profile storage. Unipile is not a Meta Partner. Unipile and the DMA

All Facebook API endpoints in one place

Messenger is one part of the picture. See every Facebook endpoint available with Unipile, from posts and comments to profiles, or start from our complete Facebook API guide.

Facebook Messenger CRM Integration FAQ

CRM messaging, automated replies and multiple Pages.

So conversations stop living in one person's phone. Every message lands on the contact record, the team sees the full history, and follow-ups, assignment and reporting work on Messenger as they do on email.

Sending and receiving messages on Messenger, WhatsApp, LinkedIn or email from inside a CRM, each conversation attached to a contact. A Facebook Messenger CRM integration covers one channel; a unified messaging API brings the others through the same data model.

Keep a person in the loop: an AI agent drafts a reply from the contact's history and a user approves it before sending. Users remain bound by Meta's terms: no unsolicited or bulk messages.

Yes. Every Page the user administers is activated by default on the same account_id, each with its own inbox (PAGE_<page_id>_INBOX) and its own status. Show each Page as a separate inbox in your CRM.

Still have questions? Our team is here to help.

Talk to an expert