> ## 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.

# Index Messages

> Retrieve a list of messages with filtering and pagination options.

This endpoint will index all of the messages sent and received based on various criteria, including searching with request id and messages attributes, with paging limited to 50 messages per response. Default sort is by `last_updated_at`.


## OpenAPI

````yaml v1/api-reference/sms/sms-collection.json GET /{instance}/messages
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}/messages:
    get:
      tags:
        - Messages
      summary: Index Messages
      description: >-
        ## Index Messages


        This endpoint will index all of the messages sent and recevied based on
        various criteria, including searching my request id and messages
        attributes, with paging limited to 50 messages per response. Default
        sort is by last updated_at.
      operationId: index-messages
      parameters:
        - 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: per_page
          description: 'number of messages per page, max: 50'
          example: ''
        - schema:
            type: string
          in: query
          name: filter[request_id]
          description: user defined string that can retrive message by it
          example: ''
        - schema:
            type: string
          in: query
          name: filter[message_thread_id]
          description: the thread id of the message
          example: ''
        - schema:
            type: string
          in: query
          name: filter[from_phone_number]
          description: message that was sent/recived from phone specified number
          example: ''
        - schema:
            type: string
          in: query
          name: filter[to_phone_number]
          description: message that was sent/recivied from phone specified number
          example: ''
        - schema:
            type: string
          in: query
          name: filter[content]
          description: search by parts of the message
          example: ''
        - schema:
            type: string
          in: query
          name: filter[status]
          description: >-
            pending, scheduled, sending, sent, failed, received, delivered,
            expired, deleted
          example: ''
        - schema:
            type: string
          in: query
          name: filter[type]
          description: sent, received, call_missed
          example: ''
        - schema:
            type: string
          in: query
          name: filter[delivered_at]
          description: >-
            filter by delivery date range down to the minute, comma seprated,
            example: 2025-01-01 00:00:00,2025-01-01 00:20:00
          example: ''
        - schema:
            type: string
          in: query
          name: filter[received_at]
          description: >-
            filter by received date range down to the minute, comma seprated,
            example: 2025-01-01 00:00:00,2025-01-01 00:20:00
          example: ''
        - schema:
            type: string
          in: query
          name: filter[expired_at]
          description: >-
            filter by expired date range down to the minute, comma seprated,
            example: 2025-01-01 00:00:00,2025-01-01 00:20:00
          example: ''
        - schema:
            type: string
          in: query
          name: filter[failed_at]
          description: >-
            filter by failed date range down to the minute, comma seprated,
            example: 2025-01-01 00:00:00,2025-01-01 00:20:00
          example: ''
        - schema:
            type: string
          in: query
          name: filter[schedule_send_at]
          description: >-
            filter by when the message will be sent date range down to the
            minute, comma seprated, example: 2025-01-01 00:00:00,2025-01-01
            00:20:00
          example: ''
        - schema:
            type: string
          in: query
          name: filter[created_at]
          description: >-
            filter by when the message was created on the system. Note: this is
            not the date of message sent or received.  
          example: ''
        - schema:
            type: string
          in: query
          name: filter[updated_at]
          description: 'filter by when the message was last updated. '
          example: ''
        - schema:
            type: string
          in: query
          name: sort
          description: >-
            default: -updated_at, you can sort by any date: 'created_at',
            'updated_at', 'delivered_at', 'received_at', 'expired_at',
            'failed_at', 'schedule_send_at'
          example: ''
        - schema:
            type: string
          in: query
          name: include
          description: >-
            include the phone or messageThread object with the message, possible
            values: phone,messageThread
          example: ''
        - schema:
            type: string
          in: query
          name: page
          description: >-
            when paginating use this property to navigate through pages,
            example: page=2, page=1 and so on..  
          example: ''
      requestBody:
        content: {}
        description: ''
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: hn0uczei49cnq
                    items:
                      $ref: '#/components/schemas/Message'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                Example 1:
                  value:
                    data:
                      - id: 9e01dbc1-1428-46de-b847-c5edd6d4c6f6
                        request_id: 9e01dbc1-14a0-49a7-b22e-248d49b19b37
                        phone:
                          id: 9dedf71e-97bf-47eb-8df5-3088a7865603
                          user_id: 9cbff1d0-6c37-4612-a8bb-6db042991761
                          phone_number: '+20154244114'
                          name: Ahmed Nagi SMS
                          sim: SIM1
                          max_send_attempts: 10
                          message_expiration_seconds: 259200
                          missed_call_auto_reply_message: null
                          is_online: false
                          last_online_at: '2025-01-19 17:36:30'
                          last_offline_at: '2025-01-19 22:48:02'
                          last_message_at: '2025-01-17 20:05:00'
                          last_missed_call_at: '2025-01-17 20:05:00'
                          last_heartbeat_at: '2025-01-19 21:43:43'
                          heartbeat_enabled_at: null
                          timezone: GMT+2
                          created_at: '2025-01-09 20:16:27'
                          updated_at: '2025-01-19 23:48:01'
                        message_thread:
                          id: 9deeebfa-9925-45d1-8b8d-a7004dda411c
                          phone_id: 9dedf71e-8f16-439c-9220-489cd2144e0c
                          last_message_id: 9e01dbc1-1428-46de-b847-c5edd6d4c6f6
                          from_phone_number: Vodafone
                          to_phone_number: '+20154244114'
                          is_archived: false
                          last_message_content: >-
                            2جيجا هدية.ليك منهم 200 ميجا فيسبوك ليومين عشان انت
                            4G. كلم#221*
                          last_message_at: '2025-01-19 10:58:44'
                          created_at: '2025-01-10 07:41:08'
                          updated_at: '2025-01-19 17:36:30'
                        message_thread_id: 9deeebfa-9925-45d1-8b8d-a7004dda411c
                        phone_id: 9dedf71e-97bf-47eb-8df5-3088a7865603
                        from_phone_number: Vodafone
                        to_phone_number: '+20154244114'
                        content: >-
                          2جيجا هدية.ليك منهم 200 ميجا فيسبوك ليومين عشان انت
                          4G. كلم#221*
                        send_duration: null
                        schedule_on_phone_at: null
                        sent_at: null
                        last_attempted_at: null
                        delivered_at: null
                        received_at: '2025-01-19 10:58:44'
                        expired_at: null
                        schedule_send_at: null
                        failed_at: null
                        send_attempt_count: 0
                        max_send_attempts: 10
                        failure_reason: null
                        message_expiration_seconds: 259200
                        timezone: GMT+2
                        sim: SIM1
                        status: received
                        type: received_from_mobile
                        created_at: '2025-01-19 17:36:30'
                        updated_at: '2025-01-19 17:36:30'
                    links:
                      first: >-
                        https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=1
                      last: >-
                        https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=74
                      prev: null
                      next: >-
                        https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=2
                    meta:
                      current_page: 1
                      from: 1
                      last_page: 74
                      links:
                        - url: null
                          label: '&laquo; Previous'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=1
                          label: '1'
                          active: true
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=2
                          label: '2'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=3
                          label: '3'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=4
                          label: '4'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=5
                          label: '5'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=6
                          label: '6'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=7
                          label: '7'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=8
                          label: '8'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=9
                          label: '9'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=10
                          label: '10'
                          active: false
                        - url: null
                          label: ...
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=73
                          label: '73'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&include=phone%2CmessageThread&page=74
                          label: '74'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9dedf71e-97bf-47eb-8df5-3088a7865603/messages?per_page=1&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: 1
                      to: 1
                      total: 74
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
components:
  schemas:
    Message:
      type: object
      properties:
        id:
          type: string
        request_id:
          type: string
        phone:
          type: object
          properties:
            id:
              type: string
            user_id:
              type: string
            phone_number:
              type: string
            name:
              type: string
            sim:
              type: string
            max_send_attempts:
              type: integer
            message_expiration_seconds:
              type: integer
            missed_call_auto_reply_message:
              type: string
            is_online:
              type: boolean
            last_online_at:
              type: string
            last_offline_at:
              type: string
            last_message_at:
              type: string
            last_missed_call_at:
              type: string
            last_heartbeat_at:
              type: string
            heartbeat_enabled_at:
              type: string
            timezone:
              type: string
            created_at:
              type: string
            updated_at:
              type: string
        message_thread:
          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
        message_thread_id:
          type: string
        phone_id:
          type: string
        from_phone_number:
          type: string
        to_phone_number:
          type: string
        content:
          type: string
        send_duration:
          type: string
        schedule_on_phone_at:
          type: string
        sent_at:
          type: string
        last_attempted_at:
          type: string
        delivered_at:
          type: string
        received_at:
          type: string
        expired_at:
          type: string
        schedule_send_at:
          type: string
        failed_at:
          type: string
        send_attempt_count:
          type: integer
        max_send_attempts:
          type: integer
        failure_reason:
          type: string
        message_expiration_seconds:
          type: integer
        timezone:
          type: string
        sim:
          type: string
        status:
          type: string
        type:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      x-examples:
        Example 1:
          id: 9e01dbc1-1428-46de-b847-c5edd6d4c6f6
          request_id: 9e01dbc1-14a0-49a7-b22e-248d49b19b37
          phone:
            id: 9dedf71e-97bf-47eb-8df5-3088a7865603
            user_id: 9cbff1d0-6c37-4612-a8bb-6db042991761
            phone_number: '+20133131313'
            name: Ahmed Nagi SMS
            sim: SIM1
            max_send_attempts: 10
            message_expiration_seconds: 259200
            missed_call_auto_reply_message: null
            is_online: false
            last_online_at: '2025-01-19 17:36:30'
            last_offline_at: '2025-01-19 22:48:02'
            last_message_at: '2025-01-17 20:05:00'
            last_missed_call_at: '2025-01-17 20:05:00'
            last_heartbeat_at: '2025-01-19 21:43:43'
            heartbeat_enabled_at: null
            timezone: GMT+2
            created_at: '2025-01-09 20:16:27'
            updated_at: '2025-01-19 23:48:01'
          message_thread:
            id: 9deeebfa-9925-45d1-8b8d-a7004dda411c
            phone_id: 9dedf71e-8f16-439c-9220-489cd2144e0c
            last_message_id: 9e01dbc1-1428-46de-b847-c5edd6d4c6f6
            from_phone_number: Vodafone
            to_phone_number: '+21388311313'
            is_archived: false
            last_message_content: 2جيجا هدية.ليك منهم 200 ميجا فيسبوك ليومين عشان انت 4G. كلم#221*
            last_message_at: '2025-01-19 10:58:44'
            created_at: '2025-01-10 07:41:08'
            updated_at: '2025-01-19 17:36:30'
          message_thread_id: 9deeebfa-9925-45d1-8b8d-a7004dda411c
          phone_id: 9dedf71e-97bf-47eb-8df5-3088a7865603
          from_phone_number: Vodafone
          to_phone_number: '+203424141333'
          content: 2جيجا هدية.ليك منهم 200 ميجا فيسبوك ليومين عشان انت 4G. كلم#221*
          send_duration: null
          schedule_on_phone_at: null
          sent_at: null
          last_attempted_at: null
          delivered_at: null
          received_at: '2025-01-19 10:58:44'
          expired_at: null
          schedule_send_at: null
          failed_at: null
          send_attempt_count: 0
          max_send_attempts: 10
          failure_reason: null
          message_expiration_seconds: 259200
          timezone: GMT+2
          sim: SIM1
          status: received
          type: received_from_mobile
          created_at: '2025-01-19 17:36:30'
          updated_at: '2025-01-19 17:36:30'
      title: ''
    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
    Error422:
      title: Error422
      x-stoplight:
        id: zsiw2qimxqq2p
      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: '422'
      required:
        - errors
        - message
        - status
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````