> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect quickstart

> Ship customer–merchant–courier chat in your app in about fifteen minutes: create a thread per order, add the courier, drop in the UI, let order status drive the rest.

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](/api-reference/authentication).

```mermaid theme={"dark"}
sequenceDiagram
  autonumber
  participant You as Your backend
  participant CX as OpenCX
  You->>CX: POST /connect/threads (order confirmed)
  CX-->>You: thread th_9f2c4e · customer↔merchant lane open
  You->>CX: POST /threads/th_9f2c4e/participants (courier assigned)
  CX-->>You: customer↔courier lane open
  Note over CX: Participants chat · AI answers, translates, nudges
  You->>CX: PATCH /threads/th_9f2c4e { order_status: "delivered" }
  CX-->>You: thread locks itself after the grace window
```

<Steps>
  <Step title="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.

    ```bash theme={"dark"}
    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" }
      }'
    ```

    ```json theme={"dark"}
    {
      "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.

    <Tip>
      Notice `language` per participant. Fatima writes Arabic, the merchant reads English, and neither ever notices — the Supervisor translates both directions live.
    </Tip>
  </Step>

  <Step title="Add the courier when you assign one">
    ```bash theme={"dark"}
    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](/api-reference/connect/remove-participant) and add the new one — the lane's history stays with the thread, the old courier loses access instantly.
  </Step>

  <Step title="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.

    ```bash theme={"dark"}
    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" }'
    ```

    ```tsx theme={"dark"}
    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](/widget/configuration).

    Building your own UI? Skip the component and go headless: [send messages](/api-reference/connect/send-message) server-side and receive them via [webhooks](/connect/webhooks) or the token-scoped WebSocket.
  </Step>

  <Step title="Let order status drive the lifecycle">
    Tell Connect what the order is doing; it handles what that means for the conversation.

    ```bash theme={"dark"}
    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](/connect/threads).
  </Step>

  <Step title="Tune the Supervisor — or don't">
    Every thread already has the AI Supervisor in `resolve` mode: it answers order questions from your [Actions](/actions/introduction), 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:

    ```bash theme={"dark"}
    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](/connect/ai-supervisor).
  </Step>
</Steps>

## 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.

<CardGroup cols={2}>
  <Card title="Threads and lifecycle" icon="layer-group" href="/connect/threads">
    Lanes, roles, visibility, the order-driven state machine, retention.
  </Card>

  <Card title="AI Supervisor" icon="shield-halved" href="/connect/ai-supervisor">
    What resolve mode does, when it intervenes, and how escalation lands in your inbox.
  </Card>
</CardGroup>