> ## Documentation Index > Fetch the complete documentation index at: https://docs.open.cx/llms.txt > Use this file to discover all available pages before exploring further. > Send a message — Sends a message in a chat session. Use when orchestrating conversations from code — creating sessions, sending messages, or listing history for an external… # Send a message ## Custom data This endpoint accepts two independent `custom_data` objects, each merged into a different record: * **Top-level `custom_data`** — session-level attributes that belong to this conversation, such as an order ID, cart value, or routing flag. Merged into the chat session and returned by [Get Session](/api-reference/chat-sessions/get). Values can be strings, numbers, or booleans. * **`contact.custom_data`** — contact-level attributes that belong to the person, such as plan, region, or account tier. Merged into the contact. Values are strings. Both merge into any existing data, so you only need to send the keys you want to add or update. Nested objects are rejected with a `400`. ```json theme={"dark"} { "sender": "contact", "custom_data": { "order_id": "ord_123", "cart_value": 149.99, "priority": "high" }, "contact": { "custom_data": { "plan": "pro", "region": "emea" } }, "message": { "type": "text", "text": "I need help with this order" } } ``` Session `custom_data` set through this endpoint is stored on the session but is **not** synced to a connected external ticketing system (e.g. Intercom or HubSpot). ## OpenAPI ````yaml post /chat/sessions/{session_id}/send openapi: 3.1.0 info: title: OpenCX API description: > OpenCX is an AI-powered, all-in-one platform for customer support and outbound communications. Use this API to manage your OpenCX organization's AI agents, actions, conversations, contacts, and more. To get started, generate a new API key from the dashboard. ## Authentication All API endpoints require authentication using a Bearer token. You can generate an API key from your OpenCX dashboard. ## Rate Limiting API requests are rate limited to ensure fair usage. The current limits are: - 100 requests per minute for standard endpoints - 1000 requests per minute for streaming endpoints ## Error Handling The API uses standard HTTP status codes and returns detailed error messages in the response body. version: 1.0-beta license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.open.cx description: Production security: - bearerAuth: [] paths: /chat/sessions/{session_id}/send: post: summary: Send a message description: >- Sends a message in a chat session. The message can be sent as either a contact or an agent. operationId: sendMessage parameters: - schema: type: string in: path name: session_id required: true description: The unique identifier of the chat session requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageInput' responses: '200': description: Default Response content: application/json: schema: $ref: '#/components/schemas/SendMessageOutput' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorDto' components: schemas: SendMessageInput: $schema: https://json-schema.org/draft/2020-12/schema $id: '#/components/schemas/SendMessageInputInput' type: object properties: sender: type: string enum: - contact - agent contact: type: object properties: name: type: string email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ phone_number: type: string avatar_url: type: string custom_data: type: object propertyNames: type: string additionalProperties: type: string custom_data: description: >- Session-level custom data to merge into the chat session. Use contact.custom_data for contact-level attributes. type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: number - type: boolean agent: type: object properties: id: type: number name: type: string avatar_url: type: string message: type: object properties: type: type: string const: text text: type: string attachments: type: array items: $ref: '#/components/schemas/ChatAttachmentInput' required: - type - text should_take_over_session_from_ai: default: false type: boolean required: - sender - message SendMessageOutput: $schema: https://json-schema.org/draft/2020-12/schema $id: '#/components/schemas/SendMessageOutput' type: object properties: success: type: boolean data: anyOf: - type: object properties: message: type: object properties: id: type: string required: - id additionalProperties: false required: - message additionalProperties: false - oneOf: - type: object properties: success: type: boolean const: true code: anyOf: - type: string - type: string const: session_assigned_to_human_agent - type: string const: response_cancelled - type: string const: skipping_unuseful_response - type: string const: duplicate_message_ignored autopilotResponse: type: object properties: type: type: string const: text value: type: object properties: error: type: boolean content: type: string required: - error - content additionalProperties: false id: type: string mightSolveUserIssue: type: boolean completelyAndFullyCoveredUserIssue: type: boolean debugInfo: type: object properties: actionCalls: type: array items: type: object properties: action: type: object properties: name: type: string id: type: string openapi: type: object properties: openapi_spec_id: type: string operation_spec: {} operation_id: type: string operation_method: type: string required: - operation_spec additionalProperties: false metadata: {} required_form_submission: type: boolean is_handoff_like: type: boolean required: - name - id - metadata additionalProperties: false arguments: {} result: {} required: - action - arguments - result additionalProperties: false actionSearchQuery: type: string knowledge: type: array items: type: object properties: source: type: string source_type: type: string url: type: string required: - source - source_type - url additionalProperties: false knowledge_used: type: array items: type: object properties: content: type: string source: type: string required: - content - source additionalProperties: false work_instructions_scanned: type: array items: type: object properties: content: type: string required: - content additionalProperties: false client_context: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- Context provided from the client. For example, dynamic metadata sent from the widget such as: the current product name on the page, the current Shopify shop domain, etc etc. additional_debug_data: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: >- Org-specific or message-type-specific debug data. whatsapp_template_request: anyOf: - {} - type: 'null' rule_violation_reflections: type: array items: type: object properties: rule_name: type: string violation_description: type: string description: How the rule was violated required: - rule_name - violation_description additionalProperties: false tool_call_results_quick_reply_suggestions: type: array items: type: object properties: tool_name: type: string suggestions: type: array items: type: string required: - tool_name - suggestions additionalProperties: false assignment_choice_summary: default: null anyOf: - type: object properties: strategy: type: string const: least-busy selected: anyOf: - type: object properties: agent_id: type: number agent_name: type: string active_sessions: type: number active_sessions_in_group: type: number pending_sessions: type: number remaining_capacity: type: number max_capacity: type: number max_capacity_in_group: anyOf: - type: number - type: 'null' is_available_globally: type: boolean is_available_in_group: type: boolean missing_required_skills: default: [] type: array items: type: object properties: id: type: string name: type: string required: - id - name additionalProperties: false required: - agent_id - agent_name - active_sessions - active_sessions_in_group - pending_sessions - remaining_capacity - max_capacity - max_capacity_in_group - is_available_globally - is_available_in_group - missing_required_skills additionalProperties: false - type: 'null' peers: type: array items: type: object properties: agent_id: type: number agent_name: type: string active_sessions: type: number active_sessions_in_group: type: number pending_sessions: type: number remaining_capacity: type: number max_capacity: type: number max_capacity_in_group: anyOf: - type: number - type: 'null' is_available_globally: type: boolean is_available_in_group: type: boolean missing_required_skills: default: [] type: array items: type: object properties: id: type: string name: type: string required: - id - name additionalProperties: false required: - agent_id - agent_name - active_sessions - active_sessions_in_group - pending_sessions - remaining_capacity - max_capacity - max_capacity_in_group - is_available_globally - is_available_in_group - missing_required_skills additionalProperties: false required_skills: default: [] type: array items: type: object properties: id: type: string name: type: string required: - id - name additionalProperties: false required: - strategy - selected - peers - required_skills additionalProperties: false - type: 'null' destination_id: type: string destination_name: type: string destination_type: type: string enum: - phone - sip - hangup transfer_reason: anyOf: - type: string - type: 'null' is_failover: type: boolean failover_source: type: string enum: - stt - llm - tts hangup_initiator: type: string enum: - user - agent - system hangup_reason: type: string duration_seconds: type: number call_direction: type: string enum: - inbound - outbound additionalProperties: false mode: type: object properties: id: type: string name: type: string slug: type: string required: - id - name additionalProperties: false didExitMode: type: boolean required: - type - value - mightSolveUserIssue - completelyAndFullyCoveredUserIssue additionalProperties: false uiResponse: type: object properties: type: type: string const: ui value: type: object properties: type: type: string const: ui_component request_response: {} name: type: string content: type: string required: - type - request_response - name additionalProperties: false mightSolveUserIssue: type: boolean required: - type - value - mightSolveUserIssue additionalProperties: false sessionIsHandedOff: type: boolean resolveArgs: type: object properties: summary: type: string description: >- Summary of the conversation with the user to be viewed by a human agent. sentiment: type: string enum: - angry - happy - neutral required: - summary - sentiment additionalProperties: false toolCallResultsQuickReplySuggestions: type: array items: type: object properties: tool_name: type: string suggestions: type: array items: type: string required: - tool_name - suggestions additionalProperties: false required: - success additionalProperties: false - type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string additionalProperties: false required: - success - error additionalProperties: false required: - success - data additionalProperties: false ErrorDto: type: object properties: statusCode: type: integer message: type: string error: type: string ChatAttachmentInput: $schema: https://json-schema.org/draft/2020-12/schema $id: '#/components/schemas/ChatAttachmentInputInput' type: object properties: name: type: string description: The name of the file url: description: The URL of the file (mutually exclusive with base64) type: string base64: description: >- Base64-encoded file content (mutually exclusive with url). Can be a data URL (data:mimetype;base64,...) or raw base64 string. type: string mime_type: description: >- MIME type of the file (e.g., "image/png", "application/pdf"). Optional if using data URL format or if type can be detected from file content. type: string required: - name securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````