> ## 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.
# Send Message
> Send a new SMS message to be sent by your android phone.
Send a new SMS message to be sent by your android phone, you can schedule it up to 3 days in the future relative to your defined phone timezone.
you can also specify an unique request id that you can use later to search for this message.
## Quick Demo
**Learn how to use Hypersender SMS API to send a message using Postman:** [Demo Link](api-reference/sms/how-to-send-sms-message-in-postman.mdx)
## OpenAPI
````yaml v1/api-reference/sms/sms-collection.json POST /{instance}/send-message
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.
**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.**
**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}/send-message:
post:
tags:
- Messages
summary: Send Message
description: >
## Send Message
Send a new SMS message to be sent by your android phone, you can
schedule it up to 3 days in the future relative to your definied phone
timezone.
you can also specifiy an unique request id that you can use later to
search for this message.
operationId: send-message
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 }}'
requestBody:
content:
application/json:
schema:
type: object
x-examples:
Example 1:
content: test send message
request_id: 133554b5-ae44-44a0-8f4f-7bbac5657a11
to: '+201122061032'
schedule_send_at: '2025-01-08 19:47:00'
max_send_attempts: 10
message_expiration_seconds: 100
properties:
content:
type: string
description: >-
The content of your SMS message, keep it short and sweet
because sms messages done like to be short!
request_id:
type: string
description: >-
any string preferably uuid that you can use later to find
this message.
to:
type: string
description: >-
phone number that you want to send the message to.
Make sure that it start with + and have country code
example: +203123131313
schedule_send_at:
type: string
description: >-
optional date in the future max: 3 days that the message
will be sent Relative to your defined Timezone! Example:
2025-01-08 19:47:00
max_send_attempts:
type: integer
description: >-
How many times I should retry sending this message when it
fails to be sent, Max: 15 times.
message_expiration_seconds:
type: integer
description: >-
How many seconds this message is valid for, this is usefull
when you are sending OTPs with expiration of 2 mins.
required:
- content
- to
examples:
Example 1:
value:
content: v
request_id: 133554b5-ae44-44a0-8f4f-7bbac5657a11
to: '+1119122018'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
Example 1:
value:
id: string
request_id: string
phone:
id: string
user_id: string
phone_number: string
name: string
sim: string
max_send_attempts: 0
message_expiration_seconds: 0
missed_call_auto_reply_message: null
is_online: true
last_online_at: string
last_offline_at: string
last_message_at: string
last_missed_call_at: string
last_heartbeat_at: string
heartbeat_enabled_at: null
timezone: string
created_at: string
updated_at: string
message_thread:
id: string
phone_id: string
last_message_id: string
from_phone_number: string
to_phone_number: string
is_archived: true
last_message_content: string
last_message_at: string
created_at: string
updated_at: string
message_thread_id: string
phone_id: string
from_phone_number: string
to_phone_number: string
content: string
send_duration: null
schedule_on_phone_at: null
sent_at: null
last_attempted_at: null
delivered_at: null
received_at: string
expired_at: null
schedule_send_at: null
failed_at: null
send_attempt_count: 0
max_send_attempts: 0
failure_reason: null
message_expiration_seconds: 0
timezone: string
sim: string
status: string
type: string
created_at: string
updated_at: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'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: ''
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
Error404:
title: Error500
x-stoplight:
id: 9j9buxw3w3pig
type: object
properties:
message:
type: string
x-stoplight:
id: 5rbetqawbxxn7
example: Not Found
required:
- message
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
````