Create a Connect thread

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",
  "participants": [
    { "id": "prt_c81", "role": "customer", "external_id": "cus_991",
      "display_name": "Fatima", "language": "ar" },
    { "id": "prt_m32", "role": "merchant", "external_id": "mrc_204",
      "display_name": "Shawarma House", "language": "en" }
  ],
  "lanes": [
    { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
    { "id": "customer_courier", "status": "waiting", "supervisor_mode": "resolve" }
  ],
  "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" },
  "created_at": "2026-07-30T14:03:11Z"
}

POST

connect

threads

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",
  "participants": [
    { "id": "prt_c81", "role": "customer", "external_id": "cus_991",
      "display_name": "Fatima", "language": "ar" },
    { "id": "prt_m32", "role": "merchant", "external_id": "mrc_204",
      "display_name": "Shawarma House", "language": "en" }
  ],
  "lanes": [
    { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
    { "id": "customer_courier", "status": "waiting", "supervisor_mode": "resolve" }
  ],
  "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" },
  "created_at": "2026-07-30T14:03:11Z"
}

Create the conversation for an order. Call it when the order is confirmed — the customer_merchant lane opens immediately; the customer_courier lane waits for a courier.

Request

string

required

Your order ID. Unique per organization and the idempotency key: posting an existing reference returns the existing thread with 200.

array

required

Initial participants. Usually the customer and merchant; couriers are added later.

Show participant

string

required

customer, merchant, or courier.

string

required

Your ID for this person or store. Also accepts an OpenCX contact_id for customers already known to your workspace.

string

required

Name shown to the other participants. Never expose contact details here.

string

BCP-47 code (ar, en, hi…). The Supervisor renders every message in this language for this participant. Defaults to your org’s primary language.

array

Lanes to enable. Defaults to ["customer_merchant", "customer_courier"]; include "merchant_courier" to open the third lane.

object

Override the org-default Supervisor config for this thread.

Show supervisor

string

observe, assist, or resolve (org default applies when omitted).

object

Per-lane overrides: { "customer_courier": { "mode": "assist", "nudge_after_seconds": 300 } }.

object

Override org defaults: wrap_up_hours (default 24), retention_days (days after locking before the thread is archived; not set by default, so a locked thread stays locked until you set it). Archiving never deletes thread history.

object

Arbitrary JSON stored on the thread and surfaced to the Supervisor as answering context — order total, vertical, promo flags.

Response

string

Thread ID (th_…).

string

Your order ID.

string

open on creation. Lifecycle: open → wrap_up → locked → archived.

string

Starts at confirmed; you drive it via Update thread.

array

Participants with server-assigned id (prt_…) alongside your external_id.

array

Lane objects: id, status (active | waiting | closed), supervisor_mode.

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",
  "participants": [
    { "id": "prt_c81", "role": "customer", "external_id": "cus_991",
      "display_name": "Fatima", "language": "ar" },
    { "id": "prt_m32", "role": "merchant", "external_id": "mrc_204",
      "display_name": "Shawarma House", "language": "en" }
  ],
  "lanes": [
    { "id": "customer_merchant", "status": "active", "supervisor_mode": "resolve" },
    { "id": "customer_courier", "status": "waiting", "supervisor_mode": "resolve" }
  ],
  "custom_data": { "vertical": "food", "total": 86.5, "currency": "QAR" },
  "created_at": "2026-07-30T14:03:11Z"
}

​Request

​Response

Request

Response