If your own bot answers your customers (for example in an automation tool), use this page so it stops when a person on your team steps in. Full examples are in the API docs: Settings → Developer → Docs → Chat control for external bots.
What your bot receives
Each message.received webhook for WhatsApp carries these fields inside data:
control: who holds the chat. It hasowner(botorhuman),since,untilandreason.social_account_id: the WhatsApp number that received the message.recent_turns: up to 20 recent messages, oldest first. Each hasspeaker(customer,stafforbot),textandat.
Example: "control": { "owner": "human", "since": "2026-11-02T13:05:33.431+00:00", "until": "2026-11-02T15:05:33.431+00:00", "reason": "agent_replied" }
You still receive messages while a person holds the chat, so your bot keeps the context.
Stop your bot in your automation tool
- Right after the Webhook node, add an IF node that continues only when
{{ $json.body.data.control.owner }}equalsbot. - On the node that sends the reply, set On Error to continue. A person can step in while the bot is writing, and nashir then refuses the send with a 409.
- End that branch when the response has
codeset tochat_controlled_by_human. Do not send the reply again. Nothing reached the customer, and this is the correct result.
Hold or release a chat from your own tool
Use GET and POST /api/v1/conversations/control:
- Send
platform,keyandaccount_id. On WhatsApp,keyisphonefrom the webhook, andaccount_idissocial_account_id. - For
POST, addaction:takeorrelease. - On
take, you can addtimeout_seconds(60 to 86400) so the hold ends by itself. Without it, the hold lasts until released, up to the maximum set for the business. - On
take, you can addreason:manual_pause(default),agent_repliedorstaff_takeover. - A
404means this chat has no messages, so no hold was created. Checkkeyandaccount_id.
When a person types through your own tool
Add "sender": "staff" on POST /api/v1/messages or POST /api/v1/messages/:id/reply. The send goes through even during a hold, and a successful send holds the chat for 2 hours. Never set it on messages your bot writes.
Get told when a chat changes hands
The control.changed event fires whenever a chat changes hands. Its data has platform, conversation_key, social_account_id, change (take, renew, release or expire), owner, reason, until, actor and at.
When until moves: on WhatsApp, Facebook, Instagram, TikTok DMs and web chat, each customer message during a timed hold moves until to 2 hours after that message, if it was earlier. This includes a hold you set with timeout_seconds. It fires renew with actor system. Another staff reply also moves it and fires renew. A hold with until set to null stays open-ended, and a hold that has already ended does not come back.
A release no person pressed: you may get change release with actor system and reason private_reply_awaiting_user. The chat was waiting for the customer to answer a private reply to their comment, and they just did. Nobody on the team handed the chat back.
To subscribe, open Settings → Developer → Webhooks, press Edit events on your webhook, tick Chat control changed, and save. If you add a separate webhook instead, check its signature with its own secret.
Facebook and Instagram messages
Your bot can answer Facebook and Instagram direct messages too:
- Open Settings → Developer → Webhooks and press Edit events.
- Tick Facebook Message Received, Instagram Message Received, or both, and save.
- Reply with
POST /api/v1/messages/:id/reply, usingnashir_message_idfrom the webhook as:id, andmessageas the text.
These webhooks carry channel, sender_id, sender_name, page_id, nashir_message_id, message_id, content, media_type, media_url, control, social_account_id and recent_turns. In the control API, key is sender_id, and platform is facebook_dm or instagram_dm. Comments are not forwarded.
Always reply through nashir's API, never with your own Meta token. Meta tells us about every message your Page sends. A reply sent with another token looks like a person on your team, so the chat is held and your bot stops itself.
When Meta refuses a reply, you get a 424:
outside_messaging_window: the customer's last message is over 24 hours old. Wait for the customer to write again. Meta's window is 24 hours, and up to 7 days after a first message from a Click-to-Messenger or Click-to-Direct ad.another_app_holds_thread: another app controls this conversation on Meta, such as Meta Business AI. Check Conversation Routing in your Page's settings.
If a nashir bot already answers on that channel, turn one of them off. Otherwise customers get two replies. Once your webhook subscribes to a channel, its chats show in the inbox that your own bot is answering, with a Pause bot button.
Send your text exactly as written
By default, nashir checks a WhatsApp text you send through POST /api/v1/messages against your catalogue and knowledge, and may turn it into a product list. If your own bot writes the final answer, add "skip_presentation": true to the request. The text is then sent exactly as given: nashir makes no product or knowledge lookup and no AI call for that message. POST /api/v1/messages/:id/reply accepts the same field.
Show "typing…" while your bot prepares a reply
Call POST /api/v1/messages/typing with account_id (the social_account_id from the webhook) and message_id (the message_id from the webhook). The customer sees "typing…" on WhatsApp for up to 25 seconds, or until your reply arrives. It also marks the message read. Use it only when your bot will reply, and call it again if the reply takes longer than 25 seconds. A repeat within 5 seconds sends nothing new. If a person on your team holds the chat, the call is refused with a 409 and code set to chat_controlled. In the community node, the operation is Nashir WhatsApp → Show Typing (version 0.19.0 and later).
Older endpoints
These keep working. For new work, use the fields and the control API above.
GET /api/v1/conversations/ai-status: returnsai_enabled,paused_since,paused_by,reasonandauto_resumes_at.POST /api/v1/conversations/pause: pauses forduration_seconds(60 to 86400).POST /api/v1/ai/pause: the older WhatsApp form, withphoneandduration_seconds.POST /api/v1/conversations/:phone/ai-toggle:actionispauseorresume. Teams with 2 or more numbers get a 400, so use the control API.
The POST endpoints return 404 when the chat has no messages, and write no hold. A resume still works on a chat that has a hold.