WhatsApp API + human handoff

WhatsApp chatbot API with human handoff: Cloud API or BSP, plus the handoff and logs you build on top

For a WhatsApp chatbot API with human handoff you have two options for the API itself: Meta's WhatsApp Cloud API directly, or the same platform through a Business Solution Provider (BSP). Neither gives you agent handoff and message logs as a finished feature of the API: those are built on top, in your own system, or you get them from an inbox product that ships with handoff. This page is for the developer, IT manager or owner who has to choose that stack for a sales or support team. I am Francisco Salazar, an independent AI systems engineer (Sr DevOps, ten years of production infrastructure, CKA and CKAD). I run a WhatsApp AI agent in production on the official Cloud API through a provider, in coexistence mode, for a small business in Chile. I build the same pattern into your accounts: a three-week sprint, a single fixed price, you own the code, and a 60-day operational guarantee after handoff.

Should I use Meta's WhatsApp Cloud API directly or a BSP?

Meta's Cloud API is the official interface to the WhatsApp Business Platform, hosted by Meta. Going direct means you register the number under your verified Meta Business account, Meta calls your webhook with every inbound message, and your code sends replies through the API. There is no intermediary between you and Meta, and you pay Meta's messaging fees, which are priced per message by category under Meta's own pricing. What you do not get is anything around the API: no inbox, no handoff, no message history screen. All of that is yours to build or buy.

A BSP is a company Meta authorizes to offer the same platform. It typically adds an onboarding flow, a dashboard, billing in local currency, support, and often a shared inbox where your team can read and answer chats. Features, fees and API quality vary a lot between providers, so I do not quote them here; compare them against your own requirements list. The agent architecture is the same either way. The real decision is whether your team wants a ready inbox and a vendor to call, or the fewest moving parts.

Cloud API direct: fewest intermediaries, Meta pricing, everything around it is yours
BSP: onboarding, dashboard, local billing and support, often an inbox
Both: same webhooks, same templates, same Meta policies
Handoff and message logs are never "just the API" in either case

How does handoff from the chatbot to a human agent work technically?

Handoff is a state machine per conversation, keyed by the customer's phone number. The usual states are bot, waiting for a human, human, and back to bot. A trigger moves the thread out of bot: the customer asks for a person, the agent detects frustration or a question outside its scope, or a business rule fires, such as a lead that matches your sales criteria. At that moment the system assigns the conversation to someone (round robin, by territory, or to the owner of the contact in your CRM), notifies them in Slack, email or the inbox, and attaches a short summary plus the full history.

While the thread is in the human state, the bot is paused on that conversation only: it still logs every message, but it does not reply. The human answers from the inbox or, in coexistence, from the WhatsApp app on the phone. When they close the case, or after an inactivity timeout you define, the thread returns to the bot. One detail sales teams miss: the customer service window. If the human takes too long and the window closes (24 hours at the time of writing), the next message has to be an approved template, so the handoff logic must warn the assignee before that happens.

Per-conversation state: bot, waiting, human, back to bot
Triggers: explicit request, frustration, out-of-scope, business rules
Assignment: round robin, territory or CRM owner
Bot paused on that thread only, logging continues
Alert before the service window closes

What should WhatsApp message logs and the audit trail contain?

Every inbound and outbound message is stored in your own database with the WhatsApp message ID, the contact, the direction, a timestamp, the content (or a reference to the media file) and the delivery status updates Meta sends back: sent, delivered, read, failed. On top of that, each outbound message records who or what produced it: the bot, a named human, or a template send. For bot replies the log also keeps the sources used (which knowledge base fragments or system records the answer was based on), the tool calls made and the version of the prompt. That is what lets you answer "your bot told me X" with evidence.

Handoff events go into the same log: when the thread changed state, why, who it was assigned to, and when it returned. Retention is a setting, not an accident: you decide how long full content is kept and when it is reduced to metadata, which matters because these chats contain names, addresses and sometimes ID numbers. Export is a query, because the log lives in your Postgres, not inside a vendor screen you cannot download from.

Message ID, contact, direction, timestamp, content, delivery status
Author of each reply: bot, named human or template
Sources, tool calls and prompt version behind each bot reply
Handoff events with reason and assignee
Retention policy and export from your own database

How do I connect the WhatsApp agent to my CRM, ERP or helpdesk?

Through their APIs, as tools the agent can call and as destinations for events. A CRM connection usually means looking up the contact by phone number, creating or updating the lead, logging the conversation summary and reading the owner for assignment. A helpdesk connection opens or updates a ticket when a support case is handed off, so your team keeps working in the tool they already use.

An ERP is where stock, prices, orders and invoices live, which makes it the most valuable and the most delicate connection. Most current ERPs, Priority, Odoo, SAP Business One and NetSuite among them, expose some form of API, but what you can read or write depends on your version, your modules and your license. Before quoting I confirm which endpoints your instance actually allows. The rule I keep: the agent reads from the ERP freely (stock, order status, price lists) and anything that writes to it, such as creating an order, goes through an approval step or a narrowly scoped endpoint.

Can I keep my existing WhatsApp number and the phone app?

