Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Initiate an outbound call

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.

    • sip_rtc_uid stringrequired

      The RTC UID used by the SIP gateway.

    • sip_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, and agent_rtc_uid.
    • 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.

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.

Authorization

This endpoint requires Basic Auth.

Request example (Pipeline ID)


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

Request example (Full configuration)


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

Response example


_3
{
_3
"agent_id": "A42AK62PExxxxxxxx74LN47MF46E"
_3
}