Create a conversation
const url = 'https://chat.centralcodestation.com/api/v1/tenants/example/applications/example/conversations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"type":"DIRECT","member_user_ids":["coach-ana","client-john"],"actor_user_id":"coach-ana"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://chat.centralcodestation.com/api/v1/tenants/example/applications/example/conversations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "type": "DIRECT", "member_user_ids": [ "coach-ana", "client-john" ], "actor_user_id": "coach-ana" }'Needs conversations.create (+ groups.create / channels.create). DIRECT dedupes on its two members. Every member must be an eligible member of the tenant and application (422 target_user_not_eligible).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The Identity Server tenant id.
The Identity Server id of a chat-enabled tenant application.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Required for GROUP and CHANNEL.
CHANNEL only; default PUBLIC.
Users: the other members (the caller is always added). Machines: required, every member. DIRECT = exactly 2 members in total.
Machines only: the tenant user recorded as creator (and GROUP/CHANNEL OWNER). Ignored for users.
Example
{ "type": "DIRECT", "member_user_ids": [ "coach-ana", "client-john" ], "actor_user_id": "coach-ana"}Responses
Section titled “Responses”The conversation. For a DIRECT conversation that already exists, the existing one.
object
The Identity Server tenant id.
The Identity Server application id (the context).
CHANNEL only.
ARCHIVED is read-only.
Set when a machine client created it.
On list/get: ACTIVE members for DIRECT/GROUP (bounded), omitted for CHANNEL.
object
Falls back to the user id when Chat has no profile.
The caller’s membership role (users only).
Users only.
Example
{ "conversation_id": "6b1f4c7e-3c52-4a0a-9a39-7d2e2f1f8a10", "tenant_id": "fitness", "application_id": "fitness-app", "type": "DIRECT", "visibility": null, "name": null, "description": null, "status": "ACTIVE", "created_by_user_id": null, "created_by_client_id": "2f1c9e5a-7f4d-4f0e-8c35-9b1a3d6e4c21", "last_activity_at": "2026-10-14T09:30:00.000Z", "created_at": "2026-10-14T09:00:00.000Z", "updated_at": "2026-10-14T09:30:00.000Z", "members": [ { "user_id": "coach-ana", "display_name": "Ana Coach", "avatar_url": null }, { "user_id": "client-john", "display_name": "John Client", "avatar_url": null } ], "member_count": 2, "my_role": "MEMBER", "has_unread": true}Error. error is one of: invalid_request.
object
Stable snake_case error code.
Example
{ "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: invalid_token, token_revoked.
object
Stable snake_case error code.
Example
{ "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, has the wrong audience (`aud` must be `chat-api`), or lacks the required scope.", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: not_tenant_member, no_application_access, tenant_not_available, insufficient_scope, client_context_mismatch, missing_capability.
object
Stable snake_case error code.
Example
{ "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: application_not_found.
object
Stable snake_case error code.
Example
{ "status_code": 404, "error": "application_not_found", "message": "The application does not exist in the tenant, or Chat is not enabled for it.", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: target_user_not_eligible.
object
Stable snake_case error code.
Example
{ "status_code": 422, "error": "target_user_not_eligible", "message": "A user you referenced (member, actor) is not an active member of the tenant with access to the application.", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: rate_limited.
object
Stable snake_case error code.
Example
{ "status_code": 429, "error": "rate_limited", "message": "The caller exceeded a rate limit", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}Error. error is one of: identity_unavailable.
object
Stable snake_case error code.
Example
{ "status_code": 503, "error": "identity_unavailable", "message": "Chat could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations", "timestamp": "2026-10-14T09:30:00.000Z"}default
Section titled “default”Error — see error for the code.
object
Stable snake_case error code.
Example
{ "status_code": 403, "error": "invalid_request", "message": "Missing Chat capability messages.send", "path": "/api/v1/tenants/t1/applications/a1/conversations"}