Start a session
Updated
Starts a session that runs a saved agent in an RTC channel or over the phone.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/sessionsThe session uses the agent's configuration as saved when the session starts. To run a configuration without saving an agent first, use Start an ephemeral session.
A 200 response confirms that the session exists. It doesn't confirm that the agent has joined the RTC channel or that an outbound call was answered. To follow the session, retrieve it. The session ends when you stop it, or when it reaches a limit in lifecycle.
appidstringThe App ID of your project.
Idempotency-KeystringA unique key, so that retrying the request can't start a second session. If a session was already started with this key, the request fails with 409 and reason IdempotencyKeyConflict, and no new session starts. The API doesn't return the original response. To find the session, list sessions. Keep the same key when you retry; never switch keys.
agent_idstringThe ID of the saved agent to run.
transportRTC | TelephonyHow the agent connects to the participant. Pass the fields of one transport type only.
typestring(RTC)rtc: The agent joins an RTC channel.
channelstring(RTC)The name of the RTC channel to join, 1 to 256 characters.
tokenstring(RTC)The RTC token the agent uses to join the channel. Required when the project has an App Certificate enabled. To renew it, update the session.
uidString | Integer(RTC)The user ID the agent uses in the channel. Pass a string of up to 255 characters, such as "1002" or "agent-bot", or an integer from 0 to 4294967295, such as 1002. Omit it, or pass 0, to let Agora assign a user ID that differs from subscribe_uids.
subscribe_uidsarray<String | Integer>(RTC)The user ID of the participant the agent talks to, as a string or an integer. Pass exactly one user ID.
audio_scenariostring(RTC)The audio scenario of the agent in the channel:
aiserver: Optimized for latency and network resilience in conversations with an agent.chorus: For participants with good network conditions who need ultra-low latency.
encryptionobject(RTC)Media encryption for the RTC channel. These values are never returned.
modestringThe encryption mode. Agora recommends aes_128_gcm2 or aes_256_gcm2, which use a salt.
keystringThe encryption key.
saltstringA Base64-encoded salt that is 32 bytes long after decoding. Required when mode is aes_128_gcm2 or aes_256_gcm2.
typestring(Telephony)telephony: The agent places a phone call.
fromstring(Telephony)The number_id of the number in the project to call from. Phone numbers aren't accepted. Import the number first.
tostring(Telephony)The phone number to call, in E.164 format, for example +14155550100.
call_policyobject(Telephony)Limits and behavior for outbound phone calls. Each limit you omit adds no limit.
max_ring_duration_msintegerThe maximum time in milliseconds from starting the dial until the call is answered. If the call isn't answered in time, the dial attempt ends.
max_call_duration_secondsintegerThe maximum length of the call in seconds, measured from when it's answered. The session's lifecycle limits can end the call earlier.
max_silence_duration_msintegerHang up when nobody on the call has spoken for this many milliseconds. This is separate from pipeline.silence_config, which only prompts the user.
end_callobjectConditions under which the agent can end the call itself. Every condition is off unless you set it to true.
on_user_requestbooleanEnd the call when the caller clearly says goodbye or asks to hang up.
on_voicemailbooleanEnd the call when the agent reaches voicemail, such as a "please leave a message after the tone" announcement.
on_ai_assistantbooleanEnd the call when the call is answered by an AI assistant, a voice secretary, or another automated answering system.
valuesobjectValues for the agent's variables, keyed by variable name, for this session only. Each key must be a variable the agent declares, and each value must match its type and options. Pass a value for every required variable. null values are rejected.
lifecycleobjectWhen the session ends on its own.
idle_timeout_msintegerHow long in milliseconds the session continues with no participant present: after the subscribed user leaves the RTC channel, or after the other side of a phone call hangs up. It isn't silence detection. Set to 0 to turn off the idle timer. Can't be greater than max_duration_ms.
max_duration_msintegerThe maximum length of the session in milliseconds, measured from start_ts. Defaults to 5 minutes. The maximum is 1 hour.
graceful_stopobjectHow the agent finishes when you stop the session, or when the idle timer expires. It doesn't extend max_duration_ms, and it doesn't add a farewell message.
enabledbooleanWhether the agent finishes what it's saying before it leaves.
timeout_msintegerThe longest time in milliseconds the agent can take to finish.
data_policyobjectHow Agora handles the session's data. You set it when the session starts and can't change it afterward.
retentionstringHow long Agora keeps the conversation data:
30_days: Agora keeps the data for 30 days.none: Agora doesn't keep the data, and variable extraction doesn't run. Use it, for example, when a caller declines recording.
labelsobjectKey-value labels for this session, such as a team or customer ID. They're included in the payload of notification events.
[key: string]stringResponse Body
The session was created.
Response Headers
agent_session_idstringThe ID of the session.
create_tsintegerThe time the session was created, as a Unix timestamp in seconds.
statusstringThe status of the session when it starts. For a phone call, RUNNING doesn't mean the call was answered.
Request examples
curl -X POST 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/sessions' \ -H 'Content-Type: application/json' \ -d '{ "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10", "values": { "customer_name": "Ada" }, "labels": { "team": "support" }, "transport": { "type": "rtc", "channel": "support-4821", "token": "<your_rtc_token>", "uid": "1002", "subscribe_uids": [ "1001" ] }, "lifecycle": { "idle_timeout_ms": 30000, "max_duration_ms": 3600000 }}'Response example
{ "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h", "create_ts": 1737111452, "status": "RUNNING"}