> ## 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. # Get Messages of a Chat > Retrieve messages from a specific chat. Messages are returned in ascending order (earliest to latest), up to `limit` messages (default 50). **Required token scopes:** `View all chats` **A filter is required** - provide either `botSessionId`, or both `beforeTime` and `beforeId`: * **Bot session** - retrieve all messages from a specific bot session by providing `botSessionId`. You can obtain this ID via Search Chats or Get Chat by Chat ID - the chat object includes a `botState` field (and `previousBotSession`) where you can find the session `id`. * **Before time & before ID** - cursor pagination, both parameters together: the response includes messages with a timestamp **up to and including** `beforeTime`, excluding the message identified by `beforeId`. To page backwards through history, pass the timestamp and `_id` of the oldest message you already have. 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 /messages/chat/{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: /messages/chat/{chatId}: get: tags: - Messages summary: Get Messages of a Chat description: >- Retrieve messages from a specific chat. Messages are returned in ascending order (earliest to latest), up to `limit` messages (default 50). **Required token scopes:** `View all chats` **A filter is required** - provide either `botSessionId`, or both `beforeTime` and `beforeId`: - **Bot session** - retrieve all messages from a specific bot session by providing `botSessionId`. You can obtain this ID via Search Chats or Get Chat by Chat ID - the chat object includes a `botState` field (and `previousBotSession`) where you can find the session `id`. - **Before time & before ID** - cursor pagination, both parameters together: the response includes messages with a timestamp **up to and including** `beforeTime`, excluding the message identified by `beforeId`. To page backwards through history, pass the timestamp and `_id` of the oldest message you already have. All status values, type enums and the ID cheat sheet: [Enums & Common Fields](/he/api-reference/enums). operationId: get-chat-messages 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 - name: limit in: query schema: type: string pattern: ^[0-9]+$ description: The maximum number of messages to return. Defaults to 50 - name: beforeTime in: query schema: type: string pattern: ^[0-9]+$ description: >- Return messages with a timestamp up to and including this value (Unix epoch milliseconds). Must be used together with `beforeId` - name: beforeId in: query schema: type: string pattern: ^[a-z0-9]+$ description: >- Message ID to exclude from the results (the cursor message). Must be used together with `beforeTime` - name: botSessionId in: query schema: type: string pattern: ^[a-z0-9]+$ description: >- Return only messages within the specified bot session (the bot state ID) responses: '200': description: >- The matching messages plus the time range of the entire chat. Field-by-field reference: [The Message object](/he/api-reference/objects/message) content: application/json: schema: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' minTime: description: >- Timestamp (ms) of the first-ever message in the chat, or `false` if the chat has no messages oneOf: - type: number - type: boolean maxTime: description: >- Timestamp (ms) of the most recent message in the chat, or `false` if the chat has no messages oneOf: - type: number - type: boolean example: messages: - _id: 68ba89f8c909657dffcf267c chatChannelInfo: name: whatsapp id: '972521234567' accountId: '972509876543' channelInfo: id: >- wamid.HBgMOTcyNTQ0NTU0ODUyFQIAEhgUM0ExNkMwMzdBN0Q0MDFEN0E4RUUA direction: incoming parent_chat: 67a87067aeedqdee1271ck4d status: 2 statusHistory: - status: 2 timestamp: 1757055477000 text: Hi timestamp: 1757055477000 type: text updatedAt: '2025-09-05T06:58:01.651Z' metadata: triggeredBot: true botSessionId: >- c1125880930b372b0f1047cad91ab5aca4f1171993d8af709497d16f77772fa4 minTime: 1746616143295 maxTime: 1757056145969 '400': description: Missing/invalid filter parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: >- data must have required property 'botSessionId', data must have required property 'beforeId', data must match a schema in anyOf '401': description: Missing or invalid token, or missing required scope '404': description: Chat not found x-codeSamples: - lang: bash label: Page back from newest source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/messages/chat/67bf11038b24880cc966f799?beforeTime=1762012091000&beforeId=68ba8c904657483ffee3101e" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Messages of a bot session source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/messages/chat/67bf11038b24880cc966f799?botSessionId=694cc065571521039d74a51044e89b932fe3310290d7c7db75fb0ccad343c9da" \ -H "Authorization: Bearer YOUR_API_TOKEN" - lang: bash label: Bot session, last 100 source: >- curl -g "https://YOUR_PROJECT.texterchat.com/server/api/v2/messages/chat/67bf11038b24880cc966f799?botSessionId=694cc065571521039d74a510...&limit=100" \ -H "Authorization: Bearer YOUR_API_TOKEN" components: schemas: Message: type: object description: >- A message within a chat. Messages come in two variants: **regular messages** (actual conversation) and **system messages** (`systemMessage: true` - routing/assignment records that only carry `newChatStatus`, `agent`, `assignedToAgent`, `assignedToDepartment` and timestamps; they have no `direction`, `status`, content or reactions) properties: _id: type: string description: Unique message ID in Texter example: 69062b15962e17ab3033f886 systemMessage: type: boolean description: >- Marks a system/control message instead of a normal chat bubble. `true` messages describe routing / assignment / status changes and omit most regular-message fields type: type: string enum: - text - media - contacts - location - buttons - list - postback - special description: The content type of the message text: type: string description: >- Human-readable body text. Present on most `text`, `buttons`, `list` and `special` messages buttons: type: array description: >- Interactive reply buttons that were sent. Only when `type` is `buttons` items: type: object properties: title: type: string payload: type: string list: type: object description: WhatsApp "list picker" that was sent. Only when `type` is `list` properties: button: type: string sections: type: array items: type: object properties: title: type: string rows: type: array items: type: object properties: title: type: string payload: type: string description: type: string postback: type: object description: >- Which list item / button the contact chose. Only when `type` is `postback` (incoming) properties: payload: type: string title: type: string description: type: string media: type: array description: Array of media items in this message. Only when `type` is `media` items: $ref: '#/components/schemas/MediaItem' location: type: object description: Shared location data. Only when `type` is `location` properties: latitude: type: number longitude: type: number name: type: string address: type: string url: type: string contacts: type: array description: Shared contact cards. Only when `type` is `contacts` items: $ref: '#/components/schemas/ContactCard' special: type: object additionalProperties: true description: >- Channel-specific or structured content. Only when `type` is `special`. Known flags: `redacted: true` (contents redacted as sensitive), `deleted: { previousType, timestamp }` (contents removed by scheduled deletion - explains "empty" messages), `isEchoMessage: true` (outgoing message sent from another client, not Texter), `isHistoryMessage: true`, `isStatusMessage: true`, `unsupportedByProvider: true`, plus channel-specific keys (`whatsapp`, `messenger`, `instagram`, `email`) such as template send data metadata: type: object description: Extra metadata about this message properties: triggeredBot: type: boolean description: Whether this incoming message triggered automation/bot logic botMsgInfo: type: object description: Which bot node generated this outgoing message properties: identifier: type: string version: type: number nodeName: type: string hideSummary: type: boolean bulkSendId: type: string description: Bulk / campaign batch ID for this message whatsappTemplate: type: object description: >- Structured template send data for outgoing WhatsApp template messages properties: name: type: string description: Template name localization: type: object additionalProperties: true description: The localization that was sent contents: type: object additionalProperties: true description: The resolved send contents (header, body values, buttons) additionalProperties: true chatChannelInfo: allOf: - $ref: '#/components/schemas/ChannelInfo' description: Which channel account / contact this message belongs to channelInfo: type: object description: >- Provider-side message identifier - use it to correlate with WhatsApp provider / Meta logs. Note: on system messages (`systemMessage: true`) the `id` is an internal placeholder with no provider meaning properties: id: type: string example: wamid.HBgMOTcyNTI3NzYwOTg5FQIAERgS... metadata: type: object additionalProperties: true direction: type: string enum: - incoming - outgoing description: Logical direction of the message. Regular messages only status: $ref: '#/components/schemas/MessageStatus' statusHistory: type: array description: Timeline of delivery/read states for this message items: type: object properties: status: $ref: '#/components/schemas/MessageStatus' timestamp: type: number description: Epoch milliseconds reactions: type: array items: type: string description: Current emoji reactions on the message reactionsHistory: type: array description: Timeline of reaction add/remove events items: type: object properties: timestamp: type: number description: Epoch milliseconds reaction: type: string description: The emoji, when added removed: type: boolean description: '`true` when this event removed the reaction' timestamp: type: number description: When the message was created (epoch **milliseconds**) updatedAt: type: string format: date-time description: >- Last time this message was updated (e.g. when delivery status changes) parent_chat: type: string description: The chat ID this message belongs to agent: type: string description: Which agent or bot sent this message - `"Bot"` or an agent UID assignedToAgent: type: string description: >- Which agent the chat was assigned to at this moment. Only on system messages assignedToDepartment: type: string description: >- Which department the chat was assigned to. Only on some system messages newChatStatus: allOf: - $ref: '#/components/schemas/ChatStatus' description: >- New chat status after this routing/system event. Only on system messages botSessionId: type: string description: Bot session / flow instance ID tied to this message hideSummary: type: boolean description: Whether this message should be hidden from summaries tmpSendId: description: >- Client-generated ID to match a send request to the stored message. String or number oneOf: - type: string - type: number errorReason: type: string description: >- Reason the send failed (provider error, throttling, 24h window, etc.). Only present if delivery failed context: type: object additionalProperties: true description: >- The message this message replies to. In API read/send responses this is **populated into a full Message object** (same schema, recursive). In raw webhook payloads it may be only the provider reference `{ id }` of the replied-to message forwarded: type: boolean description: Whether WhatsApp marked the message as forwarded sensitive: type: boolean description: >- Whether the content is marked sensitive and should be redacted in some views scheduledDeletion: type: object description: >- Present when the message is scheduled for deletion by data-retention rules properties: timestamp: type: number description: Planned deletion time (epoch ms) type: type: string enum: - full - contents - media description: What gets deleted setManuallyByUid: type: string description: Agent UID, when the deletion was scheduled manually incoming: type: boolean deprecated: true description: Deprecated - use `direction` instead outgoing: type: boolean deprecated: true description: Deprecated - use `direction` instead received: type: number deprecated: true description: Deprecated (epoch ms) - use `timestamp` instead botMsgInfo: type: object deprecated: true additionalProperties: true description: Deprecated - use `metadata.botMsgInfo` instead bulkSendId: type: string deprecated: true description: Deprecated - use `metadata.bulkSendId` instead providerMessageId: type: string deprecated: true description: Deprecated - use `channelInfo.id` instead messageId: type: string deprecated: true description: Deprecated - use `_id` instead templateId: type: string deprecated: true description: Deprecated - use `metadata.whatsappTemplate` instead templateMessage: type: boolean deprecated: true description: Deprecated - use `metadata.whatsappTemplate` instead templateMessageData: type: object deprecated: true additionalProperties: true description: Deprecated - use `metadata.whatsappTemplate` instead parameters: type: array deprecated: true items: type: string description: Deprecated - use `metadata.whatsappTemplate` instead ErrorResponse: type: object properties: error: type: string description: Human-readable error message required: - error 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 ContactCard: type: object description: A shared contact card (vCard-style) properties: name: type: object properties: formatted_name: type: string description: Full name of the contact first_name: type: string last_name: type: string middle_name: type: string prefix: type: string description: e.g. Mr., Ms., Dr. suffix: type: string description: e.g. Jr., Sr., III required: - formatted_name phones: type: array items: type: object properties: phone: type: string type: type: string description: e.g. MOBILE, WORK required: - phone emails: type: array items: type: object properties: email: type: string type: type: string required: - email urls: type: array items: type: object properties: url: type: string required: - url addresses: type: array items: type: object properties: street: type: string city: type: string state: type: string zip: type: string country: type: string country_code: type: string description: Two-letter country code type: type: string description: HOME or WORK org: type: object properties: company: type: string department: type: string title: type: string description: Job title birthday: type: string description: YYYY-MM-DD formatted string 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 MessageStatus: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 description: >- Message delivery status: `0` = Sent, `1` = Accepted by provider, `2` = Delivered, `3` = Seen, `4` = Failed, `5` = Channel Failed, `6` = Deleted 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 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. ````