> ## 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 > Creates conversations for chat, web, or telephony flows within a workspace. This endpoint supports batch creation and can optionally bypass a customer's do-not-disturb flag when `ignoreDND` is set to `true` for an individual conversation payload. # 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: ```json theme={null} { "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: ```bash theme={null} 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. ## OpenAPI ````yaml POST /conversations openapi: 3.1.0 info: title: Oration AI Webhooks description: >- Webhook events for Oration AI platform - AI agents, conversations, and voice interactions version: 1.0.0 contact: name: Oration AI Support url: https://oration.ai/support email: support@oration.ai servers: - url: https://www.oration.ai/api/v2 description: Production API base URL security: [] tags: - name: conversations description: Create conversations and inspect conversation records. - name: customers description: >- Bulk import and manage customer records used by campaigns and outbound workflows. - name: jobs description: >- Track asynchronous jobs created by long-running import or processing requests. externalDocs: description: Product and integration documentation url: https://docs.oration.ai paths: /conversations: post: tags: - conversations summary: Create one or more conversations description: >- Creates conversations for chat, web, or telephony flows within a workspace. This endpoint supports batch creation and can optionally bypass a customer's do-not-disturb flag when `ignoreDND` is set to `true` for an individual conversation payload. operationId: edge-workspaces-conversation-trigger parameters: - in: header name: x-public-key description: Optional public key used by some edge-triggered conversation flows. example: 9b2deb4d-5b7d-4bad-9bdd-2b0d7b3dcb6d schema: type: string format: uuid - in: header name: x-api-key description: Workspace API key used for server-to-server authentication. example: ora_live_xxxxxxxxxxxxx schema: type: string - in: header name: x-workspace-id description: Workspace UUID that owns the created conversations. example: 6f8c7d9d-34e2-4f42-9f5d-8f3c5b16a6af schema: type: string requestBody: required: true description: Batch payload containing one or more conversations to create. content: application/json: schema: type: object description: >- Request body for creating one or more conversations in a workspace. properties: conversations: type: array description: >- One or more conversation payloads to create in a single request. items: type: object description: Single conversation creation payload. properties: phoneId: type: string description: >- Phone resource to associate with the conversation when using telephony. nullable: true format: uuid agentId: type: string description: Agent that should handle the conversation. nullable: true format: uuid flowId: type: string description: Optional flow to execute instead of agent assignment. nullable: true format: uuid callStartTime: type: string description: >- Call start timestamp supplied by the caller if the conversation already exists in an external system. nullable: true callEndTime: type: string description: >- Call end timestamp supplied by the caller for completed conversations or backfills. nullable: true customerId: type: string description: Existing customer record to link to the conversation. nullable: true format: uuid toPhoneNumber: type: string description: >- Destination phone number for outbound telephony conversations. nullable: true fromPhoneNumber: type: string description: >- Caller ID or source phone number used for the conversation. nullable: true conversationStatus: type: string description: Initial lifecycle status for the conversation. nullable: true enum: - created - dialing - active - completed - transferred - failed - null telephonyType: type: string description: >- Whether the telephony conversation is inbound or outbound. nullable: true enum: - inbound - outbound - null telephonyStatus: type: string description: >- Initial telephony transport status if known at creation time. nullable: true enum: - dialing - connected - active - completed - failed - null endReason: type: string description: >- Reason the conversation ended, typically used for imported or externally managed calls. nullable: true enum: - user_hangup - max_call_duration_exceeded - user_inactivity - user_did_not_answer - agent_hangup - unreachable - network_error - system_error - voice_mail_detection - transferred - null recordingStatus: type: string description: >- Recording state for the conversation if recordings are enabled. nullable: true enum: - in_progress - completed - null conversationType: type: string description: Channel used for the conversation. enum: - chat - web - telephony dynamicVariables: type: object description: >- Key-value pairs injected into the agent or flow at runtime. additionalProperties: type: string campaignId: type: string description: Campaign associated with this conversation, if any. nullable: true format: uuid campaignRunId: type: string description: Specific campaign run that produced this conversation. nullable: true format: uuid sipTrunkAddress: type: string description: >- SIP trunk address to use for telephony routing when applicable. nullable: true identifier: type: string description: >- External identifier for idempotency, reconciliation, or linking back to your source system. required: - conversationType minItems: 1 required: - conversations examples: telephonyOutbound: summary: Create a telephony conversation while bypassing DND value: 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 responses: '200': description: Conversation batch accepted and processed. content: application/json: schema: type: object description: Result of a batch conversation creation request. properties: results: type: array description: >- Successfully created conversations and any related connection details. items: type: object description: Result for a single created conversation. properties: conversation: type: object description: Persisted conversation record after creation. properties: phoneId: type: string description: Phone resource associated with the conversation. nullable: true format: uuid agentId: type: string description: Agent assigned to the conversation. nullable: true format: uuid flowId: type: string description: Flow associated with the conversation, if any. nullable: true format: uuid workspaceId: type: string description: Workspace that owns the conversation. format: uuid callStartTime: type: string description: Timestamp when the call started. nullable: true callEndTime: type: string description: Timestamp when the call ended. nullable: true customerId: type: string description: Customer linked to the conversation. nullable: true format: uuid toPhoneNumber: type: string description: Destination number for the conversation. nullable: true fromPhoneNumber: type: string description: Originating number or caller ID. nullable: true conversationStatus: type: string description: Current conversation lifecycle status. nullable: true enum: - created - dialing - active - completed - transferred - failed - null telephonyType: type: string description: Whether the call was inbound or outbound. nullable: true enum: - inbound - outbound - null telephonyStatus: type: string description: Current telephony transport status. nullable: true enum: - dialing - connected - active - completed - failed - null endReason: type: string description: Reason the conversation ended, if available. nullable: true enum: - user_hangup - max_call_duration_exceeded - user_inactivity - user_did_not_answer - agent_hangup - unreachable - network_error - system_error - voice_mail_detection - transferred - null recordingStatus: type: string description: Current recording state for the conversation. nullable: true enum: - in_progress - completed - null conversationType: type: string description: Conversation channel. enum: - chat - web - telephony dynamicVariables: type: string description: >- Serialized runtime variables stored with the conversation. nullable: true campaignId: type: string description: Campaign linked to the conversation. nullable: true format: uuid campaignRunId: type: string description: Campaign run linked to the conversation. nullable: true format: uuid id: type: string description: Conversation identifier. createdAt: type: string description: >- Timestamp when the conversation record was created. updatedAt: type: string description: >- Timestamp when the conversation record was last updated. required: - id tokenResponse: type: object description: >- LiveKit connection details returned for channels that require a realtime token. properties: token: type: string description: Access token used to join the conversation room. roomName: type: string description: LiveKit room name created for the conversation. identity: type: string description: Participant identity embedded in the token. roomURL: type: string description: >- Base URL of the LiveKit deployment hosting the room. liveTest: type: string description: >- Environment flag indicating whether the response targets a live test environment. required: - token - roomName - identity - roomURL - liveTest sipParticipant: description: >- SIP participant details when the conversation is bridged through SIP. required: - conversation errors: type: array description: Per-item errors for payloads that could not be created. items: type: object description: Error returned for a failed conversation payload. properties: error: type: string description: Human-readable validation or processing error. required: - error required: - results - errors examples: createdConversation: summary: Conversation created successfully value: 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: roomName: conversation-d2417d4e identity: api-client roomURL: https://oration.livekit.cloud liveTest: disabled errors: [] '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' example: code: BAD_REQUEST message: Invalid input data issues: - message: conversations[0].conversationType is required '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - Authorization: [] components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Invalid input data code: type: string description: The error code example: BAD_REQUEST issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Authorization not provided code: type: string description: The error code example: UNAUTHORIZED issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] error.FORBIDDEN: type: object properties: message: type: string description: The error message example: Insufficient access code: type: string description: The error code example: FORBIDDEN issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: Authorization: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token issued for an authenticated Oration user or service account. ````