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

# SMS Heartbeats API (v1)

> Index heartbeats of the phone sorted by last heartbeat. (v1 API)

Index heartbeats of the phone sorted by last heartbeat.

You can filter by various attributes, and this endpoint is paginated.


## OpenAPI

````yaml v1/api-reference/sms/sms-collection.json GET /{instance}/heartbeats
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/v2/hypersender/overview/sms/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}/heartbeats:
    get:
      tags:
        - Heartbeats
      summary: Heartbeats
      description: |-
        ## Heartbeats

        Index heartbeats of the phone sorted by last heartbeat.

        You can filter by various attributes, and this endpoint is paginated.
      operationId: heartbeats
      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[app_version]
          description: >-
            filter by the android application version that was installed on your
            phone
          example: ''
        - schema:
            type: integer
          in: query
          name: filter[battery_level]
          description: filter by percentage of the battery
          example: ''
        - schema:
            type: boolean
          in: query
          name: filter[is_charging]
          description: filter by wither the phone was charging or not
          example: ''
        - schema:
            type: string
          in: query
          name: filter[local_timestamp]
          description: get heartbeats by the local time of the phone
          example: ''
        - schema:
            type: string
          in: query
          name: filter[created_at]
          description: 'filter by when the heartbeat was created on the system.  '
          example: ''
        - schema:
            type: string
          in: query
          name: sort
          description: >-
            default: -created_at, you can sort by any date: 'created_at',
            'local_timestamp'
          example: ''
        - schema:
            type: string
          in: query
          name: include
          description: 'include the phone object with the heartbeat, possible values: phone'
          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: {}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    x-stoplight:
                      id: azw8l9gqq0f36
                    items:
                      $ref: '#/components/schemas/Heartbeat'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                Example 1:
                  value:
                    data:
                      - id: 9e05f90c-affd-4e8f-967d-811a19ec575f
                        phone_id: 9defcf1e-552c-4bef-a843-872edec576ef
                        battery_level: 96
                        is_charging: false
                        local_timestamp: '2025-01-21 18:41:42'
                        app_version: null
                        created_at: '2025-01-21 18:41:43'
                        updated_at: '2025-01-21 18:41:43'
                    links:
                      first: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=1
                      last: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=72
                      prev: null
                      next: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=2
                    meta:
                      current_page: 1
                      from: 1
                      last_page: 72
                      links:
                        - url: null
                          label: '&laquo; Previous'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=1
                          label: '1'
                          active: true
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=2
                          label: '2'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=3
                          label: '3'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=4
                          label: '4'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=5
                          label: '5'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=6
                          label: '6'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=7
                          label: '7'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=8
                          label: '8'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=9
                          label: '9'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=10
                          label: '10'
                          active: false
                        - url: null
                          label: ...
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=71
                          label: '71'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=72
                          label: '72'
                          active: false
                        - url: >-
                            https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats?per_page=1&page=2
                          label: Next &raquo;
                          active: false
                      path: >-
                        https://beta.hypersender.com/api/sms/v1/9defcf1e-552c-4bef-a843-872edec576ef/heartbeats
                      per_page: 1
                      to: 1
                      total: 72
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '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:
    Heartbeat:
      type: object
      properties:
        id:
          type: string
        phone_id:
          type: string
        battery_level:
          type: integer
        is_charging:
          type: boolean
        local_timestamp:
          type: string
        app_version:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      x-examples:
        Example 1:
          id: 9e05f90c-affd-4e8f-967d-811a19ec575f
          phone_id: 9defcf1e-552c-4bef-a843-872edec576ef
          battery_level: 96
          is_charging: false
          local_timestamp: '2025-01-21 18:41:42'
          app_version: v1.3.0
          created_at: '2025-01-21 18:41:43'
          updated_at: '2025-01-21 18:41:43'
    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
    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
    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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.