How to Connect WhatsApp to Your CRM: Step by Step

This is the practical version: what you actually do, in order, to get WhatsApp conversations appearing on CRM records. It assumes you own a business WhatsApp number and a CRM that can accept an API call.

Step 1: Link the business number

Connect the WhatsApp account using the standard linked-device flow — the same pairing you already use for WhatsApp on desktop. Scan once from the business phone and the session is established.

Two things worth getting right here. First, use a number the business owns, not an employee's personal number: personal numbers leave when people do. Second, if you run several numbers, connect one first and prove the whole pipeline before adding the rest.

Step 2: Decide what a message becomes

Before any code, answer three questions in writing:

• Which CRM object holds a message — an activity, a note, an engagement, or a custom object?
• What happens when the sender's number matches no existing contact?
• Where do attachments go — your CRM's file storage, or your own object storage with a link on the record?

These are the decisions that are painful to change later. Everything after this is mechanical.

Step 3: Register a webhook endpoint

Expose an HTTPS endpoint and register it, subscribing to the events you care about. At minimum that is inbound messages, outbound messages and connection state changes.

     {          "event"  :     "whatsapp.message.received"  ,          "id"  :     "evt_01H9X2K7Q4ZB3M"  ,          "created_at"  :     "2026-03-04T09:41:07Z"  ,          "connection"  :     {            "id"  :     "conn_sales"  ,            "name"  :     "Sales"  ,            "phone"  :     "+971 4 000 0001"  ,            "status"  :     "healthy"          }  ,          "message"  :     {            "id"  :     "msg_3EB0C9D1A7F2"  ,            "direction"  :     "incoming"  ,            "type"  :     "text"  ,            "text"  :     "I'm interested in the property"  ,            "timestamp"  :     "2026-03-04T09:41:06Z"  ,            "chat"  :     {              "id"  :     "chat_971500000000"  ,              "name"  :     "Amira Khan"  ,              "phone"  :     "+971500000000"            }          }      }   

During development, point the webhook at a tunnel to your machine. The delivery log shows every attempt and the response your endpoint gave, which makes debugging straightforward.

Step 4: Verify the signature

Your endpoint URL will eventually be discovered. A signature is what stops a discovered URL from being an open write path into your CRM.

     import   crypto   from     "node:crypto"  ;           // Verify that an event really came from WhatSyncs before acting on it.      export     function     verifySignature  (  rawBody  ,   header  ,   secret  )     {          const     [  timestamp  ,   signature  ]     =   header  .  split  (  ","  )  ;          const   payload   =   timestamp   +     "."     +   rawBody  ;          const   expected   =   crypto            .  createHmac  (  "sha256"  ,   secret  )            .  update  (  payload  )            .  digest  (  "hex"  )  ;               const   a   =   Buffer  .  from  (  signature  )  ;          const   b   =   Buffer  .  from  (  expected  )  ;          if     (  a  .  length   !  =  =   b  .  length  )     return     false  ;          return   crypto  .  timingSafeEqual  (  a  ,   b  )  ;      }   

Step 5: Acknowledge fast, process later

Return a 2xx as soon as the event is durably accepted — written to a queue or a table — then do the CRM work asynchronously. Calling your CRM's API inside the handler works right up until the CRM has a slow day, at which point your handler times out, the delivery is retried, and you get duplicates.

     app  .  post  (  "/webhooks/whatsyncs"  ,     async     (  req  ,   res  )     =  >     {          if     (  !  verifySignature  (  req  .  rawBody  ,   req  .  get  (  "X-WhatSyncs-Signature"  )  ,   SECRET  )  )     {            return   res  .  sendStatus  (  401  )  ;          }               // Acknowledge fast, then process out of band. WhatSyncs retries on timeout,          // so slow handlers cause duplicate deliveries rather than lost events.        res  .  sendStatus  (  200  )  ;               const   event   =   req  .  body  ;          const   key   =   req  .  get  (  "X-WhatSyncs-Idempotency-Key"  )  ;          if     (  await     seenBefore  (  key  )  )     return  ;               await   queue  .  publish  (  "whatsapp-events"  ,     {   key  ,   event   }  )  ;      }  )  ;   

Step 6: Match the contact

Normalize the phone number to a consistent format — international, digits only — before you search. Storing numbers in three different formats is the most common reason matching fails.

1. Search existing contacts by the normalized number.
2. If exactly one matches, use it.
3. If several match, prefer the most recently active and flag the duplicate for cleanup.
4. If none match, apply your unmatched policy rather than creating a contact reflexively.

A staging queue for unmatched conversations sounds like extra work. It is considerably less work than deleting eight thousand junk contacts later.

Step 7: Write the record, idempotently

Key the write on the message identifier and make it an upsert. Record the delivery's idempotency key before processing, and skip anything you have already seen. Both matter: the identifier protects against the same message arriving through different paths, the key protects against the same delivery arriving twice.

Step 8: Handle media in a worker

Media arrives as a separate event with metadata and a short-lived authenticated download URL. Enqueue the media id, download it in a worker, and store it against the record you already wrote. Downloading a 12 MB video inside the webhook handler is the same mistake as step five, wearing a different hat.

Step 9: Alert on connection events

Subscribe to connection events and route them into whatever pages your on-call. A disconnected WhatsApp session is an outage — customers are messaging a number nothing is listening to.

Add a tile to an operations dashboard showing every connection and its state. It costs an hour and it is the first thing anyone looks at when someone says the integration is broken.

Step 10: Roll out to the rest

Once one number has been running cleanly for a week, connect the others. Nothing about the integration changes — each connection produces the same events with a different connection value, which is what your routing rules key on.

Common mistakes

What good looks like

A week in, you should be able to open a customer record and read the conversation, open the brochure that was sent, and see how long the first reply took — without asking anyone for a screenshot. That is the whole objective.