The Chat object

chat represents one conversation with one contact on one channel account. Chats are returned by Search 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 · Get Chat by Chat ID · Update Chat Properties · Update CRM Data · Webhook events

Example chat object

{
  "_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
`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 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
`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
`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 / 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 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
`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.

Show deprecated fields

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 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 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 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.

Getting Started

Endpoints

Webhooks

Objects

Identity & contact

Channel

Status & routing

Last message

Bot session

Reply action

Template subscription & bulk

CRM

Lifecycle

Deprecated fields

Chat status values

​Identity & contact

​Channel

​Status & routing

​Last message

​Bot session

​Reply action

​Template subscription & bulk

​CRM

​Lifecycle

​Deprecated fields

​Chat status values

Identity & contact

Channel

Status & routing

Last message

Bot session

Reply action

Template subscription & bulk

CRM

Lifecycle

Deprecated fields

Chat status values