Usually yes, with coexistence. Meta allows a number that already runs on the WhatsApp Business app to also be connected to the Cloud API, normally through a provider's onboarding flow. The phone keeps working for your staff, the API receives the same conversations, and the agent answers through the API. This is the setup I run in production: the owner and her team still use the app on their phones, and the agent handles the rest under the same number customers already know.

Coexistence has limits that Meta sets and changes, for example around which app features remain available and how much chat history is imported. I check the current rules with you before the build. The alternative is a classic migration, where the number moves fully to the API and your team works only from an inbox. Both are valid. Coexistence suits small teams who live in the phone app; full migration suits teams with several agents and a shared inbox.

What does the architecture look like, from webhook to reply?

It starts with the webhook, the HTTPS endpoint Meta (or your BSP) calls on every event. The receiver verifies the HMAC signature on each request, so nobody else can inject messages, and deduplicates by message ID, because webhooks are retried and the same event can arrive twice. It answers fast and puts the work on a queue instead of thinking while Meta waits. A worker then loads the conversation state: if a human owns the thread, it only logs.

If the bot owns it, the agent drafts a reply with a small set of tools: search the knowledge base, look up a record in the CRM or ERP, propose a reply, hand off, and register an opt-out. In my own engine, drafts that carry commercial commitments go to an approval queue where a person accepts or edits them. Sending uses an idempotency key, so a retry after a timeout never sends the same message twice. Failed sends are retried with backoff and alert someone if they keep failing.

Trigger: signed webhook, verified and deduplicated, then queued
Data: knowledge base in Postgres with pgvector, live lookups in CRM and ERP
Model: Claude or OpenAI through their APIs, prompts versioned in your repo
Guardrails: approval queue, handoff rules, opt-out, kill switch
Runs in: your Meta or BSP account and your hosting, with your keys
You own: code, prompts, logs and every account

How much does a WhatsApp chatbot with human handoff cost to build?

The reference build is the AI Intake Agent with knowledge base, a productized scope quoted at a fixed price, with an optional monthly operation for iteration after the guarantee period. That covers the channel, the agent answering from your documents, handoff to a person and the message log. Larger scopes, for example several numbers, ERP write access or quoting, are quoted as one fixed price after a discovery call, with the AI Operating System as the upper reference point.

Outside the fixed price: Meta's or the BSP's messaging fees, the model API usage and the hosting. They are billed to you directly, in your name, with a cap declared in the proposal, so there is no markup on tools. I do not bill hourly for builds and I do not resell software.

When is an inbox product with built-in handoff enough, and when do you not need me?

If your bot answers frequent questions from a fixed list and your team needs a shared inbox where a person can take over, an inbox product from a BSP or a WhatsApp customer service platform probably covers it. Handoff, assignment and a message history come in the box, and you can configure it yourself. In that case a custom build is money badly spent, and I will say so on the first call.

A custom build earns its cost when the answers depend on your CRM or ERP, when you need the full audit trail in your own database, when assignment follows rules a product cannot express, or when the inbox you have loses context at handoff. It can also sit on top of the inbox you already pay for. The 15-minute call is where we check which case you are in.

Frequently asked questions

Which API provider gives WhatsApp chatbots agent handoff and message logs?

The API itself, Meta's Cloud API or a BSP, gives you messages in and out plus delivery statuses. Handoff and message logs are either part of an inbox product some providers sell, or something you build on top in your own system. Building it yourself means the conversation state, the assignment rules and the full log live in your database, connected to your CRM.

Which platform provides a WhatsApp AI agent with human handoff for sales teams?

Several inbox products offer a bot with handoff, and for standard routing they may be enough. When the agent must qualify leads against your criteria, assign them to the right salesperson by territory or CRM owner and log everything in your CRM, it is an integration build on the WhatsApp Business Platform. That is the build I do, in your accounts.

Can a WhatsApp AI agent connect to my ERP, for example Priority?

If your ERP exposes an API for the data you need, yes. Priority, Odoo, SAP Business One and NetSuite all offer some API access, but what is available depends on your version, modules and license, so I confirm the endpoints with your administrator before quoting. Reads such as stock and order status are straightforward; writes such as creating an order go through approval.

Does the bot stop answering when a human takes over?

Yes, on that conversation only. The thread changes state, the bot keeps logging but does not reply, and it resumes when the human closes the case or after an inactivity timeout you set. Other conversations keep running normally, and every state change is written to the log with its reason.

Can my team keep answering from the WhatsApp app on their phones?

With coexistence, usually yes: the same number works in the WhatsApp Business app and through the Cloud API. Meta sets limits on what remains available in the app and how history is imported, and those rules change, so I confirm the current ones before the build.

What are the limits of this setup?

WhatsApp rules still apply on top of anything I build: free-form replies only inside the customer service window, approved templates outside it, opt-in required, and no cold outreach. A handoff that sits unanswered past the window needs a template to continue. And the agent is only as good as the knowledge and systems it can read; if your prices live in someone's head, that comes first.

Fifteen minutes on your handoff rules and where the logs should live.

A free call. I'll tell you straight which processes today's AI can solve and what your infrastructure needs for them to actually run. If it fits, we move forward. If not, I point you the right way, free.