> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Channel

> Connect custom chat interfaces, mobile applications, proprietary platforms, and external gateways to ChatbotX via API Channel.

**API Channel** is a flexible programmatic gateway in ChatbotX designed for developers and enterprises. It enables bidirectional messaging between ChatbotX and any external system, including custom mobile apps, proprietary web portals, SMS gateways, enterprise CRM/ERP solutions, and third-party messaging services.

With API Channel, your application can push inbound messages into the unified ChatbotX Inbox to be processed by human agents, Flow Automations, and AI Agents, while receiving outbound replies in real time via an HTTP Callback Webhook.

## Real-World Applications

API Channel provides unlimited flexibility for integrating custom conversational workflows:

<CardGroup cols={2}>
  <Card title="In-App Mobile & Web Chat" icon="mobile-screen-button">
    Embed a native chat experience directly into your iOS/Android app or customer web portal. Users chat natively within your app while your team manages conversations centrally in ChatbotX Inbox.
  </Card>

  <Card title="Third-Party Messaging Gateways" icon="comments">
    Connect specialized messaging platforms and regional chat networks (such as Viber, LINE, WeChat, Discord, or internal team tools) directly to ChatbotX.
  </Card>

  <Card title="Two-Way SMS Gateways" icon="comment-sms">
    Bridge telephony SMS providers (such as Twilio, Sinch, or local telco gateways). Incoming SMS messages arrive in Inbox, and AI Agent responses are dispatched back to customers via SMS.
  </Card>

  <Card title="Enterprise CRM & ERP Sync" icon="network-wired">
    Integrate enterprise systems like Salesforce, HubSpot, Zoho, or Odoo to dispatch real-time transactional alerts, order updates, and customer support tickets.
  </Card>

  <Card title="Custom WhatsApp Gateway Bridges" icon="whatsapp">
    Route personal or business phone numbers through self-hosted gateway solutions to manage direct 1:1 customer interactions without Meta Cloud API conversation fees.
  </Card>

  <Card title="Workflow Automation (n8n, Make, Zapier)" icon="diagram-project">
    Connect ChatbotX with automation engines like n8n, Make.com, or Zapier to build intelligent multi-step workflows, query databases in real time, and trigger instant AI responses.
  </Card>
</CardGroup>

## How the API Channel Works

The API Channel operates on a two-way communication model:

```
[ Your Application / System ] ─── (1) REST API (Inbound Message) ───► [ ChatbotX Inbox / AI Agent ]
[ Your Application / System ] ◄── (2) Webhook POST (Outbound Reply) ─ [ ChatbotX Inbox / AI Agent ]
```

1. **Inbound Messages (Client to ChatbotX):** Your server or application sends an HTTP `POST` request to the ChatbotX API containing the subscriber information and message content.
2. **Outbound Messages (ChatbotX to Client):** When an AI Agent, Flow Automation, or live human agent replies, ChatbotX sends an HTTP `POST` payload to your configured **Callback URL**.

