> ## Documentation Index
> Fetch the complete documentation index at: https://developers.workchats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Objects

> The shape of every object the API returns

## User

```json theme={null}
{
  "id": "usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "Connor Berwick",
  "display_name": "Connor",
  "email": "connor@corpwise.ae",
  "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 |

Phone numbers are never included.

## Conversation

```json theme={null}
{
  "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)

```json theme={null}
{
  "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 | |

Returned by `POST /v1/messages` and `PATCH /v1/messages/{id}`.

## Message (history)

```json theme={null}
{
  "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 | |

Returned by `GET /v1/conversations/{conversation_id}/messages`, newest
first, paginated the same way as [Pagination](/guides/pagination) describes.
Needs `conversations:history`.

## File

```json theme={null}
{
  "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 |

Returned by `GET /v1/conversations/{conversation_id}/files/{id}`. Needs
`files:read`.

## Workspace

```json theme={null}
{ "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

```json theme={null}
{ "ok": false, "error": { "code": "token_revoked", "message": "The token has been revoked." }, "request_id": "F7p0mJcXk3tq2x0AAAAB" }
```

See [Error codes](/reference/error-codes) for every `code`.