Skip to main content
POST
Assign a conversation

Authorizations

Authorization
string
header
required

Use a workspace API key in the Authorization header. Keys use pk_live_<key_id> for production and pk_test<key_id>_ for test mode.

Headers

Idempotency-Key
string

Optional retry key for safely replaying create requests. Reusing the same key with a different request body returns 409.

Required string length: 8 - 255
Example:

"8db8e596-7c1a-4fd5-a728-4d6c99f4e66b"

Path Parameters

conversationId
string
required
Example:

"conv_x6q5vl75f5d53m7oet2k4r5w6a"

Body

application/json

Requires assignee or team. Send an assignee with an empty id, or an empty team string, to clear that field.

assignee
object

Who the conversation is assigned to. Set id to an empty string to clear the assignment.

team
string

External team or routing hint.

Example:

"canggu-rentals"

Response

Assigned conversation.

Every key is always present; optional fields are null when unset.

id
string
required
Example:

"conv_x6q5vl75f5d53m7oet2k4r5w6a"

externalId
string | null
required
Example:

"inquiry_123"

subject
string
required
Example:

"Inquiry for 2BR Villa in Canggu"

status
string
required

Workspace-defined status key. Every workspace is seeded with open, pending, resolved, and closed; workspaces can define their own. Use GET /v1/statuses to list the keys valid for your workspace. Unknown keys are rejected with conversations.unknown_status.

Pattern: ^[a-z0-9][a-z0-9_-]{0,62}$
Example:

"open"

priority
string
required

Workspace-defined priority key. Every workspace is seeded with low, normal, high, and urgent; workspaces can define their own. Use GET /v1/priorities to list the keys valid for your workspace. Unknown keys are rejected with conversations.unknown_priority.

Pattern: ^[a-z0-9][a-z0-9_-]{0,62}$
Example:

"normal"

channel
string
required
Example:

"whatsapp"

customerId
string
required
Example:

"cus_x6q5vl75f5d53m7oet2k4r5w6a"

assignee
object | null
required

Null when the conversation is unassigned.

team
string | null
required
Example:

"canggu-rentals"

tags
string[]
required
externalObject
object | null
required

Null when no external object is attached.

metadata
object
required
channelIdentityId
string | null
required

The channel identity that opened this conversation, if any.

Example:

"cid_x6q5vl75f5d53m7oet2k4r5w6a"

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
routingNotes
object | null

Routing hints and resolution reasons recorded at create time (debugging).