Chats & Sessions

Overview

Read conversations and their message history, manage the agent session attached to a chat, assign a chat to a teammate, and escalate to a human when automation has gone as far as it usefully can.

8 endpoints. Requires chats.view or chats.assign on the token.

Method	Path	What it does
GET	/chats	List chats
GET	/chats/{id}	Get chat details
POST	/chats/{id}/assign	Assign or unassign a chat
POST	/chats/{id}/de-escalate	Clear escalation from a chat
POST	/chats/{id}/escalate	Escalate a chat to human agent
GET	/chats/{id}/messages	Get chat message history
GET	/chats/session	Get active session
POST	/chats/session	Manage session

Endpoints

GET /chats

List chats

List chats with rich filtering options including escalation status, assigned agent, and channel type. Requires `chats.view` permission.

Requires the chats.view permission.

Parameter	In	Type	Required	Description
waId	query	string	optional	Filter by contact WhatsApp ID (phone number)
contactId	query	string	optional	Filter by contact ID
channelId	query	string	optional	Filter by OrgChannel ID
channel	query	WHATSAPP · INSTAGRAM	optional	Filter by channel type
needsEscalation	query	true · false	optional	Filter by escalation status
assigneeId	query	string	optional	Filter by assigned agent ID
page	query	integer	optional	Page number Defaults to 1.
limit	query	integer	optional	Items per page (max 100) Defaults to 20.

Example

curl -X GET "https://orqestra.id/api/v2/chats" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

GET /chats/{id}

Get chat details

Get full chat details including escalation status, active session info, and contact details. Requires `chats.view` permission.

Requires the chats.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Chat ID (cuid)

Example

curl -X GET "https://orqestra.id/api/v2/chats/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →

---

POST /chats/{id}/assign

Assign or unassign a chat

Assign a chat to an agent, or unassign by passing `agentId: null`. Requires `chats.assign` permission.

Requires the chats.assign permission.

Parameter	In	Type	Required	Description
id	path	string	required	Chat ID (cuid)

Request body

Field	Type	Required	Description
agentId	string	required	Agent user ID to assign, or null to unassign

Example

curl -X POST "https://orqestra.id/api/v2/chats/$id/assign" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "cl9x..."
  }'

Responds with 200 · 400 · 401 · 403 · 404. Try it in the playground →

---

POST /chats/{id}/de-escalate

Clear escalation from a chat

Remove the escalation flag from a chat. Requires `chats.assign` permission.

Requires the chats.assign permission.

Parameter	In	Type	Required	Description
id	path	string	required	Chat ID (cuid)

Request body

Field	Type	Required	Description
reason	string	optional	Optional reason for clearing escalation

Example

curl -X POST "https://orqestra.id/api/v2/chats/$id/de-escalate" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403 · 404. Try it in the playground →

---

POST /chats/{id}/escalate

Escalate a chat to human agent

Flag a chat for agent escalation. Ends any active AI/flow session and triggers auto-assignment rules. Requires `chats.assign` permission.

Requires the chats.assign permission.

Parameter	In	Type	Required	Description
id	path	string	required	Chat ID (cuid)

Request body

Field	Type	Required	Description
reason	string	optional	Optional escalation reason shown to agents

Example

curl -X POST "https://orqestra.id/api/v2/chats/$id/escalate" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403 · 404 · 429. Try it in the playground →

---

GET /chats/{id}/messages

Get chat message history

Retrieve paginated message history using cursor-based pagination. Returns newest first. Requires `chats.view` permission.

Requires the chats.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Chat ID (cuid)
take	query	integer	optional	Number of messages to return (max 100) Defaults to 50.
cursor	query	string	optional	Message ID to paginate from (exclusive)

Example

curl -X GET "https://orqestra.id/api/v2/chats/$id/messages" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403 · 404. Try it in the playground →

---

GET /chats/session

Get active session

Check if a contact has an active chat session. Identify the contact by `contactId`, `waId`, or `igId`. Optionally scope lookup to a specific channel via `channelId`.

Requires the chats.view permission.

Parameter	In	Type	Required	Description
waId	query	string	optional	Contact WhatsApp ID (phone number)
igId	query	string	optional	Contact Instagram ID
contactId	query	string	optional	Contact ID (alternative to waId/igId)
channelId	query	string	optional	OrgChannel ID to scope the chat lookup

Example

curl -X GET "https://orqestra.id/api/v2/chats/session" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 404. Try it in the playground →

---

POST /chats/session

Manage session

Start, take over, or end a chat session. Identify contact by `contactId`, `waId`, or `igId`. Optionally scope to a specific channel via `channelId`. Consumes session credits.

Requires the chats.assign permission.

Request body

Field	Type	Required	Description
waId	string	optional	Contact WhatsApp ID (phone number)
igId	string	optional	Contact Instagram ID
contactId	string	optional	Contact ID (alternative to waId/igId)
channelId	string	optional	OrgChannel ID to scope the chat lookup
agentId	string	optional	Agent ID (required for START and TAKEOVER)
action	START · TAKEOVER · END	optional	Session action Defaults to "START".

Example

curl -X POST "https://orqestra.id/api/v2/chats/session" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403 · 404 · 409. Try it in the playground →