POST /api/v1/channels/{channelId}/messages

The Channels API lets you send messages to contacts through a configured API channel in your workspace. When you post a message, the platform creates or resolves the contact by contactIdentifier, routes the message to your AI agent, and returns the agent’s response synchronously in the same API call.

Conversations through an API channel are handled exclusively by AI agents. There is no interface for human agents to join these conversations, so transfer to a human is not supported.

Endpoint

POST /api/v1/channels/{channelId}/messages

Authentication

Include your Workspace API Key and, optionally, an idempotency key in the request headers.

X-API-Key: your_workspace_api_key
Content-Type: application/json
X-Idempotency-Key: optional_key_to_prevent_duplicates

Path parameters

string

required

The ID of the API channel configured in your workspace.

Request body parameters

string

required

The message type. One of: TEXT, IMAGE, AUDIO, VIDEO, DOCUMENT.

string

required

A unique identifier for the contact. Used to create or look up the contact across requests. We recommend using the contact’s email address.

string

Display name for the contact. Used when creating a new contact record.

object

required

The message payload. The shape of this object depends on the type field — see the message type examples below.

Always use the same contactIdentifier value for the same person. Using different identifiers for the same contact (for example, joao@example.com in one request and user@example.com in another) creates separate contact records and breaks conversation history.

Message types

Text

{
  "content": {
    "text": {
      "body": "Hello, how can I help you?"
    }
  },
  "type": "TEXT",
  "contactIdentifier": "user@example.com",
  "contactName": "User Name"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "Hello! How can I help you today?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Image

{
  "content": {
    "image": {
      "url": "https://example.com/image.jpg",
      "caption": "Image caption"
    }
  },
  "type": "IMAGE",
  "contactIdentifier": "user@example.com"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I see an interesting image! How can I help you with that?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Audio

{
  "content": {
    "audio": {
      "url": "https://example.com/audio.mp3"
    }
  },
  "type": "AUDIO",
  "contactIdentifier": "user@example.com"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "Audio transcription: Hello, I need help with my order"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Video

{
  "content": {
    "video": {
      "url": "https://example.com/video.mp4",
      "caption": "Video caption"
    }
  },
  "type": "VIDEO",
  "contactIdentifier": "user@example.com"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I received your video! How can I help you with that?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Document

{
  "content": {
    "document": {
      "url": "https://example.com/document.pdf",
      "filename": "document.pdf",
      "caption": "Document description"
    }
  },
  "type": "DOCUMENT",
  "contactIdentifier": "user@example.com"
}

{
  "success": true,
  "contactId": "cmg5gdkb60000sb75h4yu6mam",
  "conversationId": "cmg6etn5u000dsbx2htkjot8r",
  "messageId": "cmg6zqegm0001sbw9ip35juiq",
  "conversation": {
    "status": "ACTIVE",
    "assignedToHuman": false,
    "aiAgentId": "cmdi03x0z0003sbz6ubwtdrml",
    "aiAgentName": "Aurora",
    "teamId": "0fb043a2-75f7-42d7-b542-1ffcc1f75ccf",
    "teamName": "Technical Support"
  },
  "aiMessages": [
    {
      "content": {
        "text": {
          "body": "I received your document! How can I help you with that?"
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Response fields

boolean

required

Indicates whether the operation succeeded.

string

required

The unique ID of the contact that was created or matched by contactIdentifier.

string

required

The unique ID of the conversation.

string

required

The unique ID of the message that was sent.

object

required

Details about the conversation and its assignment.

Show properties

string

Current conversation status (e.g. ACTIVE).

boolean

Whether the conversation is assigned to a human agent.

string

ID of the AI agent handling the conversation.

string

Display name of the AI agent.

string

ID of the team the conversation belongs to.

string

Display name of the team.

array

required

The AI agent’s response messages, ordered ascending (earliest first). This is an array because the AI may split its response across multiple sequential messages.

object

required

Credit consumption information.

Show properties

number

Number of credits consumed by this request.

HTTP status codes

Code	Description
`200`	Success — message processed
`400`	Invalid request data or channel not found
`401`	Missing or invalid API key
`404`	Channel not found
`500`	Internal server error

Integration examples

async function sendMessage(channelId, apiKey, message) {
  const response = await fetch(`/api/v1/channels/${channelId}/messages`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify({
      content: {
        text: {
          body: message
        }
      },
      type: 'TEXT',
      contactIdentifier: 'user@example.com'
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

try {
  const result = await sendMessage('channel_123', 'your_api_key', 'Hello!');
  console.log('Message sent:', result);
} catch (error) {
  console.error('Error:', error);
}

import requests

def send_message(channel_id, api_key, message_data):
    url = f"https://your-domain.com/api/v1/channels/{channel_id}/messages"

    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': api_key
    }

    response = requests.post(url, headers=headers, json=message_data)

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"HTTP {response.status_code}: {response.text}")

message_data = {
    "content": {
        "text": {
            "body": "Hello, I need help!"
        }
    },
    "type": "TEXT",
    "contactIdentifier": "customer@example.com",
    "contactName": "John Smith"
}

try:
    result = send_message('channel_123', 'your_api_key', message_data)
    print('Message sent:', result)
except Exception as e:
    print('Error:', e)

curl -X POST "https://your-domain.com/api/v1/channels/channel_123/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "content": {
      "text": {
        "body": "Hello, I need help!"
      }
    },
    "type": "TEXT",
    "contactIdentifier": "customer@example.com",
    "contactName": "John Smith"
  }'

Limitations

AI only: Conversations are exclusive to AI agents — human agent handoff is not available.
Consistent contactIdentifier: Always use the same value for the same contact. We recommend using the contact’s email address.
Public media URLs: Image, audio, video, and document URLs must be publicly accessible.
File size limit: Maximum 10 MB per file.
Download timeout: Media downloads time out after 30 seconds.
Idempotency: Use X-Idempotency-Key to avoid duplicate messages on retried requests.

Overview

Endpoints

POST /api/v1/channels/{channelId}/messages

Endpoint

Authentication

Path parameters

Request body parameters

Message types

Text

Image

Audio

Video

Document

Response fields

HTTP status codes

Integration examples

Limitations

​Endpoint

​Authentication

​Path parameters

​Request body parameters

​Message types

​Text

​Image

​Audio

​Video

​Document

​Response fields

​HTTP status codes

​Integration examples

​Limitations

Endpoint

Authentication

Path parameters

Request body parameters

Message types

Text

Image

Audio

Video

Document

Response fields

HTTP status codes

Integration examples

Limitations