Developer Integration Guide v1.0

Complete reference for integrating with the Chatbot Platform — covering the REST API, Socket.IO real-time layer, web embed widget, and mobile SDK channel setup.

Authentication

All agent-facing REST endpoints (under /api/conversations/) require a valid browser session established by logging in at /auth/login. The session cookie (session) is set automatically by the browser. These endpoints use @login_required (Flask-Login) and cannot be called with an API key.

API Keys can be generated under Company → API Keys. They are stored for future use and upcoming webhook/integration endpoints — they do not currently authenticate any REST route.

Base URL & Common Headers

Base URL: https://<your-domain>

# Agent REST calls — requires active browser session
GET /api/conversations/
Cookie: session=<flask-session-cookie>
X-CSRFToken: <token from <meta name="csrf-token">>

# Widget public endpoints — no auth header needed
GET /chat-widget/history/<conversation_id>?external_id=<sid>

All request bodies are JSON. All responses are JSON unless noted.

Send Message

Messages are sent over Socket.IO, not HTTP. This applies to both end users (from the widget) and agents (from the inbox). The server persists the message, broadcasts it to the conversation room, and optionally triggers a bot response.

Payload

End-User Example (widget)

// JavaScript — inside the widget iframe
socket.emit("send_message", {
  conversation_id: "3a2b1c...",
  content: "Hello, I need help",
  content_type: "text",
  sender_type: "end_user",
  external_id: "browser-session-abc123"
});

Agent Example (inbox)

// JavaScript — inside the agent inbox page
socket.emit("send_message", {
  conversation_id: "3a2b1c...",
  content: "Hi! How can I help you today?",
  content_type: "text",
  sender_type: "agent"
  // external_id not needed — agent is identified by the session cookie
});

Server Response Event

On success, the server broadcasts message_received to everyone in the conversation room (see Event Reference). On failure, a error event is emitted only to the sender.

Message History

Two endpoints provide message history depending on who is calling.

Agent — REST endpoint

End User (Widget) — public endpoint

Returns the last 100 messages. Authorization is via external_id matching the conversation's end user — no session cookie required.

Response shape (both endpoints)

[
  {
    "id":           "uuid",
    "session_id":   "uuid",        // omitted in widget endpoint
    "sender_type":  "end_user",     // end_user | agent | bot
    "sender_id":    "external-id or user-uuid",
    "content_type": "text",
    "content":      "Hello",
    "rich_media":   null,
    "read_by":      {},             // omitted in widget endpoint
    "created_at":   "2025-01-15T08:23:10.000000"
  }
]

Rich Media Types

Pass content_type and a matching rich_media object in the send_message event.

Image

{
  "content_type": "image",
  "content":      "Optional caption",
  "rich_media": {
    "url": "https://example.com/photo.jpg",
    "alt": "A scenic view"
  }
}

File

{
  "content_type": "file",
  "content":      "invoice.pdf",
  "rich_media": {
    "url":       "https://example.com/files/invoice.pdf",
    "filename": "invoice.pdf",
    "size":     204800,           // bytes
    "mime_type":"application/pdf"
  }
}

Quick Buttons

{
  "content_type": "quick_button",
  "content":      "Choose an option:",
  "rich_media": {
    "buttons": [
      { "label": "Yes",  "value": "yes" },
      { "label": "No",   "value": "no"  }
    ]
  }
}

Carousel

{
  "content_type": "carousel",
  "content":      "",
  "rich_media": {
    "cards": [
      {
        "image_url": "https://...",
        "title":     "Product A",
        "subtitle":  "Short description",
        "buttons":   [{ "label": "Buy now", "value": "buy_A" }]
      }
    ]
  }
}

Dropdown

{
  "content_type": "dropdown",
  "content":      "Select your region:",
  "rich_media": {
    "placeholder": "-- pick one --",
    "options": [
      { "label": "Asia Pacific",  "value": "apac" },
      { "label": "Europe",        "value": "eu"   }
    ]
  }
}

List Conversations

Response

[
  {
    "id":          "uuid",
    "end_user": {
      "id":           "uuid",
      "display_name": "John Doe",
      "external_id":  "browser-session-abc"
    },
    "channel_id":  "uuid",
    "active_session": {
      "id":                 "uuid",
      "status":             "open",
      "assigned_agent_id":  null,
      "tags":               []
    },
    "created_at":  "2025-01-15T08:00:00",
    "updated_at":  "2025-01-15T08:23:00"
  }
]

Get Conversation

