> ## 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. # Update Chat Properties > Modify attributes of a chat. Most commonly used to change a contact's display name in Texter or to enable/disable an external bot for the chat. **Required token scopes:** `Manage all chats` Note that updating properties **fully overrides** existing values. For example, if a `crmData` object already exists, it is fully replaced by the new object provided in the request. To **merge** CRM data instead, use **Update CRM Data**. ## OpenAPI ````yaml api-reference/openapi.json PATCH /chats/{chatId} openapi: 3.1.0 info: title: Texter API V2 version: 2.0.0 description: >- The **Texter API** lets your developers control the Texter platform programmatically: - Manage and send your WhatsApp template messages - Retrieve chats by ID or by various filters - Assign and resolve conversations - Send session messages into active chats - Manage labels - Monitor and resolve channel health issues - Subscribe to real-time webhook events - Manage quick replies (coming soon) For any questions please contact [Texter Support](https://wa.me/972586640430). contact: name: Texter Support url: https://wa.me/972586640430 servers: - url: https://{projectID}.texterchat.com/server/api/v2 description: Your Texter environment. Replace projectID with your project subdomain variables: projectID: default: demo description: >- Your unique project subdomain. If your environment URL is https://demo.texterchat.com, your projectID is "demo" security: - bearerAuth: [] tags: - name: Manage Templates description: >- Create, localize, submit, update, delete and send WhatsApp template messages, and retrieve approved templates for your connected WhatsApp accounts. **Suggested token for this group** - create one API token with the scopes: *Send template messages*, *View template messages*, *Manage WhatsApp templates*, *Manage all chats*, *List all chats* (the last two also cover the Templates Subscriptions group). Each endpoint below also lists the exact scopes it needs. - name: Templates Subscriptions description: >- Manage recipient subscriptions for WhatsApp template messages - unsubscribe or resubscribe recipients, and list unsubscribed users across all channels or for a specific account. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*. Each endpoint below also lists the exact scopes it needs. - name: Messages description: >- Retrieve message history from a chat, or send new session messages - text, media, buttons, lists, contact cards and locations - within the active WhatsApp 24-hour session window. **Suggested token for this group** - scopes: *Send session message*, *View all chats*. Each endpoint below also lists the exact scopes it needs. - name: Chats description: >- Fetch chat details, search conversations, update chat properties, assign or resolve chats, and manage their CRM metadata. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*, *Send session message*. Each endpoint below also lists the exact scopes it needs. - name: Labels description: >- Create and edit labels, assign or remove them from chats, retrieve label data, or delete labels from your inbox. **Suggested token for this group** - scopes: *Manage labels*, *Manage all chats* (needed for managing labels on chats). Each endpoint below also lists the exact scopes it needs. - name: Channels description: >- Monitor and maintain the health of connected messaging channels - retrieve active channel health problems, filter them by severity or account, and mark issues as resolved. **Suggested token for this group** - scopes: *Manage channels*. Each endpoint below also lists the exact scopes it needs. - name: Quick Replies description: >- Manage quick replies - prepared messages agents can send into matching chats with one click. Quick replies marked with `aiQuickReply` client metadata appear as **AI suggestions** in the Texter inbox (see Create Quick Reply for the full flow). **Suggested token for this group** - scopes: *View quick replies*, *Manage quick replies*. Each endpoint below also lists the exact scopes it needs. - name: Files description: >- Generate public access links to media files stored in Texter. **Suggested token for this group** - scopes: *View all files*, *View all chats* (both required). Each endpoint below also lists the exact scopes it needs. - name: Subscribe to Events description: >- Register webhooks for events occurring in your Texter environment. Under the hood this uses **Scenarios** - a workflow automation feature within Texter. To make integration easy, pre-defined templates are provided: import a scenario JSON, plug in your webhook URL and user UID, and the subscription is active. See the **Webhook Events** pages for the payload your URL receives for each event. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*. Each endpoint below also lists the exact scopes it needs. If the provided templates don't satisfy your needs, contact [Texter Support](https://wa.me/972586640430) and we'll gladly help modify any triggers, conditions or actions for your webhook. - name: Scenarios (Advanced) description: >- Full programmatic control over scenarios for advanced automations: create scenarios from scratch, copy them, edit drafts, publish revisions, inspect execution runs, and discover the available building blocks (events, conditions, loaders, actions). For plain webhook subscriptions, the **Subscribe to Events** group with its ready-made templates is the simpler path. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Edit scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*, *View scenarios runs*. Each endpoint below also lists the exact scopes it needs. paths: /chats/{chatId}: patch: tags: - Chats summary: Update Chat Properties description: >- Modify attributes of a chat. Most commonly used to change a contact's display name in Texter or to enable/disable an external bot for the chat. **Required token scopes:** `Manage all chats` Note that updating properties **fully overrides** existing values. For example, if a `crmData` object already exists, it is fully replaced by the new object provided in the request. To **merge** CRM data instead, use **Update CRM Data**. operationId: update-chat parameters: - name: chatId in: path required: true schema: type: string description: >- The unique identifier of the chat. You can obtain this value by using the Search Chats endpoint with the contact's phone number requestBody: required: true content: application/json: schema: type: object properties: displayName: type: string maxLength: 255 description: Updates the display name of the chat externalBot: type: boolean description: >- Whether an external bot is active. Toggling this value triggers an event - commonly used to enable or disable an external bot integration crmData: type: object additionalProperties: true description: >- CRM metadata object for the chat. **Fully replaces** the existing object crmDeepLink: type: string description: >- A direct link to the contact's CRM record, shown to agents in Texter title: type: string maxLength: 255 deprecated: true description: Deprecated - use `displayName` instead language: type: string description: Reserved for future functionality examples: Enable external bot: value: externalBot: true Replace CRM data: value: crmData: age: 18 email: johnd1@gmail.com Update multiple properties: value: displayName: Donald J. Trump crmDeepLink: https://texterchat.com/ externalBot: false responses: '200': description: >- The updated chat object. Field-by-field reference: [The Chat object](/api-reference/objects/chat) content: application/json: schema: $ref: '#/components/schemas/Chat' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: data/title must NOT have more than 255 characters '401': description: Missing or invalid token, or missing required scope '404': description: Chat not found components: schemas: Chat: type: object description: A conversation with a contact on a connected channel properties: _id: type: string description: Unique identifier of the chat in Texter example: 64de3b15398a8e09c47a9f62 title: type: string description: Contact's name as set in their WhatsApp account settings displayName: type: string description: >- Custom name modified in Texter. Absent if the display name was never modified personId: type: string description: >- ID of the person that owns this chat - links chats of the same person across channels image: type: string description: File ID of the chat's avatar image, when available channelInfo: $ref: '#/components/schemas/ChannelInfo' agent: type: object description: The assigned agent properties: uid: type: string nullable: true description: Internal Texter user ID of the assigned agent displayName: type: string nullable: true description: Name of the assigned agent departmentId: type: string nullable: true description: Department responsible for the chat status: $ref: '#/components/schemas/ChatStatus' unreadCount: type: number description: Number of unread incoming messages labels: type: array items: type: string description: List of label IDs applied to the chat example: - urgent - billing lastMessage: type: object description: >- Preview of the last message in the chat. Note: not included in Search Chats results properties: type: type: string description: Type of the last message (`text`, `media`, `special`...) text: type: string description: Text content of the last message, if applicable media: type: array description: Media files attached to the last message items: $ref: '#/components/schemas/MediaItem' last_message_timestamp: type: number description: >- Timestamp (epoch **milliseconds**) of the last message sent or received lastIncomingMessageTimestamp: type: number description: >- Timestamp (epoch **milliseconds**) of the last incoming (contact) message created: type: string format: date-time description: When the chat was created updatedAt: type: string format: date-time description: Last time the chat was updated pendingMessageTime: type: number nullable: true description: >- Timestamp (epoch **seconds**) of the last pending-reminder the bot sent while the chat waits for an agent. Reset to null on resolve pendingUpdateTime: type: number description: Timestamp (epoch **seconds**) of the last update into pending status resolvedUpdateTime: type: number description: >- Timestamp (epoch **seconds**) of the last time the chat was marked as RESOLVED replyAction: $ref: '#/components/schemas/ReplyAction' sendingBulkAgent: type: string description: ID of the agent who initiated the bulk template message latestBulkSendId: type: string description: >- ID of the latest bulk send performed in this chat. Its presence does **not** mean the chat is currently in BULK status - only that a bulk send happened at some point botState: allOf: - $ref: '#/components/schemas/BotState' nullable: true previousBotSession: allOf: - $ref: '#/components/schemas/BotState' nullable: true description: Data about the second-to-last bot session crmData: type: object additionalProperties: true description: >- Custom CRM metadata associated with the chat; structure varies by integration (Powerlink, Monday, etc.) crmDeepLink: type: string description: >- Personalized link to the contact's record in the integrated business CRM crmLastTicketId: description: >- Reference to the most recent CRM record linked to the chat. String or number depending on the CRM integration oneOf: - type: string - type: number lastMessageStoredInCRMTimestamp: type: number description: Timestamp (epoch **milliseconds**) of the last message stored in CRM externalBot: type: boolean description: >- Whether an external bot (outside Texter) is currently active. Changing this value triggers an event - commonly used to enable or disable external bot integrations unsubscribed: type: object description: Present when the chat unsubscribed from template messages properties: date: type: string format: date-time description: When the chat unsubscribed from template messages bulkSendId: type: string description: >- Latest bulk send ID this contact was included in before unsubscribing blockedChat: type: object properties: blocked: type: boolean description: Whether the chat is marked as blocked agent: type: string description: ID of the agent who blocked the chat hasMessageError: type: boolean description: Whether the chat contains failed outgoing messages language: type: string description: The chat's preferred language. Reserved for future functionality personChats: type: array items: $ref: '#/components/schemas/ChannelInfo' description: >- All chats of the same person (including this one), as channel references. Present in webhook event payloads; not included in REST search results channel: type: string deprecated: true description: Deprecated - use `channelInfo.name` instead clientPhone: type: string deprecated: true description: Deprecated - use `channelInfo.id` instead clientPhoneE164: type: string deprecated: true description: Deprecated - use `channelInfo.id` instead entityPhone: type: string deprecated: true description: Deprecated - use `channelInfo.accountId` instead lastText: type: string deprecated: true description: Deprecated - use `lastMessage.text` instead unsubscribeTime: type: number deprecated: true description: Deprecated (epoch **seconds**) - use `unsubscribed.date` instead blockTemplates: type: boolean deprecated: true description: Deprecated - use the `unsubscribed` property instead ErrorResponse: type: object properties: error: type: string description: Human-readable error message required: - error ChannelInfo: type: object description: Channel that an entity belongs to properties: name: type: string enum: - whatsapp - messenger - instagram - website_chat - email - sms description: Messaging channel type accountId: type: string description: >- The business account ID connected to Texter. For WhatsApp this is the business phone number example: '972586640430' id: type: string description: >- The contact's ID on the channel. For WhatsApp this is the contact's phone number example: '972521234567' metadata: type: object additionalProperties: true description: Channel-specific metadata, when present ChatStatus: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: >- Chat status: `0` = BOT (handled by bot), `1` = PENDING (waiting for an agent), `2` = ASSIGNED (shown as "Taken" in Texter), `3` = RESOLVED, `4` = BULK MediaItem: type: object description: A media file attached to a message properties: mediaType: type: string enum: - image - video - document - audio - sticker description: The kind of file in this media item fileId: type: string description: >- Internal file ID in Texter storage. Use with Generate Public Media URL to download example: 6900c1eac29d42708adac92f previewId: type: string description: Internal preview/thumbnail file ID filename: type: string description: Original filename from the sender device example: offer_october_2025.pdf contentType: type: string description: MIME type example: application/pdf caption: type: string description: >- Optional caption text attached to the media. Relevant when mediaType is `image` or `video` metadata: type: object additionalProperties: true description: Channel / provider metadata for this attachment example: frequentlyForwarded: false scanned: type: boolean description: Whether the file has been scanned for threats deleted: type: object description: >- Present when the media file was removed by scheduled deletion (the message itself remains). The `fileId` no longer resolves properties: timestamp: type: number description: When the file was deleted (epoch ms) url: type: string deprecated: true description: Deprecated - use the `fileId` download flow instead ReplyAction: type: object nullable: true description: >- Action that runs when the contact replies to a template message. Set by template defaults or by the Send Template Message `replyAction` parameter properties: created: type: number description: >- When the reply action was set (epoch **seconds**). Expiration is measured relative to this expirationTime: type: number description: >- How long (in seconds, relative to `created`) the reply action remains valid example: 259200 chatStatus: allOf: - $ref: '#/components/schemas/ChatStatus' description: Status to apply when the contact replies setBotNode: type: string description: Bot node to trigger after reply bot: type: string description: Specific bot to run after reply replyText: type: string description: Text automatically sent after the contact replies responsibleAgent: type: string description: Agent the chat is assigned to after the reply responsibleDepartment: type: string description: Department the chat is assigned to after the reply replyToTemplateFile: type: object description: File automatically sent after the contact replies properties: url: type: string name: type: string resolveTime: type: number description: Internal scheduling timestamp, when present status: allOf: - $ref: '#/components/schemas/ChatStatus' deprecated: true description: Deprecated - use `chatStatus` instead BotState: type: object additionalProperties: true description: >- Data about the active or most recent bot session. May contain additional bot-specific keys beyond the ones listed properties: id: type: string description: >- Internal ID of the bot session (use as `botSessionId` when fetching messages) flowVersion: type: object properties: identifier: type: string description: Identifier of the bot example: onboarding-bot version: type: number description: Version number of the bot flow example: 203 node: type: string description: Current or last bot node userState: type: object additionalProperties: true description: >- Key-value memory of collected variables or answers from different bot nodes store: type: object additionalProperties: true description: Key-value memory of variables collected during the session latestAgentUid: type: string nullable: true description: ID of the last human agent involved in the session latestAgentName: type: string nullable: true description: Display name of the last human agent involved securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token generated in Texter: gear icon → Developers → API Tokens. When creating a token, assign it the scopes required by the endpoints you plan to call - each endpoint lists its required scopes. ````