Channels API: messages through an API channel

The Channels API connects the chat in your system (app, website, customer portal) to the BluBash AI agent. Your server sends the message the user wrote, BluBash finds or creates the contact by contactIdentifier, forwards the message to the AI agent, and returns the reply in the same call, synchronously.

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

The API channel is inbound only: the conversation always starts with a message sent by your system. Conversations on this channel are handled by the AI agent, and the API response carries the AI agent’s messages. There is no transfer to a team member on this channel.

Before you start

Ask BluBash support to set up the API channel and give you its channelId.
Have the workspace API Key. See API introduction →.
Configure and test the AI agent that will handle the channel. See Test the AI agent →.

URL

https://api.blubash.io/api/v1/channels/{channelId}/messages

Headers

X-API-Key: YOUR_API_KEY
Content-Type: application/json
X-Idempotency-Key: optional_unique_key

Header	Required	Description
`X-API-Key`	Yes	Workspace API Key
`Content-Type`	Yes	Always `application/json`
`X-Idempotency-Key`	No	Unique value per operation. Prevents duplicate messages when you retry a request

Path parameters

string

required

ID of the API channel configured in the workspace.

Request body

string

required

Message type: TEXT, IMAGE, AUDIO, VIDEO, or DOCUMENT.

string

required

Unique identifier of the contact in your system. BluBash uses this value to create the contact on the first message and to find it on the next ones. We recommend the user’s email.

string

Contact name. Used when creating a new contact.

object

required

Message content. The format depends on type, as shown in the table below.

`type`	`content` format	Fields
`TEXT`	`{ "text": { ... } }`	`body` (required)
`IMAGE`	`{ "image": { ... } }`	`url` (required), `caption`
`AUDIO`	`{ "audio": { ... } }`	`url` (required)
`VIDEO`	`{ "video": { ... } }`	`url` (required), `caption`
`DOCUMENT`	`{ "document": { ... } }`	`url` (required), `filename`, `caption`

Always use the same contactIdentifier for the same person. Different values for the same user (for example, john@company.com in one call and an internal ID in another) create separate contacts and break the conversation history.

Request examples

{
  "type": "TEXT",
  "contactIdentifier": "john@company.com",
  "contactName": "John Smith",
  "content": {
    "text": {
      "body": "Hi, I need help with my order."
    }
  }
}

{
  "type": "IMAGE",
  "contactIdentifier": "john@company.com",
  "content": {
    "image": {
      "url": "https://example.com/product-photo.jpg",
      "caption": "This is how the product arrived"
    }
  }
}

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

{
  "type": "VIDEO",
  "contactIdentifier": "john@company.com",
  "content": {
    "video": {
      "url": "https://example.com/video.mp4",
      "caption": "Video of the issue"
    }
  }
}

{
  "type": "DOCUMENT",
  "contactIdentifier": "john@company.com",
  "content": {
    "document": {
      "url": "https://example.com/invoice.pdf",
      "filename": "invoice.pdf",
      "caption": "Purchase invoice"
    }
  }
}

Response example

The response structure is the same for every message type.

{
  "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": "Hi John! Sure, send me your order number and I will check it for you."
        },
        "type": "text"
      },
      "type": "TEXT",
      "sender_type": "AI",
      "sender_name": "Aurora",
      "channel_message_id": null
    }
  ],
  "usage": {
    "credits": 1
  }
}

Response fields

boolean

required

Whether the operation completed.

string

required

ID of the contact created or found by contactIdentifier.

string

required

Conversation ID.

string

required

ID of the message sent in the request.

object

required

Conversation and assignment data.

Show Properties

string

Current conversation status, for example ACTIVE.

boolean

Whether the conversation is assigned to a team member.

string

ID of the AI agent handling the conversation.

string

AI agent name.

string

ID of the conversation’s team.

string

Team name.

array

required

The AI agent’s reply messages, from oldest to newest. It is a list because the AI agent can split its reply into several messages, depending on the Split Responses setting. Display all of them, in order.

object

required

Credit usage.

Show Properties

number

Credits consumed by the request.

HTTP status codes

Code	Description
`200`	Message processed successfully
`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, contactIdentifier, text) {
  const response = await fetch(
    `https://api.blubash.io/api/v1/channels/${channelId}/messages`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey,
        'X-Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        type: 'TEXT',
        contactIdentifier,
        content: { text: { body: text } }
      })
    }
  );

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

  return response.json();
}

const result = await sendMessage('YOUR_CHANNEL_ID', process.env.BLUBASH_API_KEY, 'john@company.com', 'Hello!');
for (const message of result.aiMessages) {
  console.log(message.content.text?.body);
}

import os
import uuid
import requests

def send_message(channel_id, api_key, message_data):
    url = f"https://api.blubash.io/api/v1/channels/{channel_id}/messages"
    headers = {
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Idempotency-Key": str(uuid.uuid4()),
    }
    response = requests.post(url, headers=headers, json=message_data, timeout=60)
    response.raise_for_status()
    return response.json()

message_data = {
    "type": "TEXT",
    "contactIdentifier": "john@company.com",
    "contactName": "John Smith",
    "content": {"text": {"body": "Hi, I need help!"}},
}

result = send_message("YOUR_CHANNEL_ID", os.environ["BLUBASH_API_KEY"], message_data)
for message in result["aiMessages"]:
    print(message["content"]["text"]["body"])

curl -X POST "https://api.blubash.io/api/v1/channels/YOUR_CHANNEL_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "TEXT",
    "contactIdentifier": "john@company.com",
    "contactName": "John Smith",
    "content": {
      "text": {
        "body": "Hi, I need help!"
      }
    }
  }'

The response returns only after the AI agent finishes replying. Set a compatible timeout in your HTTP client and show a “typing” indicator to the user while waiting.

Limitations

Item	Rule
Service	AI agent only. There is no transfer to a team member on this channel.
`contactIdentifier`	Always use the same value for the same person. We recommend the email.
Media URLs	Must be public and reachable without authentication.
File size	Up to 10 MB per file.
Media download	30-second timeout.
Duplicates	Use `X-Idempotency-Key` to avoid duplicate messages on retries.

Overview

Endpoints

Channels API: messages through an API channel

Before you start

URL

Headers

Path parameters

Request body

Request examples

Response example

Response fields

HTTP status codes

Integration examples

Limitations

Next steps

Train the AI agent

Campaigns API

​Before you start

​URL

​Headers

​Path parameters

​Request body

​Request examples

​Response example

​Response fields

​HTTP status codes

​Integration examples

​Limitations

​Next steps

Train the AI agent

Campaigns API

Before you start

URL

Headers

Path parameters

Request body

Request examples

Response example

Response fields

HTTP status codes

Integration examples

Limitations

Next steps