Returns a single conversation with the same shape as the list items above.

Assignment Process

An agent claims an unassigned conversation either through the REST API or via Socket.IO. Both paths call the same service method (ConversationService.assign_conversation) which sets assigned_agent_id and assigned_at on the open session.

Option A — REST (HTTP POST)

No request body required. The calling agent's identity is read from the session cookie.

# curl example
curl -X POST https://<host>/api/conversations/3a2b1c.../assign \
  -H "Cookie: session=..." \
  -H "X-CSRFToken: ..."

Response

{
  "id":                 "3a2b1c...",
  "assigned_agent_id":  "user-uuid",
  "assigned_at":        "2025-01-15T08:25:00"
}

Option B — Socket.IO event

socket.emit("claim_conversation", {
  conversation_id: "3a2b1c..."
});

On success, the server emits conversation_assigned to the entire org queue room so all connected agents see the conversation leave the unassigned list.

Assignment Flow

Resolve Conversation

Closes the open session. Optionally apply final tags at the same time.

Request body

{
  "tags": ["billing", "resolved-no-action"]   // optional, defaults to []
}

Response

{
  "id":          "conversation-uuid",
  "session_id":  "session-uuid",
  "status":      "resolved",
  "tags":        ["billing", "resolved-no-action"],
  "resolved_at": "2025-01-15T09:10:00"
}

Error states

Tagging

Add tag to open session

{ "tag": "billing" }

Response: { "tags": ["billing"] }

Available tags for a conversation's bot

[{ "id": "uuid", "tag": "billing" }, ...]

Real-Time Layer (Socket.IO)

The platform uses Socket.IO v4 for real-time messaging. Two categories of client connect:

• End users — the widget iframe. No login required. Authenticated via external_id.
• Agents — the inbox SPA. Authenticated via the Flask session cookie. On connect, the server marks the agent as online in Redis.

// Connect (browser)
const socket = io(window.location.origin);

// or with explicit URL and options
const socket = io("https://chat.example.com", {
  transports: ["websocket"],
  withCredentials: true
});

Socket.IO Event Reference

Client → Server

Server → Client

Socket.IO Rooms

Web Embed Widget

The web embed delivers a fully contained chat window as an <iframe> injected into the host page by a small JavaScript loader. No SDK installation is needed — just a <script> tag.

Step 1 — Create an Embed Token

1. Go to Integration → Web Chat in the platform dashboard.
2. Select the bot you want to attach to this embed.
3. Give it a name and (optionally) list allowed origins one per line.
4. Click Create. Copy the generated token (shown once).

Step 2 — Add the Script Snippet

Paste this snippet just before the closing </body> tag on any page where you want the chat widget to appear:

<!-- Chat widget loader -->
<script
  src="https://<your-domain>/chat-widget/embed.js"
  data-embed-token="ew_xxxxxxxxxxxxxxxxxxxx"
></script>

The loader script:

1. Reads data-embed-token from the script tag.
2. Generates or retrieves a persistent session_id from localStorage (key: cw_sid_{token}). This is the end user's external_id.
3. Injects an <iframe> pointing to /chat-widget?embed_token=...&session_id=....
4. The iframe is positioned fixed, bottom-right, 380×560 px.

Custom Parameters

Pass extra query params in the iframe src URL (not via the <script> tag — you would need to build the iframe manually in that case):

Passing a known user identity

If your site has authenticated users, pass their unique identifier as session_id so conversations persist across browsers and devices:

<!-- Example: inject with a server-rendered user ID -->
<script>
  (function() {
    var iframe = document.createElement('iframe');
    iframe.src = 'https://<your-domain>/chat-widget'
      + '?embed_token=ew_xxxx'
      + '&session_id=' + encodeURIComponent('user_' + USER_ID)
      + '&customer_name=' + encodeURIComponent(USER_DISPLAY_NAME)
      + '&title=Support+Chat';
    iframe.style.cssText = 'position:fixed;bottom:0;right:0;width:380px;height:560px;border:none;z-index:2147483647;border-radius:12px 12px 0 0;box-shadow:0 8px 32px rgba(0,0,0,0.18);';
    document.body.appendChild(iframe);
  })();
</script>

Communication between host page and iframe

The widget iframe is sandboxed. Use window.postMessage if you need to pass runtime data from your page into the widget after load. The widget does not currently emit postMessage events back.

Mobile SDK Integration

Mobile apps connect through the same Socket.IO and REST APIs as the web widget. The platform additionally manages push notification credentials (FCM for Android, APNs for iOS) per mobile channel.

