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 (default 30).

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"
}

Overview Get thread

Overview

Blocklist

Autopilot

Organization

Contacts

Sessions

Connect

AI Phone Agents

AI Email

AI WhatsApp

AI Actions

AI Outbound Sequencing

Media

AI Training

Resource Usage

Customer Insights

Teams

CSAT

Redaction

Crawl

Tags

Office Hours

Handoff Analytics

SLA Analytics

Workflows (Beta)

Salesforce MIAW

Webhooks

Create a Connect thread

Request

Response

​Request

​Response

Request

Response