Start a direct conversation
Workforce module
POST/conversations/start-directconversations.startDirect
Opens, or returns, the one-to-one conversation with another active member of the org. Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.
- Requires the capability inbox.notifications.write.
- OAuth scopes: inbox.
- Send an Idempotency-Key header. A replay with the same key returns the original response.
- Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.
Request body: DirectConversationRequest
| Field | Type | Required | Description |
|---|---|---|---|
| other_membership_id | string (uuid) | Yes | The other member. |
{
"other_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}Response 200: Conversation
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | Identifier of the conversation. |
| org_id | string (uuid) | Yes | Identifier of the owning organization, derived from the parent row and never accepted from the caller. |
| created_at | string (date-time) | Yes | When the row was created. |
| created_by | string (uuid) | null | Yes | Person who created the row; null for seed, platform or system writes. |
| updated_at | string (date-time) | Yes | When the row was last updated. |
| updated_by | string (uuid) | null | Yes | Person who last updated the row; null for seed, platform or system writes. |
| conversation_kind | "Direct" | "Group" | Yes | Direct or Group. |
| group_id | string (uuid) | null | Yes | Identifier of the group whose conversation this is. |
| direct_key | string | null | Yes | The two membership ids of a Direct conversation, sorted and joined by a colon.Constraints: length 1 to 80 |
| last_message_at | string (date-time) | null | Yes | When the latest message was sent. |
{
"id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"created_at": "2026-10-08T14:30:00Z",
"created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"updated_at": "2026-10-08T14:30:00Z",
"updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"conversation_kind": "Direct",
"group_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
"direct_key": "a:b",
"last_message_at": "2026-10-08T14:30:00Z"
}Code samples
curl -X POST "$XOS_BASE_URL/conversations/start-direct" \
-H "Authorization: Bearer $XOS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"other_membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'const { data } = await xos.conversations.startDirect({
"other_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
});response = xos.conversations.start_direct({"other_membership_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"})xos conversations start-direct --data '{"other_membership_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'