Assign an agent to an Instagram account
Attach an AI agent to one of the project's Instagram accounts so it automatically replies to incoming Instagram direct messages on that account. You bind an existing agent (by agent_id) and configure, for this account, 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 account's text_chatbot_settings.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/omni_v2/instagram/assign_chatbot' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": "00000000-0000-4000-8000-000000000000",
"name": "Instagram 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"
}
],
"knowledge_bases": [
{
"id": "00000000-0000-4000-8000-000000000000",
"project_id": "00000000-0000-4000-8000-000000000000",
"name": "string",
"key": "string",
"desc": "string",
"kind": "unstructured",
"document_count": 0,
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z"
}
],
"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
},
"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 Instagram direct messages on that account 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 Instagram account 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/instagram/get_chatbot to inspect the current assignment and DELETE /api/ext/omni_v2/instagram/unassign_chatbot to remove it.
One agent, several accounts
Assigning adds this account to the agent. The agent keeps answering on its other accounts, and their settings stay as they are.
These apply to the selected account 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 account's conversations. Leaving out auto_resolve_hours, webhook_url or webhook_hmac_secret keeps this account's current value, also when the request replaces the account's agent. On a account with no agent, every setting left out is copied from the agent's first account when the agent already answers on another account, and starts empty otherwise.
can_refer_to_humanhuman_emailsauto_resolve_hourswebhook_urlwebhook_hmac_secretA account has one agent at a time. Assigning a different agent to a account replaces the previous one there; ongoing conversations on that account continue with the new agent, which does not see the previous agent's replies. The account 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 Instagram account 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 account'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 account's conversations still open the conversation, but it is left unassigned.
Choosing the Instagram account
A project can connect more than one Instagram account. inbox_id selects the account this call works on.
inbox_id is optional; the project's only Instagram account is used.
inbox_id is required and the call returns 400 without it. An id that is not one of the project's Instagram accounts returns 404.
inbox_idList the accounts and their ids with GET /api/ext/omni_v2/instagram/inboxes.
Errors
Another change to the same account's agent, or to the same agent on another account, is still being saved. Wait a moment, then try again; GET /api/ext/omni_v2/instagram/get_chatbot shows the result once it is saved.
Event webhooks
Set webhook_url to receive a POST for each chatbot event on this account. Leave the field out to keep the current value, or send null to turn webhooks off.
Eventsmessage.received: every incoming customer message on the account, 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 account. GET /api/ext/omni_v2/instagram/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 Instagram account to use, from GET /api/ext/omni_v2/instagram/inboxes.
Use inboxes[].id (a UUID), not the numeric inboxes[].inbox_id. Optional while the project has one Instagram account; required once it has more than one.
Body
application/jsonA flat list of addresses, always available.
{
"agent_id": "00000000-0000-4000-8000-000000000000",
"name": "Instagram Support Bot",
"can_refer_to_human": true,
"human_emails": [
"support@example.com"
]
}Response
Successful Response
application/json
Validation Error
application/json