Initiate an outbound call

POST

https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/call

Use this endpoint to initiate an outbound call to the specified number and create an agent that joins the target RTC channel. The agent waits for the callee to answer.

Request

Path parameters

appid stringrequired

The App ID of the project.

Request body

APPLICATION/JSON

BODYrequired

name stringrequired
The name identifier of the call session.
sip objectrequired
SIP (Session Initiation Protocol) call configuration object.
Show propertiesHide properties
- to_number stringrequired
  Called number (target phone number), in E.164 format.
- from_number stringrequired
  Caller ID (the number that initiated the call), in E.164 format.
- rtc_uid stringrequired
  The RTC UID used by the SIP gateway.
- rtc_token stringrequired
  The RTC token used by the SIP gateway.
pipeline_id string
The unique ID of a published project in AI Studio.
properties objectrequired
Call attribute configuration. The content of this field varies depending on the invocation method:
- Using pipeline ID: Simply pass in channel, token, agent_rtc_uid, and remote_rtc_uids.
- Using complete configuration: Pass in the complete parameters of the Start a conversational AI agent properties, including all required fields such as channel, token, agent_rtc_uid, remote_rtc_uids, tts, and llm.
Show propertiesHide properties
- channel stringrequired
  RTC channel name.
- token stringrequired
  RTC Channel Token.
- agent_rtc_uid stringrequired
  The agent's user ID in the RTC channel.
- remote_rtc_uids array[string]required
  A list of user IDs that the agent subscribes to in the channel. Only subscribed users can interact with the agent.
  info
  Currently, only one user ID is supported.

Response

If the returned status code is 200, the request was successful. The response body contains the result of the request.
OK
- agent_id string
  Unique ID of the agent instance. Use it to query call status, control call flow, and perform other operations.
If the returned status code is not 200, the request failed. The response body includes the error code and description. Refer to status codes to understand the possible reasons for failure.
Error Response
- error_type string
  The type of error that occurred.
- description string
  A detailed description of the error.
Common error codes:
- 400 invalid_phone_format: Invalid phone number format (not in E.164 format).
- 401 unauthorized: Authentication failed, please check your credentials.
- 500 internal_server_error: Internal server error.

Authorization

This endpoint requires Basic Auth.

Request example (Pipeline ID)

curl
Python
Node.js

curl --request POST \
  --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/call \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "customer_service",
    "sip": {
      "to_number": "+19876543210",
      "from_number": "+11234567890",
      "rtc_uid": "100",
      "rtc_token": "<agora_sip_rtc_token>"
    },
    "pipeline_id": "fzufjlweixxxxnlp",
    "properties": {
      "channel": "<agora_channel>",
      "token": "<agora_channel_token>",
      "agent_rtc_uid": "111",
      "remote_rtc_uids": [
        "100"
      ]
    }
  }'

Request example (Full configuration)

curl
Python
Node.js

curl --request POST \
  --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/call \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "customer_service",
    "sip": {
      "to_number": "+19876543210",
      "from_number": "+11234567890",
      "rtc_uid": "100",
      "rtc_token": "<agora_sip_rtc_token>"
    },
    "properties": {
      "channel": "<agora_channel>",
      "token": "<agora_channel_token>",
      "agent_rtc_uid": "111",
      "remote_rtc_uids": [
        "100"
      ],
      "idle_timeout": 120,
      "llm": {
        "url": "https://api.openai.com/v1/chat/completions",
        "api_key": "<your_llm_key>",
        "system_messages": [
          {
            "role": "system",
            "content": "You are a helpful chatbot."
          }
        ],
        "max_history": 32,
        "greeting_message": "Hello, how can I assist you today?",
        "failure_message": "Please hold on a second.",
        "params": {
          "model": "gpt-4o-mini"
        }
      },
      "tts": {
        "vendor": "microsoft",
        "params": {
          "key": "<your_tts_api_key>",
          "region": "eastus",
          "voice_name": "en-US-AndrewMultilingualNeural"
        }
      },
      "asr": {
        "language": "en-US"
      }
    }
  }'

Response example

200
Non-200

{
  "agent_id": "A42AK62PExxxxxxxx74LN47MF46E"
}

Initiate an outbound call

Request​

Path parameters​

Request body​

Response​