> ## Documentation Index > Fetch the complete documentation index at: https://developers.domix.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send message or WhatsApp template (Unified API) > High-level unified endpoint to send a text message or a WhatsApp template message in one step. If the contact or open conversation does not exist, Domix AI automatically creates or resolves them. ## OpenAPI ````yaml /domix-ai-openapi-v1.json post /developer/api/v1/messages openapi: 3.0.3 info: title: Domix AI Developer API description: > # 🚀 Getting Started with Domix AI APIs Welcome to the official **Domix AI Developer API** documentation. Whether you are building automated workflows for your customer support team, integrating Domix AI with your CRM/ERP, sending automated WhatsApp notifications, or building conversational bots, our APIs provide the flexibility and power to do more. --- ## 📚 API Categories & Architecture Domix AI provides specialized API categories tailored for developers: 1. **Unified Messaging API (Recommended)**: - High-level, single-step messaging engine. - Send plain text or pre-approved WhatsApp templates directly by phone number. - Automatically creates or resolves contacts and open conversations in one call. - **Endpoint**: `POST /developer/api/v1/messages` 2. **Core CRM & Conversation APIs**: - Complete control over your customer support and messaging infrastructure. - **Contacts**: Search by phone/email (`GET /contacts/search`), create, update, and manage custom attributes. - **Conversations**: Manage conversation lifecycle (`open`, `resolved`, `pending`, `snoozed`) and staff assignments. - **Messages**: Retrieve message history, send replies, or post internal staff notes (`private: true`). - **Inboxes**: Inspect connected communication channels (WhatsApp, Web Chat, Email, API). 3. **Real-time Webhooks**: - Stream live events directly to your backend server as HTTP POST notifications. - Supported events: `message_created`, `message_updated`, `conversation_created`, `conversation_status_changed`, `contact_created`. --- ## 🔐 Authentication All requests to Domix AI require authentication using your secret **API Access Token**. ### Flexible Header Support To ensure maximum compatibility with different HTTP clients, proxies, and libraries, Domix AI accepts both **hyphenated** and **underscored** header names: | Header | Supported Names | Required For | Description | | :--- | :--- | :--- | :--- | | **Access Token** | `api-access-token` OR `api_access_token` | All API Endpoints | Your private API access token | | **Account ID** | `api-account-id` OR `api_account_id` | Unified Messaging API | Your account identifier in Domix AI | > 💡 **How to obtain your Access Token:** > 1. Log in to your Domix AI dashboard at [chat.domix.ai](https://chat.domix.ai). > 2. Click on your profile avatar (bottom-left) → **Profile Settings**. > 3. Scroll to **Access Token**, copy the token, and keep it confidential. --- ## ⚡ Quickstart: Send a Message in 60 Seconds ### cURL Example ```bash curl -X POST https://chat.domix.ai/developer/api/v1/messages \ -H "Content-Type: application/json" \ -H "api-access-token: YOUR_ACCESS_TOKEN" \ -H "api-account-id: YOUR_ACCOUNT_ID" \ -d '{ "inbox_id": 1, "phone_number": "+966555555555", "content": "Hello from Domix AI API!", "name": "Customer Name" }' ``` ### JavaScript (Node.js / Fetch) ```javascript const response = await fetch('https://chat.domix.ai/developer/api/v1/messages', { method: 'POST', headers: { 'Content-Type': 'application/json', 'api-access-token': 'YOUR_ACCESS_TOKEN', 'api-account-id': 'YOUR_ACCOUNT_ID' }, body: JSON.stringify({ inbox_id: 1, phone_number: '+966555555555', content: 'Hello from Domix AI API!' }) }); const result = await response.json(); console.log('Result:', result); ``` --- ## ❓ Frequently Asked Questions (FAQ) #### Q: Can I use `api-access-token` or `api_access_token`? **A:** Yes, both header conventions are fully supported across all endpoints. #### Q: How can I prevent creating duplicate contacts? **A:** Always use `GET /api/v1/accounts/{account_id}/contacts/search?q=+966555555555` to check if the phone number already exists before calling the create contact endpoint. #### Q: How do I send WhatsApp Template messages? **A:** Use the Unified Messages endpoint (`POST /developer/api/v1/messages`) with `"message_type": "template"` and supply your template's parameters in `template_params`. #### Q: How do I listen to incoming messages in real-time? **A:** Register a Webhook via `POST /api/v1/accounts/{account_id}/webhooks` with subscriptions to `message_created` and `conversation_created`. Your endpoint will receive an instant JSON payload whenever a customer sends a message. version: 1.0.0 contact: name: Domix AI Support url: https://domix.ai servers: - url: https://chat.domix.ai description: Production Server security: - ApiAccessToken: [] ApiAccountId: [] - ApiAccessTokenHyphen: [] ApiAccountIdHyphen: [] tags: - name: Unified Messaging API description: High-level unified messaging and direct conversation message dispatching. - name: Core CRM & Conversation APIs description: >- Manage contacts, conversation statuses, assignments, inboxes, and account configuration. - name: Real-Time Webhooks description: Configure HTTP webhook endpoints to receive instant event notifications. paths: /developer/api/v1/messages: post: tags: - Unified Messaging API summary: Send message or WhatsApp template (Unified API) description: >- High-level unified endpoint to send a text message or a WhatsApp template message in one step. If the contact or open conversation does not exist, Domix AI automatically creates or resolves them. operationId: sendUnifiedMessage parameters: - name: api_account_id in: header required: false description: Account ID header (Supports `api_account_id` or `api-account-id`) schema: type: string example: '16' - name: api-account-id in: header required: false description: Alternative hyphenated header for Account ID schema: type: string example: '16' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UnifiedMessagePayload' examples: TextMessage: summary: Send Plain Text Message value: inbox_id: 1 phone_number: '+966555555555' content: Hello! Thank you for contacting Domix AI support. name: Ahmed Mohamed WhatsAppTemplate: summary: Send WhatsApp Template Message value: inbox_id: 1 phone_number: '+966555555555' message_type: template template_params: name: order_confirmation category: MARKETING language: ar components: - type: body parameters: - type: text text: Ahmed - type: text text: '#10492' responses: '200': description: Message dispatched successfully content: application/json: schema: $ref: '#/components/schemas/UnifiedMessageResponse' '401': description: Unauthorized - Invalid token or unauthorized account access content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Inbox not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation error or invalid payload content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: UnifiedMessagePayload: type: object required: - inbox_id properties: inbox_id: type: integer description: ID of the inbox channel (e.g. WhatsApp channel) example: 1 phone_number: type: string description: Recipient phone number with country code (e.g. +966...) example: '+966555555555' contact_id: type: integer description: Optional contact ID if already known example: 160 content: type: string description: Text content of the message example: Hello from Domix AI! message_type: type: string enum: - outgoing - template default: outgoing example: outgoing name: type: string description: Customer name to associate with contact if created example: Ahmed Mohamed email: type: string format: email example: ahmed@example.com custom_attributes: type: object description: Key-value custom attributes for contact example: client_id: ABC-99 template_params: type: object description: Parameters for WhatsApp approved template messages properties: name: type: string example: order_confirmation category: type: string example: MARKETING language: type: string example: ar components: type: array items: type: object UnifiedMessageResponse: type: object properties: status: type: string example: ok conversation_display_id: type: integer example: 12 contact_id: type: integer example: 34 message_id: type: integer example: 56 ErrorResponse: type: object properties: error: type: string example: Invalid Access Token securitySchemes: ApiAccessToken: type: apiKey in: header name: api_access_token description: API Access Token (underscore format) ApiAccountId: type: apiKey in: header name: api_account_id description: Account ID (underscore format for unified message endpoints) ApiAccessTokenHyphen: type: apiKey in: header name: api-access-token description: API Access Token (hyphen format - also fully supported) ApiAccountIdHyphen: type: apiKey in: header name: api-account-id description: Account ID (hyphen format for unified message endpoints) ````