Updated on October 25, 2026
There are two ways to have several agents on the same WhatsApp number: the linked devices of the WhatsApp Business app, which have a device limit, or the official WhatsApp Business API, where the number is run by a system and agents work in a shared inbox, with no cap on people set by Meta. With the API, routing, history and permissions live in your software. With coexistence, the phone can even keep working alongside it.
The limits of the WhatsApp Business app
The app was built for manual use. According to the WhatsApp Help Center, a business account can link up to four devices; the multi-agent feature raises that to up to 10, depending on the benefits of subscriptions such as Meta Verified. That works for a small shop, but it breaks down as the team grows:
- Everyone sees everything. There is no queue and no “mine” or “yours”. Two agents answer the same customer, or nobody does.
- No per-person metrics. You cannot tell who replied, how fast, or how many chats each person resolved.
- Dependence on the primary phone. If the primary device goes unused for about 14 days, linked devices are disconnected.
- No integrations. The app does not talk to your CRM, ERP or bot.
How the API solves it: the number becomes a system
On the official API, the number is not on a phone. Every incoming message reaches your server through a webhook, and every reply goes out through an HTTP call. An “agent” is not a device linked to WhatsApp but a user of your system. That is why Meta does not limit how many people can answer: the limit is your software’s.
| Aspect | App with linked devices | API with a shared inbox |
|---|---|---|
| Number of agents | Up to 4 devices (up to 10 with multi-agent) | Set by your system |
| Routing | Manual | Automatic, rule-based |
| History | On the device | In your database |
| Per-agent metrics | No | Yes, from the events |
| Bot and AI | Not native | Part of the same flow |
| Permissions | Whoever has the device sees everything | Per team, queue or role |
Shared inbox architecture
A multi-agent setup on the API has five parts:
- Webhook receiver. Receives Meta’s events, returns
200quickly and pushes the event onto a queue. Do no heavy work here. - Processor. Reads the queue, stores messages and statuses, opens or reopens the conversation, and calls the routing engine.
- Routing engine. Decides who handles it: the bot, a department queue or a specific agent.
- Agent interface. Assigned conversations, history and a reply box, updated in real time (WebSocket or similar).
- Sending layer. A single layer that calls the API, stores the returned
wamidand handles errors.
Two webhook details shape the design. Meta’s webhooks overview says unacknowledged events are retried for up to 7 days and that this can produce duplicate notifications. So:
- Deduplicate on the message
id(wamid). A unique constraint in the database is enough. - Do not rely on arrival order. Sort messages by the event
timestamp, not by when the webhook arrived.
Conversation states
A support conversation needs clear states. A simple model:
| State | Meaning | Who acts |
|---|---|---|
bot | Bot or automatic message handling it | System |
queued | Waiting for an agent in a department | Routing engine |
assigned | One agent owns the conversation | Agent |
waiting_customer | Agent replied, waiting for the customer | System watches the 24-hour window |
closed | Resolved | Reopens if the customer writes again |
The waiting_customer state matters because of the 24-hour customer service window: if the customer takes too long and the window closes, the agent can only resume with a template.
Routing rules
No rule fits every case. The most common ones:
| Rule | How it works | When to use it |
|---|---|---|
| Round robin | Next available agent on the list | Similar agents, similar demand |
| Least busy | Agent with the fewest open chats | Chats of varying length |
| By department | Bot asks the topic and routes to the right queue | Separate sales, support and billing |
| Sticky | Customer goes back to their last agent, if available | Consultative sales, account portfolios |
| Manual (pull from queue) | Agent picks the next chat | Small teams, complex cases |
In practice, combine them: the bot or welcome message asks the topic, the chat goes to that department’s queue, and within the queue you use least busy, with stickiness for returning customers.
Example: conflict-free assignment in PostgreSQL
The most common bug is two agents grabbing the same chat. With FOR UPDATE SKIP LOCKED, each transaction locks the conversation it is assigning and skips those another transaction already holds:
-- Assign the oldest queued conversation to the agent with the fewest open chats
WITH next_conv AS (
SELECT id
FROM conversations
WHERE state = 'queued' AND department = 'support'
ORDER BY queued_at
LIMIT 1
FOR UPDATE SKIP LOCKED
),
agent AS (
SELECT a.id
FROM agents a
LEFT JOIN conversations c ON c.agent_id = a.id AND c.state = 'assigned'
WHERE a.online AND a.department = 'support'
GROUP BY a.id, a.max_concurrent
HAVING COUNT(c.id) < a.max_concurrent
ORDER BY COUNT(c.id)
LIMIT 1
)
UPDATE conversations
SET state = 'assigned', agent_id = (SELECT id FROM agent), assigned_at = now()
WHERE id = (SELECT id FROM next_conv)
AND EXISTS (SELECT 1 FROM agent)
RETURNING id, agent_id;Run it when a chat enters the queue and when an agent frees up. The max_concurrent field keeps anyone from getting more chats than they can handle.
Operating best practices
- Show who is replying. Prefix messages with the agent’s name (“Ana:“). The customer knows who they are talking to and handoffs stay transparent.
- Hand off with context. When transferring a chat, add an internal note. The customer should not have to repeat everything.
- Mark as read only when someone has read it. The
readstatus shows the two blue ticks to the customer; send it when the agent opens the chat, not when the webhook arrives. - One sending path. Bot, agents and automations should all go through the same layer, so you respect the number’s throughput and log everything.
- Least privilege. Agents see their own queue; supervisors see the team. The guide on business account security covers portfolio access and tokens.
- Measure. First response time, handling time and satisfaction per agent and per queue. See WhatsApp support metrics.
Coexistence: the phone keeps working
With coexistence, the same number runs on the WhatsApp Business app and the API at the same time. The owner can keep replying from the phone while the team uses the inbox. According to Meta’s coexistence documentation:
- Messages sent from the app reach your system through the
smb_message_echoeswebhook. Show them in the conversation history, or agents will not know the customer has already been answered. - The app supports up to four companion devices. Messages sent from unsupported companions (such as WhatsApp for Windows) do not trigger webhooks and will not show up in your system.
- Throughput for coexistence numbers is fixed at 20 messages per second.
- App tools such as quick replies, labels, greeting and away messages are not supported on the Cloud API.
- If the primary device is inactive for about 14 days, Meta sends an
account_updatewithPARTNER_REMOVEDand the API connection drops.
For multi-agent support, the rule of thumb is: the phone becomes one more “agent”, and your system has to treat its messages that way. The article on what syncs in coexistence goes through each item.
How to do this with Vectalk
Vectalk is the API layer: it delivers Meta’s webhooks to your system and sends replies through the official Cloud API. You can register several URLs per instance with POST /api/webhooks (for example, your inbox and your CRM receiving the same event), send with POST /api/messages, and mark as read with the same endpoint using status: "read". Vectalk supports coexistence, so the number can stay on the app. The inbox and routing rules belong to your software. Documentation at docs.vectalk.com.br and sign-up at apps.vectalk.com.br/register.
If you plan to put a bot in front of your agents, see also AI scheduling on WhatsApp.
Frequently asked questions
How many agents can I have on one number with the API?
Meta does not limit the number of agents on the API, because they are not WhatsApp devices but users of your system. The practical limit is your software and the number’s sending capacity.
Can I use WhatsApp Web together with the API?
Only with coexistence, where WhatsApp Web acts as a companion device of the app. Messages sent from it reach your system through the smb_message_echoes webhook. Without coexistence, a number registered on the API is not available in the app or on WhatsApp Web.
How do I stop two agents from answering the same customer?
Assign the conversation to an owner before showing the reply box, with a database lock (like FOR UPDATE SKIP LOCKED in the example). Everyone else sees the chat as read-only.
Does the customer see the agent’s name?
The customer sees the business display name. If you want to show who is handling the chat, include the name in the message text.
Do I need one number per department?
No. One number with department queues is usually simpler for the customer. Separate numbers make sense for different brands or operations.
Official sources consulted on October 25, 2026: Webhooks overview, Coexistence: onboarding WhatsApp Business app users, WhatsApp Help Center: multi-agent, Vectalk docs: webhooks, Vectalk docs: mark as read.