> ## Documentation Index > Fetch the complete documentation index at: https://operator.xyz/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversation ## OpenAPI ````yaml api-reference/openapi3.json post /conversations openapi: 3.0.0 info: title: Operator API version: '2025-06-19' description: API for Operator servers: - url: https://api.operator.xyz security: [] paths: /conversations: post: tags: - Conversations summary: Create a conversation parameters: - name: Operator-Version in: header required: true schema: type: string enum: - '2025-06-19' description: The API version to use. example: '2025-06-19' requestBody: required: true content: application/json: schema: properties: agent_id: description: >- The agent that should handle the conversation. Use `ca_8qm9JBCiTe7` for the released version or `ca_8qm9JBCiTe7@v2` for a specific version. type: string channel: anyOf: - $ref: '#/components/schemas/CreateConversationInPhoneChannel' title: phone_channel - $ref: >- #/components/schemas/CreateConversationInChatRealtimeChannel title: chat_realtime_channel - $ref: >- #/components/schemas/CreateConversationInChatAsyncChannel title: chat_async_channel description: >- Configuration for the channel the conversation will be created on. livemode: default: true description: Whether the conversation should be created in live mode. type: boolean override_config: additionalProperties: true type: object default: null description: >- Partial override for [the agent's configuration](/api-reference/conversational-agents/create-a-conversational-agent#body-config) (e.g. voice, runtime, tools). Follows the same shape as the agent configuration object, but all fields are optional since it is merged into the base config. Read more on [dynamic configuration](/conversational-agents/dynamic-configuration). context: additionalProperties: true type: object default: null description: >- Arbitrary context passed to the agent. This can include runtime variable values, user metadata, or any other relevant payload. required: - agent_id - channel type: object responses: '200': description: Successful response. content: application/json: schema: properties: id: description: >- Unique identifier for the conversation, e.g. `conv_8qm9JBCiTe7`. type: string channel: anyOf: - $ref: '#/components/schemas/CreateConversationOutPhoneChannel' title: phone_channel - $ref: >- #/components/schemas/CreateConversationOutChatRealtimeChannel title: chat_realtime_channel - $ref: >- #/components/schemas/CreateConversationOutChatAsyncChannel title: chat_async_channel description: >- Details of the channel the conversation was created on. Will match the type of the channel used in the request. required: - id - channel type: object '400': description: Agent is not properly configured to handle the conversation. content: application/json: schema: type: object properties: code: type: string message: type: string data: {} '404': description: The requested resource was not found. content: application/json: schema: type: object properties: code: type: string message: type: string data: {} security: - BearerAuth: [] components: schemas: CreateConversationInPhoneChannel: description: Parameters for creating a phone channel conversation. properties: type: type: string enum: - phone callee_no: description: The phone number to call, in E.164 format. type: string caller_no: type: string default: null description: >- The phone number to call from, in E.164 format. If missing, defaults to a random registered number. priority: default: normal description: Priority for dispatching the call. enum: - normal - high type: string required: - type - callee_no type: object CreateConversationInChatRealtimeChannel: description: Parameters for creating a chat channel conversation. properties: type: type: string enum: - chat_realtime required: - type type: object CreateConversationInChatAsyncChannel: description: Parameters for creating a chat channel conversation. properties: type: type: string enum: - chat_async required: - type type: object CreateConversationOutPhoneChannel: description: Response object for creating a phone channel conversation. properties: type: default: phone type: string enum: - phone callee_no: type: string default: null description: The phone number that was called, in E.164 format. caller_no: type: string default: null description: The phone number that called, in E.164 format. token: description: Ephemeral token for the conversation session. type: string events_url: description: SSE stream of all server-side events during the call. type: string required: - token - events_url type: object CreateConversationOutChatRealtimeChannel: description: Response object for a chat-channel websocket conversation. properties: type: default: chat_realtime type: string enum: - chat_realtime caller_no: type: string default: null description: >- The phone number of the caller, in E.164 format. Available only in test mode, where it's populated from the customer's data so you can test your webhooks. callee_no: type: string default: null description: >- The phone number of the callee, in E.164 format. Available only in test mode, where it's populated from the customer's phone number so you can test your webhooks. token: description: Ephemeral token for the conversation session. type: string websocket_url: description: WebSocket URL to interact with the conversation session. type: string events_url: description: SSE stream of all server-side events during the call. type: string required: - token - websocket_url - events_url type: object CreateConversationOutChatAsyncChannel: description: Response object for a chat-channel http async conversation. properties: type: default: chat_async type: string enum: - chat_async token: description: Ephemeral token for the conversation session. type: string token_expires_at: description: UTC timestamp when the token expires. format: date-time type: string session_url: description: URL for sending/receiving messages in a request/response flow. type: string events_url: description: SSE stream of all server-side events during the call. type: string required: - token - token_expires_at - session_url - events_url type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````