Skip to content

Playbook · 5 steps

CRM Integration(CRM)

Also called: WhatsApp CRM integration · WhatsApp CRM sync · CRM connector

5steps

Level
Practitioner
Reading time
About 5 min

Reviewed

Definition
A link that syncs WhatsApp conversations, contacts and events with a CRM, so agents see customer context and sales activity is logged automatically.

01 · How it works, in 5 steps

How does a WhatsApp CRM integration work?

  1. 1

    Subscribe to the webhook fields

    Subscribe your app to the messages field. Inbound messages and outbound statuses both arrive on it; verify every request with the X-Hub-Signature-256 HMAC before processing.

  2. 2

    Match or create the contact

    Look up the CRM contact by BSUID (user_id) first, then by wa_id. If neither matches, create a contact with both, plus the WhatsApp profile name.

  3. 3

    Log the activity idempotently

    Write each message as a CRM activity keyed on its wamid. Webhooks can be retried for days, so the same message must never create two activities.

  4. 4

    Send from the CRM through the Cloud API

    CRM workflows call your middleware, which sends a free-form message inside the 24-hour window or an approved template outside it, then records the returned wamid.

  5. 5

    Write outcomes back

    Map statuses (delivered, read, failed), conversation tags and consent changes to CRM fields so reports and segments stay accurate.

02Try it

Hands-on: use the controls to work through it yourself.

Trace one WhatsApp message into the CRM and back

9 / 9
  • CustomerWhatsApp app
  • Cloud APIMeta
  • MiddlewareYour webhook
  • CRMContacts & deals

Step 9 of 9Event

Cloud APIMiddleware

statuses: delivered, read

Written back to the CRM activity.

  • Request — solid arrow — a call that expects an answer
  • Response — dashed arrow — the answer coming back
  • Event — dotted arrow — something happened and is pushed out
  • Async — double head — fire-and-forget, nobody waits
Step through an inbound message travelling from the customer to the CRM record, and a CRM workflow sending a template reply. Each step names the field or call involved.

Step 9 of 9: Cloud API to Middleware — statuses: delivered, read. Written back to the CRM activity.

03What is a WhatsApp CRM integration?

A WhatsApp CRM integration is the connection between the WhatsApp Business Platform and a customer relationship management (CRM) system, so that conversations, contacts and events flow both ways. Inbound messages and delivery statuses are written to the right contact record; agents and sales reps see deal stage, orders and past conversations beside the chat; and actions in the CRM — a stage change, a follow-up task — can send WhatsApp messages.

