API Channel

Overview

The API channel provides a developer integration point for connecting custom messaging platforms, proprietary interfaces, or any external system to Support Portal. Unlike pre-built social media channels, the API channel requires programmatic interaction through REST APIs and webhook callbacks, giving your engineering team full control over the conversation lifecycle.

Use cases include:

• Building a custom chat interface in place of the default web widget.
• Embedding conversational support into mobile applications.
• Bridging Support Portal to platforms for which no native channel integration exists.

Prerequisites

• An active Support Portal account with permission to create Inboxes (see Adding Inboxes).
• A callback URL endpoint capable of receiving HTTP POST requests (for webhook delivery).
• An API access token, obtainable from Profile Settings > Access Token within Support Portal.

Configuration Steps

1. Initiate Inbox Creation

Navigate to Settings > Inboxes and select Add Inbox.

2. Select the API Channel Type

From the channel selection interface, select the API icon.

3. Provide Channel Parameters

The configuration interface presents the following fields:

Select Create API Channel to proceed.

4. Assign Agents

Add one or more Agents to the Inbox.

Sending Messages to the API Channel

All API requests require the api_access_token header. The following sequence establishes a conversation:

Step 1: Create a Contact

Issue a POST request to create a contact, including the Inbox ID of the API channel. The response includes contact_inboxes, each containing a source_id that serves as a session identifier.

{
  "email": "[email protected]",
  "name": "Customer Name",
  "phone_number": "+1234567890",
  "contact_inboxes": [
    {
      "source_id": "session-identifier-string",
      "inbox": {
        "id": 1,
        "name": "Mobile App Support",
        "channel_type": "Channel::Api"
      }
    }
  ],
  "id": 42
}

Step 2: Create a Conversation

Use the source_id from the previous response to create a conversation. The response returns a conversation ID.

{
  "id": 101
}

Step 3: Create a Message

Send a message to the conversation. Messages are classified as either:

• Incoming (message_type: 0) — messages originating from the end user.
• Outgoing (message_type: 1) — messages sent by an Agent.

{
  "id": 1,
  "content": "Message content",
  "inbox_id": 1,
  "conversation_id": 101,
  "message_type": 0,
  "created_at": 1693000000,
  "private": false,
  "sender": {
    "id": 42,
    "name": "Customer Name",
    "type": "contact"
  }
}

Receiving Messages via Webhook Callback

When a new message is created in the API channel (for example, an Agent reply), Support Portal delivers a POST request to the callback URL configured during Inbox creation. The payload follows the message_created event structure:

{
  "id": 1,
  "content": "Agent response content",
  "created_at": "2024-08-30T15:43:04.000Z",
  "message_type": "outgoing",
  "sender": {
    "id": 5,
    "name": "Agent Name",
    "type": "user"
  },
  "inbox": {
    "id": 1,
    "name": "Mobile App Support"
  },
  "conversation": {
    "channel": "Channel::Api",
    "id": 101,
    "inbox_id": 1,
    "status": "open"
  },
  "event": "message_created"
}

For a complete list of supported webhook events, see Webhooks.

Client APIs

Support Portal exposes Client APIs specifically designed for building customer-facing interfaces on top of the API channel.

Authentication

Obtain the inbox_identifier from Inbox Settings > Configuration. The customer_identifier (also referred to as source_id) is returned when creating a contact through the API. Store this identifier on the client side (e.g., in cookies or local storage) to make subsequent requests on behalf of the customer.

HMAC Verification

Client APIs support HMAC-based identity validation to prevent impersonation. The HMAC token for the channel is available through the platform's administrative interface.

WebSocket Connectivity

To receive real-time updates from the Agent Dashboard, establish a WebSocket connection to:

wss://<your-instance-url>/cable

Subscribe using the customer's pubsub_token (provided during contact creation) to receive events directed to that customer object.

const connection = new WebSocket('wss://your-instance.example.com/cable');
connection.send(JSON.stringify({
  command: "subscribe",
  identifier: JSON.stringify({
    channel: "RoomChannel",
    pubsub_token: customer_pubsub_token
  })
}));

Expected Behavior

Once configuration is complete, contacts and conversations created through the API appear in the Support Portal Dashboard identically to those from other channels. Agents can respond through the Dashboard, and those responses trigger webhook callbacks to your callback URL. All standard features — including labels, macros, and automation rules (see Automation) — apply.

Governance Notes

• Data responsibility: Because the API channel connects arbitrary external systems, your organization is responsible for ensuring that data transmitted through this channel complies with applicable privacy regulations.
• Callback URL security: The callback endpoint should validate incoming requests to prevent unauthorized payloads. Consider implementing signature verification or IP allowlisting.
• Token management: API access tokens grant broad permissions. Rotate tokens regularly and restrict their distribution to authorized systems. Store tokens securely and never expose them in client-side code.