How to Connect and Use the API Channel in ChatbotX

​

Key Capabilities and How It Works

• Comprehensive Multimedia Support: Send and receive text messages, images, audio clips / voice notes, video files, and documents (PDF, DOCX, XLSX, etc.).
• Unified Inbox: Messages from your custom channels appear directly in the centralized ChatbotX Inbox alongside Messenger, Zalo, WhatsApp, and Webchat.
• AI & Flow Automation: Trigger Flow Automation sequences, smart AI Agent replies, or live chat routing rules immediately upon message arrival.

​

Bidirectional Data Flow

1. Inbound (Receiving messages into ChatbotX): Your application or server makes an HTTP POST request containing the customer’s message to ChatbotX’s Inbound API Endpoint using your Channel API Token for authentication.
2. Outbound (Sending replies from ChatbotX): When an AI Agent or live agent replies within ChatbotX Inbox, ChatbotX sends an HTTP POST payload containing the message response to your configured Callback URL.

​

How to Create an API Channel on ChatbotX

​

Step 1: Navigate to API Channel Settings

1. Log in to your ChatbotX Workspace dashboard.
2. In the left navigation menu, click Settings.
3. Select the Channels tab in the top navigation bar.
4. Scroll down to the channel list and select API.
5. Click the Add API button in the upper-right corner.

​

Step 2: Configure Channel Details

• Name: Enter a descriptive name for your channel (e.g., WhatsApp Support, Telegram Hotline, or Internal Mobile App).
• Callback URL (Optional): Enter your server’s webhook endpoint URL to receive outgoing replies from ChatbotX. If your channel only receives messages and does not require ChatbotX to send replies back, you can leave this field blank.

​

Step 3: Create the Channel and Copy Your API Token

1. Click the green Create button.
2. ChatbotX will generate your unique Channel API Token (prefixed with cbx_api_...).
3. Copy and store this token securely. You will use it in the Authorization: Bearer <TOKEN> header when sending inbound messages to ChatbotX.

Note: You can create multiple API Channels within the same Workspace to independently manage different phone numbers, branches, or communication platforms.

​

Integrating Personal WhatsApp via WAHA ChatbotX Gateway

​

Step 1: Deploy WAHA ChatbotX Gateway

# Clone the repository
git clone https://github.com/craybull/waha-chatbotx-dashboard.git
cd waha-chatbotx-dashboard

# Start the gateway container
docker compose -f docker-compose.chatbotx.yaml up -d

​

Step 2: Connect Your WhatsApp Account (Dashboard Step 1)

​

Method 1: Scan QR Code (Recommended)

1. Select the QR Code tab.
2. Open WhatsApp on your phone: go to Settings > Linked Devices.
3. Tap Link a Device and point your phone’s camera at the QR code displayed on your screen.

💡 Real-time Instant Transition: As soon as your phone scans the code, the dashboard automatically hides the QR box and displays the green Connected Online badge with your WhatsApp display name and phone number in real time without refreshing the page.

​

Method 2: Link with Phone Number (Pairing Code)

1. Select the Phone Pairing Code tab.
2. Enter your WhatsApp phone number in international format (without leading zeros, e.g., 14155552671 or 84384524243).
3. Click Get Code.
4. An 8-digit pairing code will appear. Open WhatsApp on your phone > Linked Devices > Link with phone number > enter the 8-digit code to authenticate.

​

Step 3: Create Channel on ChatbotX (Dashboard Step 2)

1. Click Open ChatbotX to quickly launch the channel management page in a new tab.
2. Copy the auto-detected configuration:
   • Channel Name: Suggested name automatically synchronized with your WhatsApp profile name (e.g., Quoc Kiem (+84384524243)).
   • Callback URL: The dedicated Webhook route for this specific WhatsApp number (e.g., https://waha.yourdomain.com/webhooks/chatbotx).
3. In ChatbotX, click Add API, paste the Channel Name and Callback URL, then click Create.
4. Copy the generated Channel API Token.

​

Step 4: Link and Activate Channel (Dashboard Step 3)

1. Paste your Channel API Token into the ChatbotX API Token input field.
2. Verify the ChatbotX API URL (default: https://app.chatbotx.io/api) and your Media & Webhook Base URL.
3. Optionally check Forward WhatsApp group messages to ChatbotX if you want your AI bot to process group chat messages.
4. Click Save & Activate Channel.

💡 Auto Disconnect Synchronization: If you ever click Disconnect in Step 1, the dashboard automatically syncs with Step 3, resetting the stored token and preparing the interface for a clean re-link.

​

Step 5: Test Inbound and Outbound Messaging

1. Test Outbound Message:
   • The Test Outbound Message card appears directly below Step 1 as soon as the account is Online.
   • Enter a recipient phone number with country code (e.g., 14155552671) and your test message.
   • Click Send Test Message to verify immediate delivery from your connected WhatsApp account.
2. Test Inbound Message:
   • Send a message from a different phone number to your connected WhatsApp number.
   • Open Inbox in ChatbotX to see the conversation appear instantly and watch your AI Agent reply automatically.

​

Multi-Account WhatsApp Management

1. In the WAHA Dashboard top bar, click the + Add Account button.
2. Enter an identifier for the new session (e.g., account_2, sales_la, support_nyc).
3. The dashboard initializes an independent session with its own unique Callback URL.
4. Create a matching API Channel in ChatbotX and activate the token.
5. Easily switch between accounts using the top session bar to view QR codes, monitor online status, or manage each number independently.

​

API Channel Technical Specification (For Developers)

​

Inbound Text Message

• Content-Type: application/json
• Authorization: Bearer <YOUR_CHANNEL_API_TOKEN>

{
  "sender_id": "14155552671",
  "sender_name": "Alex Johnson",
  "message_type": "text",
  "text": "Hello, I would like to know more about your product!"
}

​

Inbound Media Message

{
  "sender_id": "14155552671",
  "sender_name": "Alex Johnson",
  "message_type": "image",
  "text": "Attached receipt screenshot",
  "media_url": "https://example.com/uploads/receipt.jpg"
}

​

Outbound Webhook Response Format

{
  "event": "message.created",
  "recipient_id": "14155552671",
  "message": {
    "type": "text",
    "text": "Thank you for reaching out! Our team is ready to assist you."
  }
}

​

Frequently Asked Questions (FAQ)