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"
}
Connect
Create a Connect thread
Create an order-scoped thread with its initial participants. Idempotent on reference, so call it from your order pipeline without duplicate-guarding.
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
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.
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"
}
Was this page helpful?