<Note>
  The API Channel is designed specifically for **bidirectional conversation handling**. If your use case only requires dispatching one-way transactional notifications into ChatbotX without receiving automated replies, refer to the [API Overview](https://chatbotx.io/docs/api-reference/api-overview) instead.
</Note>

## Setting Up an API Channel in ChatbotX

Follow these steps to create an API Channel inside your ChatbotX workspace:

### Step 1: Open the API Channel Settings

1. Log in to your ChatbotX dashboard.
2. Navigate to **Channels** from the left navigation menu.
3. Select **API** and click **Connect**.

### Step 2: Configure Channel Details

Enter the following configuration fields:

* **Channel Name:** A descriptive name for the channel (for example: `Mobile App Customer Support` or `Internal CRM Bridge`).
* **Callback URL:** The public HTTPS endpoint on your server where ChatbotX will send outbound replies and webhook events.

### Step 3: Retrieve and Activate the Channel API Token

Once created, ChatbotX generates a unique **Channel API Token**.

<Info>
  Keep your Channel API Token secure. It is required for authenticating all inbound API requests to this channel.
</Info>

## Technical API Reference

All API Channel requests require authentication using your `Channel API Token` passed in the `Authorization` header:

```http theme={null}
Authorization: Bearer cbx_api_your_channel_token_here
Content-Type: application/json
```

👉 [**Interactive API Reference: ChatbotX API Channel Documentation**](https://app.chatbotx.io/api#tag/api-channel)

### 1. Verify Token & Fetch Channel Identity (`GET /v1/channels/api/me`)

Validates the `Channel API Token` and retrieves metadata regarding the connected Inbox in your workspace.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.chatbotx.io/api/v1/channels/api/me" \
    -H "Authorization: Bearer cbx_api_your_token_here"
  ```

  ```json Response (200 OK) theme={null}
  {
    "inboxId": "105",
    "inboxName": "Mobile App Customer Support",
    "workspaceId": "42"
  }
  ```
</CodeGroup>

### 2. Send Inbound Message to ChatbotX (`POST /v1/channels/api/messages`)

Pushes customer messages from your application directly into the ChatbotX Inbox. The system automatically creates or updates the subscriber profile (`contact`) and triggers active Flow Automations or AI Agents.

Supports text messages, multimedia attachments (images, audio, video, documents), geographical location coordinates (`location`), and `postbackPayload`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.chatbotx.io/api/v1/channels/api/messages" \
    -H "Authorization: Bearer cbx_api_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "contact": {
        "sourceId": "user_app_99182",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phoneNumber": "+1234567890",
        "avatar": "https://example.com/avatar.jpg"
      },
      "message": {
        "sourceId": "msg_001",
        "text": "Hello, I need help with my recent order",
        "contentType": "text",
        "attachments": [
          {
            "url": "https://example.com/item.jpg",
            "fileType": "image",
            "mimeType": "image/jpeg",
            "name": "item.jpg"
          }
        ]
      }
    }'
  ```

  ```json Response (202 Accepted) theme={null}
  {
    "accepted": true,
    "messageSourceId": "msg_001"
  }
  ```
</CodeGroup>

### 3. Notify Contact Typing Indicator (`POST /v1/channels/api/typing`)

Sends a real-time signal notifying ChatbotX Inbox that the user is currently composing a message (triggering the "typing..." animation for human agents).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.chatbotx.io/api/v1/channels/api/typing" \
    -H "Authorization: Bearer cbx_api_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "contact": {
        "sourceId": "user_app_99182"
      },
      "typing": true
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Successfully accepted
  ```
</CodeGroup>

### 4. Notify Messages Read Status (`POST /v1/channels/api/read`)

Informs ChatbotX Inbox that the customer has opened and viewed replies sent by AI Agents or human team members.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.chatbotx.io/api/v1/channels/api/read" \
    -H "Authorization: Bearer cbx_api_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "contact": {
        "sourceId": "user_app_99182"
      }
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Successfully accepted
  ```
</CodeGroup>

### 5. Report Outbound Delivery Status (`POST /v1/channels/api/delivery-status`)

Reports the delivery state of an outbound message dispatched to the customer's device (`delivered`, `read`, or `failed` with error details).

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.chatbotx.io/api/v1/channels/api/delivery-status" \
    -H "Authorization: Bearer cbx_api_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "messageId": "msg_outbound_88219",
      "status": "delivered",
      "timestamp": "2026-08-28T10:00:00Z"
    }'
  ```

  ```json Response (204 No Content) theme={null}
  // HTTP 204 No Content - Successfully accepted
  ```
</CodeGroup>

### Receiving Agent Replies via Callback URL (Outbound Webhook)

When an AI Agent, Flow Automation, or live human agent sends a reply within ChatbotX Inbox, the system automatically posts an HTTP `POST` event payload to the `Callback URL` configured in your API Channel settings.

Sample Outbound Webhook payload received by your server:

```json theme={null}
{
  "event": "message:created",
  "messageId": "msg_outbound_88219",
  "conversationId": "conv_5501",
  "contact": {
    "sourceId": "user_app_99182",
    "name": "John Doe"
  },
  "message": {
    "text": "Hello, your order has been confirmed successfully!",
    "contentType": "text",
    "attachments": []
  },
  "timestamp": "2026-08-28T10:00:00Z"
}
```