Conversational AI Platform REST API overview

The Conversational AI Platform REST API (Preview) lets you save agents, secrets, and phone numbers in your project, and use them to run agent sessions and outbound call campaigns from your server.

API basicsCopy Anchor Link

• Base URL: https://preview.ai.agora.io/conversational-ai/v1/projects/<appid>, where <appid> is the App ID of your Agora project. Every resource belongs to one project.
• Authentication: Use token authentication or Basic HTTP authentication for every request.
• Request: Request and response bodies use JSON. Request URLs and request bodies are case-sensitive.
• IDs: Each resource returns its ID in a <resource>_id field, such as agent_id, number_id, and campaign_id. Agent, number, and campaign IDs are UUIDs, such as 3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10. Session IDs are 32 lowercase letters and digits.
• Timestamps: Timestamps are Unix times in seconds, in fields that end in _ts. Durations have a unit suffix, such as _ms or _seconds. Campaign schedules are the exception: they use local times in the schedule's time zone.

ConventionsCopy Anchor Link

The following conventions apply to every endpoint:

• Pagination: List endpoints return data, has_more, and next_cursor. To get the next page, pass next_cursor in the cursor query parameter. next_cursor is null on the last page.
• Errors: Every error response contains detail and reason. For all reasons, see Status codes and error reasons.
• Request ID: Every response includes an Agora-Request-Id header. Include it when you contact Agora support.

REST APIsCopy Anchor Link

The Platform APIs are organized by resource. You save agents, secrets, and phone numbers in your project, then reference them when you start sessions and campaigns.

AgentsCopy Anchor Link

An agent is a saved configuration that defines how your agent behaves, including its instructions, variables, greeting, and the models in its pipeline. Use these endpoints to manage agents that you start sessions and campaigns from.

• Create an agent: Save an agent configuration.
• List agents: Retrieve the agents in your project.
• Retrieve an agent: Retrieve the configuration of an agent.
• Update an agent: Change the configuration of an agent.
• Delete an agent: Delete an agent.

SessionsCopy Anchor Link

A session runs one agent in an RTC channel or a phone call. Use these endpoints to start sessions from a saved or inline agent, control them while they run, and stop them.

• Start a session: Start a session with a saved agent.
• Start an ephemeral session: Start a session with an agent configuration you pass in the request.
• List sessions: Retrieve the sessions that match your filters.
• Retrieve a session: Retrieve the status of a session.
• Update a session: Renew the RTC token, or replace the messages or LLM parameters of a running session.
• Stop a session: Stop a running session.

SecretsCopy Anchor Link

A secret set stores provider API keys and other credentials, so your agent configurations reference secrets instead of containing them. Secret values are write-only and are never returned.

• Create a secret set: Store credentials in a named secret set.
• List secret sets: Retrieve the secret sets in your project.
• Retrieve a secret set: Retrieve the key names in a secret set.
• Update a secret set: Add, change, or remove several keys in one change.
• Replace a secret set: Replace all the keys in a set.
• Delete a secret set: Delete a set and all its keys.
• Set a secret key: Add a key or replace its value.
• Delete a secret key: Remove a key from a set.

Phone numbersCopy Anchor Link

A phone number connects your agents to the phone network through your carrier's SIP trunk. Agents call from a registered number, and you can choose the agent that answers inbound calls to it.

• Create a phone number: Import a phone number with its SIP trunk and inbound routing.
• List phone numbers: Retrieve the phone numbers in your project.
• Retrieve a phone number: Retrieve a number and its SIP and inbound settings.
• Update a phone number: Change the SIP trunk or inbound routing of a number.
• Delete a phone number: Remove a number from your project.

CampaignsCopy Anchor Link

A campaign calls a list of contacts with a saved agent, on a schedule or right away. Each call starts a telephony session. Use these endpoints to create campaigns and control them while they run.

• Create a campaign: Dial a list of contacts with a saved agent.
• List campaigns: Retrieve the campaigns in your project.
• Retrieve a campaign: Retrieve a campaign and its contact counts.
• Update a campaign: Change the pacing, schedule, or dialing limits.
• Pause a campaign: Stop placing new calls.
• Resume a campaign: Continue dialing a paused campaign.
• Cancel a campaign: End a campaign permanently.
• Delete a campaign: Delete a finished campaign.