Assign an agent to a WhatsApp number
Attach an AI agent to one of the project's WhatsApp numbers so it automatically replies to incoming WhatsApp messages on that number. You bind an existing agent (by agent_id) and configure, for this number, whether the bot may escalate to a human, who it hands over to, when idle conversations close, and where conversation events are sent. The response returns the bound agent's full configuration plus this number's text_chatbot_settings.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/omni_v2/whatsapp/assign_chatbot' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": "00000000-0000-4000-8000-000000000000",
"name": "WhatsApp Support Bot",
"can_refer_to_human": true,
"human_emails": [
"support@example.com"
]
}'{
"agent": {
"agent_id": "00000000-0000-4000-8000-000000000000",
"project_id": "00000000-0000-4000-8000-000000000000",
"created_by_email": "string",
"created_at": "2026-01-15T12:00:00.000Z",
"last_update": "2026-01-15T12:00:00.000Z",
"name": "string",
"start_first": false,
"first_sentence": "string",
"agent_type": "basic",
"who_are_you": "string",
"goal": "string",
"steps": "string",
"allow_interruptions": false,
"voice": "dania",
"support_data": "string",
"languages": [
"ar"
],
"stack": "latest",
"speech_speed": 0.7,
"variables": [
{
"name": "string",
"type": "string",
"default_value": "string"
}
],
"pre_call_callback": {
"url": "string",
"parameters": [
{
"name": null,
"location": null,
"data_type": null,
"value": null
}
]
},
"post_call_callback": {
"url": "string",
"parameters": [
{
"name": null,
"location": null,
"data_type": null,
"value": null
}
]
},
"post_analysis_callback": {
"url": "string",
"parameters": [
{
"name": null,
"location": null,
"data_type": null,
"value": null
}
]
},
"tools": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string"
}
],
"system_tools": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string",
"config": {},
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z",
"when_to_use": "string"
}
],
"analysis_groups": [
{
"id": "00000000-0000-4000-8000-000000000000",
"name": "string"
}
],
"background_ambient": false,
"background_ambient_volume": 0,
"thinking_sound": false,
"thinking_sound_volume": 0,
"language_mode": "single"
},
"text_chatbot_settings": {
"can_refer_to_human": false,
"human_emails": [
"string"
],
"name": "string",
"created_at": "2026-01-15T12:00:00.000Z",
"auto_resolve_hours": 0,
"webhook_url": "string",
"has_webhook_hmac_secret": false,
"inbox_ids": [
"00000000-0000-4000-8000-000000000000"
]
}
}How auto-reply works
Once assigned, incoming WhatsApp messages on that number are handled by the chosen agent, which generates and sends replies automatically.
agent_idThe UUID of an existing text/basic agent in this project that should answer messages.
agent_idnameThe bot's display name. It is shared by every WhatsApp number this agent answers on.
nameSet can_refer_to_human to true to let the bot escalate a conversation, then describe who it reaches in human_emails (see below).
can_refer_to_humanhuman_emailsUse GET /api/ext/omni_v2/whatsapp/get_chatbot to inspect the current assignment and DELETE /api/ext/omni_v2/whatsapp/unassign_chatbot to remove it.
One agent, several numbers
Assigning adds this number to the agent. The agent keeps answering on its other numbers, and their settings stay as they are.
These apply to the selected number only.
can_refer_to_humanhuman_emailsauto_resolve_hourswebhook_urlwebhook_hmac_secretLeaving out can_refer_to_human turns handoff off, and leaving out human_emails sends an empty list, which hands over to a random project member who can see this number's conversations. Leaving out auto_resolve_hours, webhook_url or webhook_hmac_secret keeps this number's current value, also when the request replaces the number's agent. On a number with no agent, every setting left out is copied from the agent's first number when the agent already answers on another number, and starts empty otherwise.
can_refer_to_humanhuman_emailsauto_resolve_hourswebhook_urlwebhook_hmac_secretA number has one agent at a time. Assigning a different agent to a number replaces the previous one there; ongoing conversations on that number continue with the new agent, which does not see the previous agent's replies. The number keeps its own settings, except those sent in the request and the handoff rule above.
inbox_idstext_chatbot_settings.inbox_ids in the response lists every WhatsApp number the agent now answers on.
inbox_idsChoosing who the bot hands over to
human_emails accepts three shapes. Working hours are optional on any destination; when they are set, only destinations inside their window are eligible and one of them is picked at random.
An empty list refers the conversation to a random project member who can see this number's conversations. Working hours are ignored on this path.
human_emailsA list of addresses. Each item is either a bare string (always available) or an object with an optional hours window.
human_emailsA category map. desc is required and is the only text the assistant sees when deciding which department fits, so make it specific. The assistant must pass a category on every call; if none of the descriptions match, nobody is contacted.
human_emailshours{ "days": [1,2,3,4,5], "start": "09:00", "end": "17:00", "timezone": "Asia/Riyadh" }days are ISO weekdays, 1 = Monday through 7 = Sunday; an empty list means every day. start and end are zero-padded 24-hour times, and a window whose start is later than its end wraps past midnight. timezone is an IANA zone and defaults to Asia/Riyadh.
human_emailsAddresses that do not belong to a project member who can see this number's conversations still open the conversation, but it is left unassigned.
Choosing the WhatsApp number
A project can connect more than one WhatsApp number. inbox_id selects the number this call works on.
inbox_id is optional; the project's only WhatsApp number is used.
inbox_id is required and the call returns 400 without it. An id that is not one of the project's WhatsApp numbers returns 404.
inbox_idList the numbers and their ids with GET /api/ext/omni_v2/whatsapp/inboxes.
Errors
Another change to the same number's agent, or to the same agent on another number, is still being saved. Wait a moment, then try again; GET /api/ext/omni_v2/whatsapp/get_chatbot shows the result once it is saved.
Event webhooks
Set webhook_url to receive a POST for each chatbot event on this number. Leave the field out to keep the current value, or send null to turn webhooks off.
Eventsmessage.received: every incoming customer message on the number, including chats a person has taken over. message.replied: a reply sent by the bot. message.sent: a reply sent by a person or through the API. conversation.status_changed: a handoff to a person, the bot ending the chat, or a manual status change. conversation.auto_resolved: the chat was closed after the auto-resolve window.
webhook_urlPayload{ "event", "occurred_at", "project_id", "agent_id", "conversation_id", "data" }For message events, data has conversation_id, content, content_type, created_at, message_type (0 = incoming, 1 = outgoing) and attachments (each with file_type and data_url). For status events, data has conversation_id, status, previous_status (can be null) and reason (refer_to_human, end_chat, auto_resolve or manual).
SignatureX-Nabrah-Signature: sha256=<hex digest>When webhook_hmac_secret is set, each request has X-Nabrah-Timestamp (Unix seconds) and X-Nabrah-Signature: sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw request body>, keyed with your secret. Verify it against the raw body, compare in constant time, and reject old timestamps. Every request also has X-Nabrah-Event with the event name.
webhook_hmac_secretDeliveryEach event is sent once with a 5-second timeout. Failed or non-2xx deliveries are not retried, and events have no event ID. One status change can arrive as two events, for example conversation.auto_resolved and then conversation.status_changed. Keep your handler idempotent, and use GET /api/ext/omni_v2/conversation/conversation/{id}/messages to fill any gaps.
Events are only sent while a chatbot is assigned to the number. GET /api/ext/omni_v2/whatsapp/get_chatbot returns webhook_url and has_webhook_hmac_secret; the secret itself is never returned.
Authorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Query parameters
inbox_idstringThe id of the WhatsApp number to use, from GET /api/ext/omni_v2/whatsapp/inboxes.
Use inboxes[].id (a UUID), not the numeric inboxes[].inbox_id. Optional while the project has one WhatsApp number; required once it has more than one.
Body
application/jsonA flat list of addresses, always available.
{
"agent_id": "00000000-0000-4000-8000-000000000000",
"name": "WhatsApp Support Bot",
"can_refer_to_human": true,
"human_emails": [
"support@example.com"
]
}Response
Successful Response
application/json
Validation Error
application/json