> ## 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 Chat by Chat ID

> Retrieve a chat by its ID. The response is the chat's **public view** - a trimmed set of properties (it does not include `_id`, `labels`, `crmData` or `displayName`, and `botState` is narrowed to just its session `id`). To retrieve the complete chat record, use **Search Chats**.

**Required token scopes:** `Send session message`


## OpenAPI

````yaml api-reference/openapi.json GET /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}:
    get:
      tags:
        - Chats
      summary: Get Chat by Chat ID
      description: >-
        Retrieve a chat by its ID. The response is the chat's **public view** -
        a trimmed set of properties (it does not include `_id`, `labels`,
        `crmData` or `displayName`, and `botState` is narrowed to just its
        session `id`). To retrieve the complete chat record, use **Search
        Chats**.


        **Required token scopes:** `Send session message`
      operationId: get-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
      responses:
        '200':
          description: >-
            The public chat view. Field-by-field reference: [The Chat
            object](/api-reference/objects/chat)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicChat'
              example:
                success: true
                title: Niv Shteingart
                channelInfo:
                  name: whatsapp
                  id: '972521234567'
                  accountId: '972549876543'
                departmentId: null
                agent:
                  uid: null
                  displayName: ''
                status: 0
                created: '2025-05-07T11:09:03.295Z'
                updatedAt: '2025-11-03T20:05:15.532Z'
                lastIncomingMessageTimestamp: 1762200310000
                lastMessage:
                  type: text
                  text: מה שמך?
                unreadCount: 2
                botState:
                  id: >-
                    236ef058aa87c90536c33493d2024cd87055bdac4d64a0f22fd84fcb3cea6f8d
                lastMessageTimestamp: 1762200315209
        '401':
          description: Missing or invalid token, or missing required scope
        '404':
          description: Chat not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendErrorResponse'
              example:
                error: Chat not found
                success: false
components:
  schemas:
    PublicChat:
      type: object
      description: >-
        The public chat view returned by Get Chat by ID. Note: this is a trimmed
        version of the chat - fields like `_id`, `labels`, `crmData` and
        `displayName` are not included, and `botState` is narrowed to its `id`
        only.
      properties:
        success:
          type: boolean
          example: true
        title:
          type: string
        channelInfo:
          $ref: '#/components/schemas/ChannelInfo'
        departmentId:
          type: string
          nullable: true
        agent:
          type: object
          properties:
            uid:
              type: string
              nullable: true
            displayName:
              type: string
              nullable: true
        status:
          $ref: '#/components/schemas/ChatStatus'
        created:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lastIncomingMessageTimestamp:
          type: number
          description: Epoch milliseconds
        lastMessage:
          type: object
          properties:
            type:
              type: string
            text:
              type: string
            media:
              type: array
              items:
                $ref: '#/components/schemas/MediaItem'
        blockedChat:
          type: object
          properties:
            blocked:
              type: boolean
            agent:
              type: string
        unreadCount:
          type: number
        unsubscribed:
          type: object
          properties:
            date:
              type: string
              format: date-time
            bulkSendId:
              type: string
        externalBot:
          type: boolean
        crmDeepLink:
          type: string
        language:
          type: string
        botState:
          type: object
          description: Narrowed bot state - only the session ID is returned
          properties:
            id:
              type: string
        lastMessageTimestamp:
          type: number
          description: >-
            Timestamp (epoch **milliseconds**) of the last message sent or
            received
    SendErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        success:
          type: boolean
          example: false
      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
  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.

````