Connect quickstart

By the end of this page an order in your system has a live conversation between its customer, merchant, and courier — with the AI Supervisor already answering the questions none of them should have to. Everything below uses your normal API key.

Create a thread when the order is confirmed

One call, at the same place in your backend where you confirm the order. reference is your order ID — calls with the same reference are idempotent, so retries are safe.

curl -X POST https://api.open.cx/connect/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_84421",
    "participants": [
      { "role": "customer", "external_id": "cus_991",
        "display_name": "Fatima", "language": "ar" },
      { "role": "merchant", "external_id": "mrc_204",
        "display_name": "Shawarma House", "language": "en" }
    ],
    "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" }
  }'

{
  "id": "th_9f2c4e",
  "reference": "order_84421",
  "status": "open",
  "order_status": "confirmed",
  "lanes": [
    { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
    { "id": "customer_courier", "status": "waiting" }
  ]
}

The customer↔merchant lane is live immediately. The customer↔courier lane exists but waits — there’s no courier yet.

Notice language per participant. Fatima writes Arabic, the merchant reads English, and neither ever notices — the Supervisor translates both directions live.

Add the courier when you assign one

curl -X POST https://api.open.cx/connect/threads/th_9f2c4e/participants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "courier", "external_id": "drv_318",
        "display_name": "Aleksei", "language": "en" }'

The customer↔courier lane flips to active. If you reassign the order, remove the courier and add the new one — the lane’s history stays with the thread, the old courier loses access instantly.

Render the thread in your apps

Mint a scoped token per participant, then mount the drop-in component. The token only grants that participant’s view — their lanes, their language, nothing else.

curl -X POST https://api.open.cx/connect/threads/th_9f2c4e/tokens \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "participant_id": "prt_c81" }'

import { ConnectThread } from '@opencx/widget/react';

<ConnectThread token={threadToken} />

The component ships message list, composer, quick replies, attachment upload, read receipts, RTL layout, and the Supervisor’s presence — themed by the same options as the chat widget.Building your own UI? Skip the component and go headless: send messages server-side and receive them via webhooks or the token-scoped WebSocket.

Let order status drive the lifecycle

Tell Connect what the order is doing; it handles what that means for the conversation.

curl -X PATCH https://api.open.cx/connect/threads/th_9f2c4e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "order_status": "delivered" }'

On delivered, participants get a wrap-up window (default 24 hours) for “the gate code didn’t work”-type follow-ups, then the thread locks itself read-only. On cancelled, it locks immediately. Full state machine in Threads.

Tune the Supervisor — or don't

Every thread already has the AI Supervisor in resolve mode: it answers order questions from your Actions, translates between participants, nudges a silent merchant, and escalates to your inbox when a human is needed.Dial it per lane if you want different behavior:

curl -X PATCH https://api.open.cx/connect/threads/th_9f2c4e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "supervisor": { "lanes": { "customer_courier": { "mode": "assist" } } } }'

Org-wide defaults live in the dashboard under Connect → Supervisor. The modes — observe, assist, resolve — are covered in AI Supervisor.

That’s the integration

Two API calls per order (create thread, add courier), one component per app, one PATCH per status change. Compare that to running a chat SDK: provisioning channels per pair, syncing membership, scheduling freezes and deletes, wiring moderation, and building the support handoff yourself.

Threads and lifecycle

Lanes, roles, visibility, the order-driven state machine, retention.

AI Supervisor

What resolve mode does, when it intervenes, and how escalation lands in your inbox.

Connect

Concepts

Reference

That’s the integration

Threads and lifecycle

AI Supervisor

​That’s the integration

Threads and lifecycle

AI Supervisor

That’s the integration