User
{
"id": "usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d",
"name": "Connor Berwick",
"display_name": "Connor",
"email": "[email protected]",
"avatar_url": "https://cdn.workchats.com/a/9a1d2c3e.png",
"title": "Sales",
"timezone": "Asia/Dubai",
"is_active": true,
"is_bot": false,
"is_admin": false,
"is_external": false
}
| Field | Type | Notes |
|---|---|---|
id | string | usr_ prefixed |
name | string | Full name |
display_name | string, nullable | First name |
email | string | Present only with users:read.email, and only when the person allows it. Absent, not null, when withheld |
avatar_url | string, nullable | |
title | string, nullable | Job title |
timezone | string, nullable | IANA timezone |
is_active | boolean | false for deactivated and removed people, who stay listed |
is_bot | boolean | Always false — bots are never listed |
is_admin | boolean | A company admin |
is_external | boolean | A guest from outside the company |
Conversation
{
"id": "chn_c41a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"name": "sales-alerts",
"type": "private_channel",
"parent_id": "grp_6b0a1b2c-3d4e-4f50-8a6b-7c8d9e0f1a2b",
"is_private": true,
"is_archived": false,
"is_member": true,
"member_count": 9,
"topic": null
}
| Field | Type | Notes |
|---|---|---|
id | string | grp_ for a group, chn_ for a named channel |
name | string | |
type | "channel" | "private_channel" | channel when the whole company may join |
parent_id | string, nullable | A channel’s group id (grp_); null for a group itself |
is_private | boolean | |
is_archived | boolean | |
is_member | true | Always true — only conversations your bot belongs to are ever returned |
member_count | integer | People with an active account; bots are never counted |
topic | string, nullable | The group’s or channel’s description |
Message (send response)
{
"id": "dmsg_4e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"conversation_id": "dm_77a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",
"thread_id": null,
"created_at": "2026-09-28T11:05:12Z"
}
| Field | Type | Notes |
|---|---|---|
id | string | gmsg_ in a group or channel, dmsg_ in a direct message |
conversation_id | string | grp_ / chn_ for a group or channel, dm_ for a direct message |
thread_id | string, nullable | The message this one quote-replies to |
created_at | string, RFC 3339 |
POST /v1/messages and PATCH /v1/messages/{id}.
Message (history)
{
"id": "gmsg_9b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"conversation_id": "grp_6b0c1d2e-3f40-4a5b-8c6d-7e8f9a0b1c2d",
"thread_id": null,
"user_id": "usr_9a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d",
"type": "file",
"text": "The signed contract",
"files": [{ "id": "fil_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" }],
"created_at": "2026-09-28T11:05:12Z"
}
| Field | Type | Notes |
|---|---|---|
id | string | gmsg_ prefixed |
conversation_id | string | grp_ or chn_ prefixed |
thread_id | string, nullable | The message this one replies to, gmsg_ prefixed. null unless your bot can read that message in this same conversation |
user_id | string, nullable | The sender. null for a system message, and for a guest your bot may not see |
type | string | "text", "image", "file", "system", "audio", "video", "location", "contact", "call", "poll", or "survey". system is a notice such as someone joining |
text | string, nullable | null for a system message |
files | array of {id} | Attached file ids; fetch details with files:read |
created_at | string, RFC 3339 |
GET /v1/conversations/{conversation_id}/messages, newest
first, paginated the same way as Pagination describes.
Needs conversations:history.
File
{
"id": "fil_1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "contract-signed.pdf",
"mimetype": "application/pdf",
"size": 482113,
"url": "https://cdn.workchats.com/f/1a2b3c4d.pdf?sig=…"
}
| Field | Type | Notes |
|---|---|---|
id | string | fil_ prefixed |
name | string | The file name it was uploaded with |
mimetype | string | |
size | integer | Bytes |
url | string | Signed, needs no token, usable for 15 minutes; redirects to a download good for up to an hour after that. Treat it and the download as secrets while they last |
GET /v1/conversations/{conversation_id}/files/{id}. Needs
files:read.
Workspace
{ "id": "cmp_3f0c1b9e-5d0a-4a57-9a53-2f4f1c9d6b10", "name": "Corpwise", "domain": "corpwise.ae" }
| Field | Type | Notes |
|---|---|---|
id | string | cmp_ prefixed |
name | string | |
domain | string, nullable | The company’s email domain, null when it has none. Only present on GET /v1/auth/test |
Error
{ "ok": false, "error": { "code": "token_revoked", "message": "The token has been revoked." }, "request_id": "F7p0mJcXk3tq2x0AAAAB" }
code.