Skip to main content
POST
/
conversations
Create one or more conversations
curl --request POST \
  --url https://www.oration.ai/api/v2/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversations": [
    {
      "agentId": "0f9e2f8a-df49-4c24-83a2-b9fd8d1f44a7",
      "customerId": "cc1e4298-a150-495d-8c88-b1ce4487ed9e",
      "conversationType": "telephony",
      "telephonyType": "outbound",
      "toPhoneNumber": "+14155550100",
      "fromPhoneNumber": "+14155550999",
      "dynamicVariables": {
        "firstName": "Ava",
        "plan": "premium"
      },
      "ignoreDND": true,
      "identifier": "crm-contact-1024"
    }
  ]
}
'
{
  "results": [
    {
      "conversation": {
        "id": "d2417d4e-eab4-4ab6-a914-69f8b6d1b2d0",
        "workspaceId": "6f8c7d9d-34e2-4f42-9f5d-8f3c5b16a6af",
        "agentId": "0f9e2f8a-df49-4c24-83a2-b9fd8d1f44a7",
        "customerId": "cc1e4298-a150-495d-8c88-b1ce4487ed9e",
        "conversationType": "telephony",
        "conversationStatus": "created",
        "telephonyType": "outbound",
        "telephonyStatus": "dialing",
        "toPhoneNumber": "+14155550100",
        "fromPhoneNumber": "+14155550999",
        "createdAt": "2026-04-01T10:15:30.000Z",
        "updatedAt": "2026-04-01T10:15:30.000Z"
      },
      "tokenResponse": {
        "token": "<livekit-token>",
        "roomName": "conversation-d2417d4e",
        "identity": "api-client",
        "roomURL": "https://oration.livekit.cloud",
        "liveTest": "disabled"
      }
    }
  ],
  "errors": []
}

Documentation Index

Fetch the complete documentation index at: https://docs.oration.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Create Conversations

This endpoint allows you to create conversations with AI agents.

​
Dynamic Variables

Dynamic variables allow you to personalize your AI agent’s responses for each conversation. They’re a powerful way to make your conversations more relevant and context-aware. Here’s how you can use them:

​
How It Works

  1. When defining your AI agent, you can include a dynamicVariables in your prompts using the {{variableName}} placeholder.
  2. When creating a conversation, you can include those variables as a dictionary in the dynamicVariables field in your request body.
  3. Each key-value pair in this object represents a variable that can be used by your AI agent during the conversation.
  4. Your agent can then reference these variables to personalize its responses.

​
Example Usage

Here’s an example of how to include dynamic variables when creating a conversation: 
{
  "conversations": [
    {
      "agentId": "5e3832c1-700e-49e8-9b10-9fbd5f8f28c2",
      "conversationType": "telephony",
      "toPhoneNumber": "+1234567890",
      "dynamicVariables": {
        "customerName": "Alice Smith",
        "productName": "Gold Membership",
      }
    }
  ]
}
In this example:
  • customerName could be used by the agent to greet the customer by name.
  • productName might be referenced when discussing the customer’s current subscription.

​
Rate Limiting

The API has a rate limit of 20 concurrent calls per workspace. If you exceed this limit, the API will return a 429 error. The rate limit is enforced per workspace. If you need to increase the limit, please contact us. The endpoint throws a 429 error when the available slots are occupied by active or dialing conversations.

​
Example Request

Here’s a simple example using cURL: 
curl --request POST \
  --url https://www.oration.ai/api/v2/conversations \
  --header 'x-api-key: your-api-key-here' \
  --header 'x-workspace-id: your-workspace-id-here' \
  --data '{
  "conversations": [
    {
      "agentId": "5e3832c1-700e-49e8-9b10-9fbd5f8f28c2",
      "conversationType": "telephony",
      "toPhoneNumber": "+1234567890",
      "dynamicVariables": {
        "customerName": "Bob Johnson",
        "appointmentTime": "3:00 PM",
        "serviceType": "Annual Check-up"
      }
    }
  ]
}'
This request will trigger a phone call to the specified number, and the AI agent will be able to use the provided dynamic variables to personalize the conversation. By leveraging dynamic variables, you can create more engaging and personalized AI-driven conversations that adapt to each unique interaction.

​
Developer Recommendations

When you are trying to make multiple calls using this API endpoint. You can use the following strategy to ensure maximum utilisation of the available concurrency. There are two simple rules to follow:
  1. Use Short Bursts: If you need to make a lot of calls, consider making them in short bursts.
  2. Listen to the Rate Limit Headers: Rather than sending a batch of arbitrary length, listen to the rate limit headers and adjust the length of calls to be made accordingly.

​
Example Strategy

In case you want to make 200 calls. Assuming your max concurrent calls is 20.
  1. You can add 20 conversations in the first request.
  2. Then wait for few seconds and make another request with another 20 conversations. Check the rate limit headers and adjust the length of calls to be made accordingly.
  3. You can adjust the size of the batch based on the rate limit headers till you finish all the calls.
  4. You can use the GET /conversations endpoint to check the status of the conversations.

Authorizations

​
Authorization
string
header
required

Bearer token issued for an authenticated Oration user or service account.

Headers

​
x-public-key
string<uuid>

Optional public key used by some edge-triggered conversation flows.

​
x-api-key
string

Workspace API key used for server-to-server authentication.

​
x-workspace-id
string

Workspace UUID that owns the created conversations.

Body

application/json

Batch payload containing one or more conversations to create.

Request body for creating one or more conversations in a workspace.

​
conversations
object[]
required

One or more conversation payloads to create in a single request.

Minimum array length: 1

Response

Conversation batch accepted and processed.

Result of a batch conversation creation request.

​
results
object[]
required

Successfully created conversations and any related connection details.

​
errors
object[]
required

Per-item errors for payloads that could not be created.