Skip to main content
POST
/
conversations
Create Conversation
curl --request POST \
  --url https://www.oration.ai/api/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-workspace-id: <api-key>' \
  --data '
{
  "conversations": [
    {
      "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "conversationType": "chat",
      "toPhoneNumber": "<string>",
      "sipTrunkAddress": "<string>",
      "dynamicVariables": {}
    }
  ]
}
'
{
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "phoneId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "wsUrl": "<string>",
      "llmUrl": "<string>",
      "callStartTime": "2023-11-07T05:31:56Z",
      "callEndTime": "2023-11-07T05:31:56Z",
      "userJoinTime": "2023-11-07T05:31:56Z",
      "userLeaveTime": "2023-11-07T05:31:56Z",
      "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "toPhoneNumber": "<string>",
      "fromPhoneNumber": "<string>",
      "conversationStatus": "queued",
      "telephonyType": "inbound",
      "telephonyStatus": "<string>",
      "endReason": "user_did_not_answer",
      "recordingStatus": "in_progress",
      "postCallNotes": "<string>",
      "postCallCategory1": "<string>",
      "postCallCategory2": "<string>",
      "postCallCategory3": "<string>",
      "postCallMetadata": {},
      "conversationType": "chat",
      "dynamicVariables": "<string>",
      "summary": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "errors": [
    {
      "error": "<string>"
    }
  ]
}

​
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

​
x-api-key
string
header
required
​
x-workspace-id
string
header
required

Body

application/json

Conversation creation request

​
conversations
object[]
required

Response

Successful response

​
results
object[]
​
errors
object[]