API referenceSet system tools and call transfer

Agents

Set system tools and call transfer

Sets the built-in system tools of the agent identified by agent_id, such as call transfer. The list you send replaces the agent's current system tools, so send every tool you want to keep; an empty list removes them all. The response returns the agent's system tools after the change. Authenticated with your API key.

POST

https://api.nabrah.ai/api/ext/agent/{agent_id}/system_tools

curl --request POST \
  --url 'https://api.nabrah.ai/api/ext/agent/<agent_id>/system_tools' \
  --header 'X-API-Key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "system_tools": [
    {
      "name": "transfer",
      "when_to_use": "When the caller asks to speak to a person",
      "config": {
        "transfer_to": "+966500000000",
        "transfer_type": "cold",
        "sip_outbound_number": "+966110000000"
      }
    }
  ]
}'

{
  "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"
    }
  ]
}

System tools

Each entry has a name, an optional when_to_use, and a config for transfer.

transfer

Hands the call to a person. Needs a config (see below).

nameconfig

convert_date_to_weekday

Lets the agent work out the weekday of a date the caller mentions.

get_phone_number, get_email_address, get_national_id

Let the agent collect and confirm the caller's phone number, email address or national ID.

when_to_use

Up to 500 characters telling the agent when to use the tool, for example "When the caller asks for a sales person".

when_to_use

Transfer config

Phone calls only.

transfer_to

Where to transfer. A single number such as "+966500000000", a list of numbers (each a string or {"number": "+9665…", "hours": {…}}), or a category map such as {"Sales": {"desc": "when the caller wants to buy", "numbers": ["+9665…"]}}. hours uses days 1–7, start and end as HH:MM, and a timezone (default Asia/Riyadh). When several numbers are open, one is picked at random.

transfer_to

transfer_type

"warm": the agent calls the person and briefs them before connecting the caller. "cold": the caller is connected straight away. "forward": the call is handed back to the caller's phone system to transfer; on web calls it works like "cold".

transfer_type

sip_outbound_number

The outbound number used to place the transfer call. It must already be added to your project (GET /api/ext/sip_outbound); otherwise the request returns 404. Needed for warm and cold transfers, and for forward transfers on web calls.

sip_outbound_number

Returns 404 when the agent does not exist in your project or the outbound number is not found.

Authorization

X-API-Keystringheaderrequired

Your workspace API key. Create one in the dashboard under API keys.

Path parameters

agent_idstringrequired

Body

application/json

Connect the caller to the front desk when they ask for a person.

Transfer to one number

{
  "system_tools": [
    {
      "name": "transfer",
      "when_to_use": "When the caller asks to speak to a person",
      "config": {
        "transfer_to": "+966500000000",
        "transfer_type": "cold",
        "sip_outbound_number": "+966110000000"
      }
    }
  ]
}

Response

200

Successful Response

application/json

422

Validation Error

application/json

API referenceSet system tools and call transfer

Agents

Set system tools and call transfer

POST

https://api.nabrah.ai/api/ext/agent/{agent_id}/system_tools

Set system tools and call transfer

curl --request POST \
  --url 'https://api.nabrah.ai/api/ext/agent/<agent_id>/system_tools' \
  --header 'X-API-Key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "system_tools": [
    {
      "name": "transfer",
      "when_to_use": "When the caller asks to speak to a person",
      "config": {
        "transfer_to": "+966500000000",
        "transfer_type": "cold",
        "sip_outbound_number": "+966110000000"
      }
    }
  ]
}'

{
  "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"
    }
  ]
}

System tools

Each entry has a name, an optional when_to_use, and a config for transfer.

transfer

Hands the call to a person. Needs a config (see below).

nameconfig

convert_date_to_weekday

Lets the agent work out the weekday of a date the caller mentions.

get_phone_number, get_email_address, get_national_id

Let the agent collect and confirm the caller's phone number, email address or national ID.

when_to_use

Up to 500 characters telling the agent when to use the tool, for example "When the caller asks for a sales person".

when_to_use

Transfer config

Phone calls only.

transfer_to

transfer_type

sip_outbound_number

Returns 404 when the agent does not exist in your project or the outbound number is not found.

Authorization

X-API-Keystringheaderrequired

Your workspace API key. Create one in the dashboard under API keys.

Path parameters

agent_idstringrequired

Body

application/json

Connect the caller to the front desk when they ask for a person.

Transfer to one number

{
  "system_tools": [
    {
      "name": "transfer",
      "when_to_use": "When the caller asks to speak to a person",
      "config": {
        "transfer_to": "+966500000000",
        "transfer_type": "cold",
        "sip_outbound_number": "+966110000000"
      }
    }
  ]
}

Response

200

Successful Response

application/json

422

Validation Error

application/json