Step 1 — Provision a Mobile Channel

1. Go to Integration → Mobile SDK in the dashboard.
2. Select the bot and click Create Channel. Each bot gets one mobile channel.
3. Configure FCM and/or APNs credentials (see Push Notifications).
4. Note the Channel ID — you will need it when opening conversations from the app.

Step 2 — Open a Conversation from the App

Option A — WebView (simplest, works today)

Load the widget URL in a native WebView. The widget handles conversation creation, Socket.IO connection, and message rendering automatically. Use the embed token generated in the dashboard and pass a stable user identifier as session_id:

https://<your-domain>/chat-widget
  ?embed_token=ew_xxxxxxxxxxxxxxxxxxxx
  &session_id=mobile-user-12345
  &customer_name=Alice+Smith
  &title=Support+Chat

Option B — Native Socket.IO (requires pre-existing conversation_id)

If you already have a conversation_id from a prior WebView session or from a server-side process that called ConversationService.create_or_get_conversation() directly, you can connect natively via Socket.IO. The join_conversation event verifies external_id against the stored end user record — it does not create a new conversation.

Step 3 — Connect via Socket.IO

Using any Socket.IO client library (available for iOS, Android, Flutter, React Native):

// build.gradle: implementation 'io.socket:socket.io-client:2.1.0'
val opts = IO.Options.builder()
    .setTransports(arrayOf("websocket"))
    .build()
val socket = IO.socket("https://your-domain.com", opts)

socket.on(Socket.EVENT_CONNECT) {
    socket.emit("join_conversation", JSONObject().apply {
        put("conversation_id", conversationId)
        put("external_id", externalId)
    })
}

socket.on("message_received") { args ->
    val data = args[0] as JSONObject
    // render data.getString("content") in your UI
}

socket.connect()

// Send a message
socket.emit("send_message", JSONObject().apply {
    put("conversation_id", conversationId)
    put("content", userText)
    put("content_type", "text")
    put("sender_type", "end_user")
    put("external_id", externalId)
})

// Package.swift: .package(url: "https://github.com/socketio/socket.io-client-swift", ...)
let manager = SocketManager(
    socketURL: URL(string: "https://your-domain.com")!,
    config: [.log(false), .compress]
)
let socket = manager.defaultSocket

socket.on(clientEvent: .connect) { _, _ in
    socket.emit("join_conversation", [
        "conversation_id": conversationId,
        "external_id":     externalId
    ])
}

socket.on("message_received") { data, _ in
    guard let msg = data.first as? [String: Any] else { return }
    // render msg["content"] in your UI
}

socket.connect()

// Send a message
socket.emit("send_message", [
    "conversation_id": conversationId,
    "content":         userText,
    "content_type":    "text",
    "sender_type":     "end_user",
    "external_id":     externalId
])

// pubspec.yaml: socket_io_client: ^2.0.0
import 'package:socket_io_client/socket_io_client.dart' as IO;

final socket = IO.io('https://your-domain.com', <String, dynamic>{
  'transports': ['websocket'],
  'autoConnect': false,
});

socket.onConnect((_) {
  socket.emit('join_conversation', {
    'conversation_id': conversationId,
    'external_id':     externalId,
  });
});

socket.on('message_received', (data) {
  // render data['content'] in your widget tree
});

socket.connect();

// Send a message
socket.emit('send_message', {
  'conversation_id': conversationId,
  'content':         userText,
  'content_type':    'text',
  'sender_type':     'end_user',
  'external_id':     externalId,
});

Push Notifications

Configure push credentials under Integration → Mobile SDK → {channel}.

FCM (Android / Firebase Cloud Messaging)

APNs (iOS / Apple Push Notifications)

Data Models

Conversation

The top-level entity. One conversation per end user per channel. Multiple sessions can exist over time (one per support interaction).

Conversation Session

Represents a single support interaction within a conversation. A conversation moves through open → resolved, and a new session is created on the next end-user message.

Message

Error Reference

Changelog

Changes to the integration surface — endpoints, Socket.IO events, widget URLs, and documented response fields.

• 2026-05-11 — Corrected widget URL prefix from /widget to /chat-widget throughout. Clarified API keys are stored but do not yet authenticate REST routes. Replaced non-existent POST /api/conversations/init mobile endpoint with accurate WebView and planned-API notes.
• 2026-05-11 — Initial integration guide published: REST API (list, get, history, assign, resolve, tag), Socket.IO event reference, web embed snippet, and mobile SDK channel setup.