How WhatsApp Business API integration actually works

There are two versions of this integration in most people's heads. One is the diagram in a sales deck: a WhatsApp logo, an arrow, a CRM logo. The other is the thing you have to build. This guide is the second one, written for whoever has to make the requests actually work.

Cloud API or On-Premises: pick Cloud

The WhatsApp Business Cloud API is hosted by Meta. You call the Graph API over HTTPS, Meta handles the message infrastructure, and there is nothing for you to run. The older On-Premises API shipped as a Docker container you hosted yourself, and Meta is retiring it. If you are starting now, the Cloud API is the only sensible choice, and the WhatsApp Business web API endpoints you will find in older tutorials mostly refer to that deprecated path.

The architecture, in four moving parts

A working WhatsApp Business API architecture has four pieces, and every integration problem sits in one of them.

1. A Meta app and a registered phone number, with a permanent access token issued against a system user rather than a personal login.
2. Outbound calls: HTTPS POST requests to the /messages endpoint on graph.facebook.com, one per message.
3. A public webhook endpoint you own, which Meta calls with inbound messages and status updates. It must answer a GET verification challenge once, then accept POSTs and return 200 fast.
4. A queue or worker behind that webhook, because Meta retries anything you do not acknowledge quickly, and doing CRM work inline is how you end up processing the same message four times.

What a client library actually sends

There is no official WhatsApp Business API client for most languages, and you rarely need one. The API is a small number of JSON POSTs, so a WhatsApp Business API Python integration is usually twenty lines around the requests library, and the Node equivalent is the same shape. A text message is the simplest case: a recipient, a type, and a body.

Where a wrapper earns its place is in the parts that are tedious rather than difficult: refreshing tokens, validating webhook signatures, mapping the inbound payload shape into something your application recognises, and retrying failed sends with backoff. Write that layer once, keep it thin, and stay close to the documented request bodies so an API version bump is a small diff rather than an archaeology project.

Buttons and lists are a different message type

WhatsApp Business API buttons are not formatting applied to a text message. Interactive messages are their own type, with their own payload structure, and the reply arrives back through the webhook carrying the button ID you set rather than the label the user saw. Design around the IDs, because labels get edited and translated.

• Reply buttons: up to three, best for a yes/no/other branch in a flow.
• List messages: up to ten rows in sections, for menus that would be unreadable as buttons.
• Call-to-action URL buttons: send the user out to a booking page or a payment link.
• Template buttons: attached to a pre-approved template, and changing them means resubmitting the template for approval.

Do not automate WhatsApp Web

Searching for WhatsApp web automation using Python turns up plenty of Selenium scripts that drive the browser client. They work in a demo and they are a bad idea in production: it is against the WhatsApp terms of service and risks the number being banned, it breaks whenever the web UI changes, it cannot receive webhooks reliably, and it has no delivery reporting. The official API costs money per conversation, which is the whole reason people look for the workaround, but a banned number costs considerably more.

The chat interface, if you need to build one

If agents will handle conversations in your own product rather than in a vendor inbox, you are building a chatbot React interface on top of the same webhook data: a thread list, a message pane subscribed to a websocket or a polling endpoint, and a composer that posts to your send wrapper rather than to Meta directly. Keep the transport in your backend. A front end holding an access token is a leak waiting to happen.

The CRM hop

A conversation that never reaches the CRM is a conversation nobody can follow up. The usual pattern is a worker that resolves the phone number to a contact, creates one if it does not exist, appends the message to the timeline, and updates a stage or an owner when the flow reaches a qualifying answer.

On the HubSpot side that means the Contacts and Timeline endpoints of the HubSpot API, authenticated with a private app token rather than the long-deprecated API key. The same integration usually grows a second job: a HubSpot API send email call for the follow-up that belongs in a mailbox rather than a chat thread, so the two channels stay on one contact record instead of two systems.