> ## Documentation Index
> Fetch the complete documentation index at: https://help.texterchat.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The Chat object
> A conversation with a contact on a connected channel
chat represents one conversation with one contact on one channel account. Chats are returned by [Search Chats](/he/api-reference/chats/search-chats), [Get Chat by Chat ID](/he/api-reference/chats/get-chat-by-chat-id) (trimmed public view), chat-management endpoints, and inside every chat-related webhook payload.
**Time units differ by field naming:** fields ending in `Timestamp` / `_timestamp` are epoch **milliseconds**; fields ending in `UpdateTime` / `MessageTime` (and `replyAction.created`) are epoch **seconds**; `created`, `updatedAt` and `unsubscribed.date` are ISO date-time strings.
Returned by: [Search Chats](/he/api-reference/chats/search-chats) · [Get Chat by Chat ID](/he/api-reference/chats/get-chat-by-chat-id) · [Update Chat Properties](/he/api-reference/chats/update-chat-properties) · [Update CRM Data](/he/api-reference/chats/update-crm-data) · [Webhook events](/he/api-reference/webhooks-guide)
```json Example chat object [expandable] theme={null}
{
"_id": "67bf11038b24880cc966f799",
"title": "John Doe",
"displayName": "John from the gym",
"channelInfo": {
"name": "whatsapp",
"id": "972521234567",
"accountId": "972509876543"
},
"agent": {
"uid": "4d170fc7-5cd6-4496-98e4-f4f03a11456e",
"displayName": "Tyler"
},
"departmentId": "customer_service",
"status": 2,
"unreadCount": 0,
"labels": [
"VIP"
],
"lastMessage": {
"type": "text",
"text": "תודה!"
},
"last_message_timestamp": 1762012091000,
"lastIncomingMessageTimestamp": 1762012091000,
"created": "2025-02-26T13:02:58.353Z",
"updatedAt": "2025-11-01T15:48:14.076Z",
"pendingUpdateTime": 1756292160,
"resolvedUpdateTime": 1762012093,
"botState": {
"id": "99f3e9b18b6ae02781db30fb5fb673639d7007210a3280e87b754c44c3e6222c",
"flowVersion": {
"identifier": "onboarding-bot",
"version": 37
},
"node": "handoff",
"userState": {
"menu_choice": {
"choice": 2,
"text": "נציג אנושי"
}
}
},
"crmData": {
"leadId": 641225,
"plan": "premium"
},
"crmDeepLink": "https://app.yourcrm.com/leads/641225",
"externalBot": false
}
```
## Identity & contact
| Field | Type | Description |
| ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | `string` | Unique identifier of the chat in Texter. Use it in every chat-scoped endpoint |
| `title` | `string` | Contact's name as set in their WhatsApp account settings |
| `displayName` | `string` | Custom name modified in Texter. Absent if never modified. Update via [Update Chat Properties](/he/api-reference/chats/update-chat-properties) |
| `personId` | `string` | ID of the person that owns this chat - links chats of the same person across channels |
| `image` | `string` | File ID of the chat's avatar image, when available |
| `labels` | `string[]` | Label IDs applied to the chat. Manage via [Manage Labels in Chat](/he/api-reference/labels/manage-labels-in-chat) Example: `["urgent","billing"]` |
| `personChats` | `object[]` | All chats of the same person (including this one) as channel references (`{name, accountId, id}`). Present in **webhook event payloads**; not included in REST search results |
## Channel
| Field | Type | Description |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `channelInfo.name` | `string` | Channel type: `whatsapp`, `messenger`, `instagram`, `website_chat`, `email`, `sms` |
| `channelInfo.accountId` | `string` | The business account connected to Texter. For WhatsApp, the business phone number Example: `972586640430` |
| `channelInfo.id` | `string` | The contact's ID on the channel. For WhatsApp, the contact's phone number Example: `972521234567` |
| `channelInfo.metadata` | `object` | Channel-specific metadata, when present |
## Status & routing
| Field | Type | Description | |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `status` | `number` | Current state: `0` BOT, `1` PENDING, `2` ASSIGNED (shown as "Taken" in Texter), `3` RESOLVED, `4` BULK | |
| `agent.uid` | \`string | null\` | Internal Texter user ID of the assigned agent |
| `agent.displayName` | \`string | null\` | Name of the assigned agent |
| `departmentId` | \`string | null\` | Department responsible for the chat |
| `unreadCount` | `number` | Number of unread incoming messages | |
| `pendingUpdateTime` | `number` | When the chat last entered pending status (epoch **seconds**) | |
| `resolvedUpdateTime` | `number` | When the chat was last marked RESOLVED (epoch **seconds**) | |
| `pendingMessageTime` | \`number | null\` | When the bot last sent a pending-reminder while the chat waits for an agent (epoch **seconds**). Reset to null on resolve |
| `blockedChat.blocked` | `boolean` | Whether the chat is marked as blocked | |
| `blockedChat.agent` | `string` | ID of the agent who blocked the chat | |
| `hasMessageError` | `boolean` | Whether the chat contains failed outgoing messages | |
## Last message
| Field | Type | Description |
| ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------- |
| `lastMessage.type` | `string` | Type of the last message (`text`, `media`, `special`...). Not included in Search Chats results |
| `lastMessage.text` | `string` | Text content of the last message, if applicable |
| `lastMessage.media` | `object[]` | Media items of the last message - see [Media item](/he/api-reference/objects/message#media-items) |
| `last_message_timestamp` | `number` | When the last message was sent or received (epoch **milliseconds**) |
| `lastIncomingMessageTimestamp` | `number` | When the last incoming (contact) message arrived (epoch **milliseconds**) |
## Bot session
`botState` holds the active or most recent bot session; `previousBotSession` holds the one before it (same shape). Both can be `null`, and may carry additional bot-specific keys.
| Field | Type | Description | |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `botState.id` | `string` | Bot session ID - use as `botSessionId` in [Get Messages of a Chat](/he/api-reference/messages/get-messages-of-a-chat) | |
| `botState.flowVersion.identifier` | `string` | Identifier of the bot Example: `onboarding-bot` | |
| `botState.flowVersion.version` | `number` | Version number of the bot flow | |
| `botState.node` | `string` | Current or last bot node | |
| `botState.userState` | `object` | Key-value memory of answers collected at each bot node | |
| `botState.store` | `object` | Key-value memory of variables collected during the session | |
| `botState.latestAgentUid` | \`string | null\` | ID of the last human agent involved in the session |
| `botState.latestAgentName` | \`string | null\` | Display name of the last human agent involved |
| `externalBot` | `boolean` | Whether an external bot (outside Texter) is active for this chat. Toggling it fires the [External Bot Enabled](/he/api-reference/webhooks/chat-events/external-bot-enabled) / [Disabled](/he/api-reference/webhooks/chat-events/external-bot-disabled) events | |
## Reply action
The pending action that runs when the contact replies to a template message. `null` when no reply action is armed. Set by template defaults or the [Send Template Message](/he/api-reference/manage-templates/send-template-message) `replyAction` parameter.
| Field | Type | Description |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `replyAction.created` | `number` | When the reply action was set (epoch **seconds**) |
| `replyAction.expirationTime` | `number` | How long the action remains valid, in seconds relative to `created` Example: `259200` |
| `replyAction.chatStatus` | `number` | Status to apply when the contact replies (`0` BOT / `2` ASSIGNED / `3` RESOLVED) |
| `replyAction.setBotNode` | `string` | Bot node to trigger after reply |
| `replyAction.bot` | `string` | Specific bot to run after reply |
| `replyAction.replyText` | `string` | Text automatically sent after the contact replies |
| `replyAction.responsibleAgent` | `string` | Agent the chat is assigned to after the reply |
| `replyAction.responsibleDepartment` | `string` | Department the chat is assigned to after the reply |
| `replyAction.replyToTemplateFile` | `object` | File (`{url, name}`) automatically sent after the contact replies |
| ~~`replyAction.status`~~ | `number` | **Deprecated** - Use `chatStatus` instead |
## Template subscription & bulk
| Field | Type | Description |
| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `unsubscribed.date` | `string` | When the chat unsubscribed from template messages (ISO date-time). The whole `unsubscribed` object is present only after an opt-out |
| `unsubscribed.bulkSendId` | `string` | Latest bulk send this contact was included in before unsubscribing |
| `sendingBulkAgent` | `string` | ID of the agent who initiated the bulk template message |
| `latestBulkSendId` | `string` | ID of the latest bulk send performed in this chat. Its presence does **not** mean the chat is currently in BULK status |
## CRM
| Field | Type | Description | |
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `crmData` | `object` | Custom CRM metadata; structure varies by integration. Merge via [Update CRM Data](/he/api-reference/chats/update-crm-data) | |
| `crmDeepLink` | `string` | Personalized link to the contact's record in your CRM, shown to agents in Texter | |
| `crmLastTicketId` | \`string | number\` | Reference to the most recent CRM record linked to the chat |
| `lastMessageStoredInCRMTimestamp` | `number` | When the last message was stored in CRM (epoch **milliseconds**) | |
## Lifecycle
| Field | Type | Description |
| ----------- | -------- | ---------------------------------------------------------------- |
| `created` | `string` | When the chat was created (ISO date-time) |
| `updatedAt` | `string` | Last time the chat was updated (ISO date-time) |
| `language` | `string` | The chat's preferred language. Reserved for future functionality |
## Deprecated fields
These may still appear in responses but should not be used in new code.
| Field | Type | Description |
| --------------------- | --------- | ------------------------------------------------------------------ |
| ~~`channel`~~ | `string` | **Deprecated** - Use `channelInfo.name` instead |
| ~~`clientPhone`~~ | `string` | **Deprecated** - Use `channelInfo.id` instead |
| ~~`clientPhoneE164`~~ | `string` | **Deprecated** - Use `channelInfo.id` instead |
| ~~`entityPhone`~~ | `string` | **Deprecated** - Use `channelInfo.accountId` instead |
| ~~`lastText`~~ | `string` | **Deprecated** - Use `lastMessage.text` instead |
| ~~`unsubscribeTime`~~ | `number` | **Deprecated** - Epoch seconds. Use `unsubscribed.date` instead |
| ~~`blockTemplates`~~ | `boolean` | **Deprecated** - Use the `unsubscribed` property instead |
| ~~`firestoreId`~~ | `string` | **Deprecated** - Pre-migration legacy ID on very old chats. Ignore |
**Get Chat by ID returns a trimmed view.** [Get Chat by Chat ID](/he/api-reference/chats/get-chat-by-chat-id) returns only the public subset of these fields (no `_id`, `labels`, `crmData` or `displayName`; `botState` narrowed to its `id`) plus `lastMessageTimestamp` (milliseconds). Use [Search Chats](/he/api-reference/chats/search-chats) for the complete record.
## Chat status values
Used by `status`, template `chatStatus`, `replyAction.chatStatus` and `newChatStatus` on system messages. The `statuses[]` filter of [Search Chats](/he/api-reference/chats/search-chats) takes the **names**, not the numbers.
| Value | Name | Meaning |
| ----- | ---------- | ---------------------------------------------- |
| `0` | `BOT` | Handled by the bot |
| `1` | `PENDING` | Waiting for a human agent |
| `2` | `ASSIGNED` | Taken by an agent (shown as "Taken" in Texter) |
| `3` | `RESOLVED` | Conversation finished |
| `4` | `BULK` | Created/affected by a bulk send |
More enums and the ID cheat sheet: [Enums & Common Fields](/he/api-reference/enums).