Technically, the integration sits between two APIs. The Cloud API pushes events to your webhook: a messages webhook for every inbound message and a statuses webhook for sent, delivered, read and failed. Middleware (your own service, an iPaaS or your inbox provider's connector) matches each event to a CRM contact and creates or updates records through the CRM's REST API. In the other direction, the CRM calls the middleware, which posts to https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages.

Identity matching is the hard part. A messages webhook carries the sender's wa_id (digits, country code first) and, since early April 2026, a business-scoped user ID (BSUID) in user_id. When a user has adopted a WhatsApp username, the phone number can be left out of webhooks, so a CRM keyed only on phone numbers will miss people. Store both identifiers on the contact.

A CRM integration is different from a helpdesk integration. The CRM view is about the customer and the revenue relationship — leads, deals, accounts — while a helpdesk is built around tickets, queues and SLAs. Many businesses run both, and a customer data platform (CDP) may sit above them to unify profiles across channels.

Key takeaways

  • A WhatsApp CRM integration links Cloud API webhooks and the send endpoint to a CRM, so chats, contacts and outcomes live on the customer record.
  • Inbound messages arrive by webhook; your middleware matches the sender to a CRM contact and logs an activity.
  • Match contacts on the wa_id and the business-scoped user ID (BSUID); webhooks can omit the phone number for username users.
  • Outbound messages from the CRM go through the Cloud API messages endpoint, and outside the 24-hour window they must be approved templates.
  • A CRM integration serves sales and account context; a helpdesk integration serves ticket-based support.

04 · In code

A WhatsApp CRM integration in code

// Express handler: verify, then log each inbound message to a CRM
import crypto from "node:crypto";
import express from "express";
 
const app = express();
app.use(express.raw({ type: "application/json" })); // keep the raw body for HMAC
 
app.post("/webhooks/whatsapp", async (req, res) => {
  const sig = req.get("X-Hub-Signature-256") ?? "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.APP_SECRET)
    .update(req.body)
    .digest("hex");
  if (sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // acknowledge fast, process after
 
  const body = JSON.parse(req.body.toString("utf8"));
  for (const entry of body.entry ?? []) {
    for (const change of entry.changes ?? []) {
      const v = change.value;
      for (const msg of v.messages ?? []) {
        const contact = (v.contacts ?? [])[0] ?? {};
        // Generic CRM API: replace with your CRM's own endpoints
        const person = await crm.upsertContact({
          bsuid: contact.user_id ?? msg.from_user_id,
          waId: contact.wa_id ?? msg.from, // can be absent for username users
          name: contact.profile?.name,
        });
        await crm.logActivity({
          externalId: msg.id, // wamid: unique key makes retries harmless
          contactId: person.id,
          channel: "whatsapp",
          direction: "inbound",
          text: msg.text?.body ?? `[${msg.type}]`,
          at: new Date(Number(msg.timestamp) * 1000),
        });
      }
    }
  }
});

The crm object stands for your CRM's SDK or REST client; field names vary by CRM.

05 · Mistakes to avoid

Common mistakes with a WhatsApp CRM integration

  • Keying contacts on phone number only

    Username users can arrive without a phone number in the webhook. Store and match on the BSUID as well as the wa_id, and handle the user_id_update event when a user changes number.

  • Duplicate activities from retries

    Meta retries webhooks for up to 7 days when it does not get a 200, so the same message can arrive more than once. Use the wamid as a unique key on CRM activities.

  • Slow webhook handlers

    Calling a slow CRM API before responding causes timeouts and more retries. Acknowledge with 200 straight away and process from a queue.

  • CRM workflows ignoring the window

    A free-form message triggered by a stage change fails with error 131047 if the customer has not written in 24 hours. Route such automations to approved templates.

  • Syncing more personal data than needed

    Copying every message and attachment into a CRM widens your data-protection duties. Sync what teams use, restrict access and set retention.

06 · Key facts

A WhatsApp CRM integration: key facts and limits

Inbound path
Cloud API webhook (messages field) → middleware → CRM API
Outbound path
CRM → middleware → POST /{PHONE_NUMBER_ID}/messages
Contact keys
BSUID (user_id) and wa_id
Dedup key
The message wamid
Webhook retries
Up to 7 days on non-200 responses
Webhook signature
X-Hub-Signature-256, HMAC-SHA256 with the app secret

07Example: A Pune car dealership's lead desk

A Pune car dealership gets enquiries from click-to-WhatsApp ads. Each inbound message reaches its middleware by webhook; the ad referral and the BSUID are stored on a new CRM lead, and the lead is assigned to a sales rep by city. When the rep moves the deal to "Test drive booked", the CRM triggers a utility template confirming the slot. Read receipts and replies are logged on the lead, so the manager's pipeline report shows which ads produced test drives — without anyone copying chats by hand.

08 · Why it matters

Why does a WhatsApp CRM integration matter?

Without an integration, WhatsApp becomes a silo: agents ask for order numbers the CRM already knows, sales has no record of what was promised in chat, and marketing cannot tell which leads came through click-to-WhatsApp ads. Connecting the two lets agents answer faster, keeps the customer record complete for every team, and makes WhatsApp activity measurable in the same pipeline reports as calls and email.

09 · Pro tips

Best practices for a WhatsApp CRM integration

  • Show the latest order, open deals and last CSAT in a sidebar next to the chat, not in a separate tab.
  • Store the click-to-WhatsApp referral on the lead so ad spend can be tied to revenue.
  • Write opt-in and opt-out events to a dedicated consent field the marketing team must respect.
  • Log outbound template sends with the template name, so reports can compare follow-up templates.

10CRM FAQs

How does WhatsApp integrate with a CRM?+
Through webhooks and the messages API. Cloud API webhooks deliver inbound messages and statuses to middleware that writes them to the CRM, and the CRM sends messages back through the Cloud API messages endpoint.
Can a CRM send WhatsApp messages automatically?+
Yes, through the Cloud API. Inside the 24-hour window after a customer's last message it can send free-form replies; outside the window it must send an approved template, billed per delivered message by category.
What is the difference between a CRM integration and a helpdesk integration?+
A CRM integration attaches WhatsApp activity to contacts, leads and deals for sales and account teams. A helpdesk integration turns conversations into tickets with queues, statuses and SLAs for support teams.
Which identifier should a CRM use for WhatsApp contacts?+
Store both the wa_id and the business-scoped user ID (BSUID). The BSUID is present on webhooks even when a user with a username hides their phone number.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms