Channels: Web & Mobile.

Channel Types and Creation

A Cxperium account can have more than one channel. All channels connect to the same bot, the same contact list and the same inbox; agents see the conversation on one screen regardless of where it came from.

To create a new channel:

1. Open the Channels page

   Go to Channels in the left menu and click Add at the top right.

2. Pick the type

   Choose the Web card for chat on your website, or Mobile for a mobile app or your own client.

3. Give it a name and a bot address

   Enter a name for the channel and the bot address that incoming messages on this channel are forwarded to. The default language is optional. Click Add Channel.

4. Collect the connection details

   The last step shows the channel key, the secret and (for the Web type) a ready-made install code. You can reach these later from the Detail window in the Channels list.

Web Channel: Widget Setup

The web channel adds a chat bubble to the corner of your site. The visitor clicks the bubble, optionally types a name and starts talking to the bot or your agent. Setup is a single snippet of code.

<!-- Cxperium chat -->
<script>
  window.cxperiumSettings = {
    channelKey: "ch_c727ccd3ef5112a1",
    secret: "f57b4e…",
    brand: "Acme Support",
    color: "#7c3aed",
    launcherText: "Chat with us",
    texts: { greetingMessage: "Hi! How can we help you?" }
  };
  // Optional: introduce the user signed in on your site —
  // the welcome form is skipped and the chat starts right away:
  // window.cxperiumSettings.user = { name: "Jane Doe", username: "jane.d" };
  (function (d) {
    var s = d.createElement("script");
    s.src = "https://cdn.cxperium.com/widget/v1/cxperium-widget.js";
    s.async = true;
    d.head.appendChild(s);
  })(document);
</script>

1. Copy the code

   Click Copy in the last step of channel creation or in the Channels → Detail window. If you customised the appearance, copy the code from the Widget Designer; that code contains your design.

2. Paste it into your site

   Paste it right before the </body> tag on every page where the chat should appear. There must be only one Cxperium snippet per page; remove any old one.

3. Reload the page

   The bubble should appear in the chosen corner. If not, reload without cache (Ctrl + F5).

The widget stores the visitor's identity and token in the browser; when the visitor returns, they can continue the previous conversation or open a new one. If you introduce a signed-in user through the user setting, the welcome form is never shown.

The same widget in a mobile app: you can also use the custom channel inside a WebView. The WebView Customizer screen of a mobile channel in the Channels list configures the look of the page you embed in your app, so you can add chat without writing the SDK integration below.

Widget Appearance (Widget Designer)

You change the bubble's colour, position, texts and brand from the dashboard. The designer opens only for channels of the Web type.

You reach the designer from two places: the Customize appearance button in the last step when you create the channel, or later from the channel's Detail window in the Channels list. The screen has three parts: settings on the left, a live preview on the right (Chat / Welcome form views) and the install code under the preview. There is no save button; every change is reflected in both the preview and the code within about half a second.

Brand

Colours and font

Layout and size

Texts and behaviour

The install code contains only the settings that differ from the defaults, so it stays short. Reset to defaults in the top bar clears all settings and the draft.

Mobile App (Custom Channel)

The mobile channel (custom channel) connects your iOS, Android, React Native or Flutter app directly to Cxperium. The user writes a message in the app, the bot or an agent replies, and the reply lands in the app instantly. No backend required.

Two setup paths

The decision comes down to one question: will your own server sit between your app and Cxperium?

If you have no backend, follow path A. The steps below describe path A; for path B only the authentication header changes (see "If you have a server: signature").

Step 1: Register (once, on first launch)

const res = await fetch("https://provider.cxperium.com/custom/ch_xxxxxxxx/register", {
  method: "POST",
  headers: { "apiKey": SECRET, "Content-Type": "application/json" },
  body: JSON.stringify({ user: { name: "Jane" } }),
}).then((r) => r.json());

// res = { status: 200, channelKey: "ch_xxxxxxxx",
//         contact: { id: "c_5d5cdeb1-…" }, token: "8abfc196…" }
save("contactId", res.contact.id);   // Keychain / EncryptedSharedPreferences
save("token", res.token);             // never expires, obtained once

If the app was reinstalled and you still have the stored contactId, include it in the registration body as user.id; the same token is returned and the conversation continues where it left off. The user id cannot contain the & character.

Step 2: Connect and fetch history (on every launch)

import { io } from "socket.io-client";

const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: { channelKey: "ch_xxxxxxxx", user: contactId, token },
});

socket.on("connect", async () => {
  // ORDER MATTERS: connect first, THEN fetch history — the reverse loses messages.
  // If you store messages locally, after = last seen seq; otherwise 0.
  let after = stored("lastSeq") || 0;
  for (;;) {
    const h = await fetch(
      `https://provider.cxperium.com/custom/ch_xxxxxxxx/messages?user=${contactId}&after=${after}&limit=50`,
      { headers: { Authorization: `Bearer ${token}` } },
    ).then((r) => r.json());
    for (const m of h.messages) render(m);
    if (!h.hasMore) break;
    after = h.cursor;   // advance from the page's cursor, not from your own counter
  }
});

History returns both directions: direction: "in" is the user's own message (draw on the right), "out" is a bot or agent reply (draw on the left). seq is a per-user increasing sequence number.

Step 3: Send, receive and acknowledge

// Send — id is the replay guard: on a network error resend with the SAME id
socket.emit("message.send",
  { user: { name: "Jane" }, message: { id: uniqueId(), type: "text", text: "hello" } },
  (ack) => { /* ack = { status: 202, messageId: "…" } */ });

// Receive — m = { id, seq, ts, type, text, choices, media, link, form }
socket.on("message.created", (m) => {
  if (seen.has(m.id)) return;   // the same message can arrive twice
  seen.add(m.id);
  render(m);
  save("lastSeq", m.seq);
  socket.emit("message.ack", { seq: m.seq }, () => {});   // everything up to seq counts as delivered
});

If the WebSocket is down, the same bodies can be sent over REST: POST /custom/<KEY>/messages and POST /custom/<KEY>/ack with the Authorization: Bearer <token> header. socket.io reconnects on its own; when connect fires again, run the history fetch from Step 2 once more and any messages missed in between arrive.

• Persist contactId and token — they must survive the app being closed.
• WebSocket first, then history — the reverse order misses messages that arrive in between.
• Deduplicate messages by id — the system guarantees at-least-once delivery, not exactly-once.
• When paging, advance after from the response cursor — not from a counter you keep yourself.
• Don't panic on disconnects — fetch history after reconnecting; no message is lost.

If you have a server: signature (path B)

The app talks to your server, and your server talks to Cxperium. The secret never reaches the app. Every request carries an X-Cxperium-Signature: t=<unix seconds>,v1=<hex> header where v1 = HMAC-SHA256(secret, "<t>.<content>"). The content is the raw JSON body for POST requests, and the string "<channelKey>:<userId>" for the WebSocket connection and the history query. A signature is valid for 300 seconds; generate a fresh one for every request.

const crypto = require("crypto");
function sign(content) {
  const t = Math.floor(Date.now() / 1000);
  const v1 = crypto.createHmac("sha256", CHANNEL_SECRET).update(`${t}.${content}`).digest("hex");
  return `t=${t},v1=${v1}`;
}

// For WebSocket, auth must be a FUNCTION, not a static object — the signature is refreshed on reconnect
const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: (cb) => cb({ channelKey: CHANNEL_KEY, user: userId, signature: sign(`${CHANNEL_KEY}:${userId}`) }),
});

Message Types and Forms

The same message body is used in the WebSocket message.created event, in the history query and in the delivery webhook. If a type you don't recognise arrives, show the text field; new types are added over time and text is always populated.

What you can send from the user to the bot

The location type is not supported yet; sending it returns 202 but it is not processed.

What can arrive from the bot

Forms (Flow)

The bot can send forms to the custom channel with the same code it uses for WhatsApp Flows. The form definition arrives inside the message as form.screens; the screens are in Meta Flow JSON format (TextInput, Dropdown, RadioButtonsGroup, CheckboxGroup, DatePicker, Footer). Start with form.screen; form.data is the data of the first screen. If you cannot render forms, at least show the text field.

• Answer: if the Footer action of the last screen is complete, send the filled fields as a normal message of type form; token is required.
• Requesting a screen from the server: if the Footer action is data_exchange, call POST /custom/<KEY>/flows/exchange; the response is { "version": "3.0", "screen": "…", "data": { … } }. If screen is SUCCESS, close the form and send the data.extension_message_response.params object as the answer.
• Ready-made implementation: the web widget implements this whole section; a WebView integration needs no extra work.

Troubleshooting

The most common situations and their fixes.

Web widget

Custom channel (mobile)