> ## 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. # Search Chats > Search for chats based on various query parameters. The most common use case is searching by the contact's phone number using the `search` parameter. **Required token scopes:** `List all chats` Results are sorted by last message time (newest first). Note: the chat objects returned by this endpoint do **not** include the `lastMessage` preview field. All status values, type enums and the ID cheat sheet: [Enums & Common Fields](/he/api-reference/enums). ## OpenAPI ````yaml he/api-reference/openapi.json GET /chats/search 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/search: get: tags: - Chats summary: Search Chats description: >- Search for chats based on various query parameters. The most common use case is searching by the contact's phone number using the `search` parameter. **Required token scopes:** `List all chats` Results are sorted by last message time (newest first). Note: the chat objects returned by this endpoint do **not** include the `lastMessage` preview field. All status values, type enums and the ID cheat sheet: [Enums & Common Fields](/he/api-reference/enums). operationId: search-chats parameters: - name: search in: query schema: type: string minLength: 2 description: >- Search by contact phone number or name (case-insensitive, minimum 2 characters) - name: channel[name] in: query schema: type: string enum: - whatsapp - messenger - instagram - website_chat - email description: >- Filter by channel name. Must be used together with `channel[accountId]` - name: channel[accountId] in: query schema: type: string description: >- Filter by channel account ID. Must be used together with `channel[name]` - name: labels[] in: query schema: type: array items: type: string maxItems: 100 style: form explode: true description: >- Filter chats by label ID. Repeat the parameter to match multiple labels (chats matching **any** of the labels are returned). Up to 100 unique labels - name: statuses[] in: query schema: type: array items: type: string enum: - BOT - PENDING - ASSIGNED - RESOLVED - BULK maxItems: 5 style: form explode: true description: >- Filter chats by status name. Repeat the parameter to include multiple statuses (same behavior as `labels[]`). Note: use `ASSIGNED` (shown as "Taken" in Texter) and `RESOLVED` - values like `SOLVED` or `TAKEN` are rejected - name: showNoMessages in: query schema: type: string enum: - '1' - 'true' - '0' - 'false' description: >- Whether to include chats with no messages. By default, only chats that contain messages are returned - name: limit in: query schema: type: string pattern: ^\d+$ description: The maximum number of results to return (1-10000). Defaults to 30 - name: skip in: query schema: type: string pattern: ^\d+$ description: The number of results to skip before starting to return records responses: '200': description: >- The matching chats and the total count. Field-by-field reference: [The Chat object](/he/api-reference/objects/chat) content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Chat' description: >- Chat objects matching the search criteria (without the `lastMessage` preview) total: type: number description: >- Total number of chats matching the query (ignoring pagination) example: data: - _id: 67bf11038b24880cc966f799 title: John Doe agent: uid: null displayName: '' channel: whatsapp entityPhone: '+972509876543' clientPhoneE164: '+972521234567' clientPhone: '+972521234567' created: '2025-02-26T13:02:58.353Z' botState: {} last_message_timestamp: 1762012091000 lastIncomingMessageTimestamp: 1762012091000 status: 3 unreadCount: 6 channelInfo: name: whatsapp id: '972521234567' accountId: '972509876543' departmentId: null resolvedUpdateTime: 1762012093 crmData: aiTerminateReason: Inactivity externalBot: false updatedAt: '2025-11-01T15:48:14.076Z' total: 1 '400': description: Invalid query content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: data/statuses/0 must be equal to one of the allowed values '401': description: Missing or invalid token, or missing required scope x-codeSamples: - lang: bash label: By phone number source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?search=0521234567" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Multiple statuses (OR) source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?statuses[]=PENDING&statuses[]=ASSIGNED" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Multiple labels (OR) source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?labels[]=VIP&labels[]=hot_lead" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Status + label combined source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?statuses[]=RESOLVED&labels[]=VIP" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Specific channel, paginated source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?channel[name]=whatsapp&channel[accountId]=972586640430&limit=50&skip=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Include chats without messages source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/chats/search?search=0521234567&showNoMessages=true" \ -H "Authorization: Bearer YOUR_API_TOKEN" 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. ````