> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message threads

> Index all contacts a phone number has communicated with.

This endpoint will index all of the contacts which a phone number has communicated with (threads).

with paging limited to `50 messages` per response.

It will be sorted by `updated_at` in descending order.


## OpenAPI

````yaml v2/api-reference/sms/sms-collection.json GET /{instance}/message-threads
openapi: 3.1.0
info:
  title: Hypersender SMS API Docs
  version: v1.0
  description: >-
    Send and receive sms messages, with Hypersender SMS API. This Documentation
    provides a comprehensive guide to the API, including detailed information on
    how to send and receive sms messages, controll message threads, and monitor
    phone heartbeats.


    **How it works**


    To use the API, you need to have the Hypersender app installed on your
    android phone. The app will receive the messages and send them to the
    recipient.


    **Download the app**


    You can download it from the release page on
    [github](https://github.com/hypersender/sms-app-releases/releases).


    **How to use the app**


    - Download the app from the release page.


    - Install the app on your android phone.


    - Grant the app the necessary permissions, see the
    [permissions](https://docs.hypersender.com/docs/hypersender/overview/sms-quick-start#step-4-download-the-hypersender-sms-app),
    section for more information.


    - Open the app, and scan the QR code to link the app with the API.


    - The app will start receiving messages, and then send them to the
    recipient.



    <hr />


    **Quick Demo**

      **Learn how to use Hypersender SMS API to send a message using Postman:**
      [Demo Link](https://app.hypersender.com/send-sms-message-in-postman) **to easily interact with our API.**

    <hr />


    **postman collection**


    You can download our [Postman
    Collection](https://docs.hypersender.com/sms-postman-collection.json) to
    easily interact with our API.
servers:
  - url: https://app.hypersender.com/api/sms/v1
    description: Production
security:
  - Authorization: []
paths:
  /{instance}/message-threads:
    get:
      tags:
        - Message threads
      summary: Message threads
      description: >
        ## Message Threads


        This endpoint will index all of the contacts which a phone number has
        communicated with (threads). with paging limited to 50 messages per
        response. It will be sorted by updated_at in descending order.
      operationId: message-threads
      parameters:
        - name: Accept
          in: header
          schema:
            type: string
          example: application/json
        - schema:
            type: string
          in: query
          name: per_page
          description: 'number of messages per page, max: 50'
          example: ''
        - name: instance
          in: path
          description: Instance UUID copied from hypersender dashboard
          required: true
          schema:
            type: string
            example: '{{ instance_id }}'
          examples:
            default:
              value: '{{ instance_id }}'
        - schema:
            type: string
          in: query
          name: sort
          description: >-
            default: -updated_at, you can sort by any date: 'created_at',
            'last_message_at', 'updated_at'
          example: ''
        - schema:
            type: string
          in: query
          name: filter[last_message_content]
          description: filter by last message content.
          example: ''
        - schema:
            type: boolean
          in: query
          name: filter[is_archived]
          description: filter by SMS messages based on their archived status.
          example: ''
        - schema:
            type: string
          in: query
          name: filter[last_message_id]
          description: get the thread where the thread is the specified message id
          example: ''
        - schema:
            type: string
          in: query
          name: filter[from_or_to_number]
          description: get the thread where the "from" or "to" of phone number
          example: ''
        - schema:
            type: string
          in: query
          name: include
          description: >-
            include the phone or messageThread object with the message, possible
            values: phone, messageThread
          example: ''
      requestBody:
        content: {}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    id: 9df34332-2070-4cc5-beba-ad21fcf9ff6f
                    phone_id: 9defcf1e-552c-4bef-a843-872edec576ef
                    last_message_id: 9e03fc6b-ce90-4399-a472-6b029857e15b
                    from_phone_number: WE
                    to_phone_number: '+201412789476'
                    is_archived: false
                    last_message_content: >-
                      اشترك الآن في أجدع شحنه 26.6 واحصل علي 1,300 وحده تستخدمهم
                      في المكالمات الصوتيه و الانترنت ب 26.6 جنيه صالحه لمدة 14
                      يوم. للإشتراك اتصل ب #566* او زور تطبيق MyWE
                    last_message_at: '2025-01-20 18:59:28'
                    created_at: '2025-01-12 11:28:19'
                    updated_at: '2025-01-20 18:59:30'
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: o471oxuz9vr8e
                    items:
                      $ref: '#/components/schemas/MessageThread'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                Example 1:
                  value:
                    data:
                      - id: 9df34184-99e5-43a5-9e6d-371de0344bb9
                        phone_id: 9defcf1e-552c-4bef-a843-872edec576ef
                        last_message_id: 9e05ec65-bd9e-42b8-aa18-ddd497b4667e
                        from_phone_number: '4100'
                        to_phone_number: '+2014398429234'
                        is_archived: false
                        last_message_content: "مبروك ليك 20 وحدة هدية\r\nرد ب 1 الاّن!\r\nو اشتراك اول يوم علينا\r\nو فرصتك تلعب و تكسب 50,000جنيه\r\nاشترك في GamezZe بـ5جنيه لليوم \r\nرد ب 1 الاّن"
                        last_message_at: '2025-01-21 17:38:41'
                        created_at: '2025-01-12 11:23:38'
                        updated_at: '2025-01-21 18:06:21'
                    links:
                      first: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=1
                      last: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=6
                      prev: null
                      next: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=2
                    meta:
                      current_page: 1
                      from: 1
                      last_page: 6
                      links:
                        - url: null
                          label: '&laquo; Previous'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=1
                          label: '1'
                          active: true
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=2
                          label: '2'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=3
                          label: '3'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=4
                          label: '4'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=5
                          label: '5'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=6
                          label: '6'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads?per_page=1&page=2
                          label: Next &raquo;
                          active: false
                      path: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/message-threads
                      per_page: 1
                      to: 1
                      total: 6
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    MessageThread:
      type: object
      properties:
        id:
          type: string
        phone_id:
          type: string
        last_message_id:
          type: string
        from_phone_number:
          type: string
        to_phone_number:
          type: string
        is_archived:
          type: boolean
        last_message_content:
          type: string
        last_message_at:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      x-examples:
        Example 1:
          id: 9df34332-2070-4cc5-beba-ad21fcf9ff6f
          phone_id: 9defcf1e-552c-4bef-a843-872edec576ef
          last_message_id: 9e03fc6b-ce90-4399-a472-6b029857e15b
          from_phone_number: WE
          to_phone_number: '+201478930987'
          is_archived: false
          last_message_content: >-
            اشترك الآن في أجدع شحنه 26.6 واحصل علي 1,300 وحده تستخدمهم في
            المكالمات الصوتيه و الانترنت ب 26.6 جنيه صالحه لمدة 14 يوم. للإشتراك
            اتصل ب #566* او زور تطبيق MyWE
          last_message_at: '2025-01-20 18:59:28'
          created_at: '2025-01-12 11:28:19'
          updated_at: '2025-01-20 18:59:30'
    PaginationLinks:
      type: object
      x-examples:
        Example 1:
          first: >-
            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=1
          last: >-
            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=2
          prev: null
          next: >-
            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=2
      properties:
        first:
          type:
            - string
            - 'null'
        last:
          type:
            - string
            - 'null'
        prev:
          type:
            - string
            - 'null'
        next:
          type:
            - string
            - 'null'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type: integer
        last_page:
          type: integer
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              label:
                type: string
              active:
                type: boolean
        path:
          type: string
        per_page:
          type: integer
        to:
          type: integer
        total:
          type: integer
      x-examples:
        Example 1:
          current_page: 1
          from: 1
          last_page: 2
          links:
            - url: null
              label: '&laquo; Previous'
              active: false
            - url: >-
                https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=1
              label: '1'
              active: true
            - url: >-
                https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=2
              label: '2'
              active: false
            - url: >-
                https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?include=phone%2CmessageThread&page=2
              label: Next &raquo;
              active: false
          path: >-
            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages
          per_page: 50
          to: 50
          total: 74
    Error400:
      title: Error400
      x-stoplight:
        id: 8swvc1ct1z3h7
      type: object
      properties:
        errors:
          type: object
          x-stoplight:
            id: rw2idauwtmv2j
          description: This Object contains the key and the message
        message:
          type: string
          x-stoplight:
            id: 5rbetqawbxxn7
          example: The given data was invalid.
        status:
          type: string
          x-stoplight:
            id: ueqvh7touhe34
          example: '400'
      required:
        - errors
        - message
        - status
    Error500:
      title: Error500
      x-stoplight:
        id: pwoo8am0y1e5j
      type: object
      properties:
        message:
          type: string
          x-stoplight:
            id: 5rbetqawbxxn7
          example: Internal Server Error
      required:
        - message
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````