v1

latestOpenAPI 3.0.02026-08-067074272.5 KB

Messages

Sends a message

Sends a message through a dashboard in your Text Request account. You can optionally specify a delivery status callback URL to track the status of the message on a third-party site. If a delivery callback URL is specified, you will receive either a delivered callback, or an error callback with a status code explaining the issue. Messages are sent at the throttle rate on your dashboard. The throttle rate is defined as your 10DLC message rate, or at one message per second for non-10dlc registered dashboards.

Scheduling

There are three send modes:

Mode	Fields to include	Response status
Immediate	Omit schedule_date_utc and repeat_settings	"sending"
One-time scheduled	schedule_date_utc only (future UTC)	"scheduled"
Recurring	schedule_date_utc + repeat_settings	"scheduled"

Use the Request body examples in this endpoint for copy-paste payloads covering each repeat mode (daily, weekly with days, monthly, yearly, stop after N sends, stop on date).

See the repeat_settings schema for the full step reference table and repeat mode rules.

Scheduling is not compatible with: authvia_conversation_id, geolocation_requested, or location_callback.

Sent messages can also include Location requests. Location requests are urls sent in texts that contacts can access to send their location to Text Request. This info will be shown in their queue, but can also be sent via a callback to some third-party url.

Location requests can be done in one of two ways:

Set geolocation_requested to true in the request body. This will add the phrase "Go to <text request url> to share your location"
Add the tag [LocationRequest] to your message body. This tag will be replaced by the text request url.

Location requests can also have a callback that is returned when the location request is completed by the contact. This information will be sent as a POST request to the location_callback property. See the callbacks tab below for the schema of the callback.

WARNING: The location_callback property only works with the [LocationRequest] tag. If no tag exsits, even if geolocation_requested is true, the callback will not work and the send-message request will return a 400 (Bad Request) exception.

post/messages

Request body

fromstring required

A ten or eleven digit phone number in your Text Request account that you are sending the message from. This field should be digits only. The country code of "1" is optional. This field is required.

tostring required

The message recipient's ten or eleven digit North American phone number. This field should be digits only. The country code of "1" is optional. This field is required.

bodystring required

The message body. This should be 1600 characters in length or less. If the body exceeds 1600 characters, a 400 bad request will be returned. This field is required.

sender_namestring

Specify who sent this message. This can be any text that is 41 characters or less in length. If this field is omitted, the sender will be listed as 'API'

recipient_namestring

Specify who this message is for. This will change the display_name of the contact within Text Request, so you will know who this is when they respond. This does not update the first_name or last_name fields of the contact.

status_callbackstring uri

A URL that Text Request will callback with message delivery information. See the callbacks tab on /messages and /dashboards/{dashboard_id}/contacts/{phone_number}/messages for the schema of the callback

location_callbackstring uri

A URL that Text Request will callback with contact location information. Requires the insertion of the [LocationRequest] tag in the message body for the link contacts will use. See the callbacks tab on /messages and /dashboards/{dashboard_id}/contacts/{phone_number}/messages for the schema of the callback

mms_mediastring[]

An array of Text Request MMS media urls to access the mms media to be attached and sent with this message (see /mms). This argument is optional and can be omitted, set to null, or set to an empty array.

authvia_conversation_idstring

The Authvia conversation Id for this payment request

geolocation_requestedboolean

Whether the message should include a location request, appended to the end of the message body.

schedule_date_utcstring date-time

UTC timestamp for when the message should be sent. If omitted, the message is sent immediately. Required when repeat_settings is specified. Cannot be used with authvia_conversation_id, geolocation_requested, or location_callback.

Field	Rule
repeat_by	Required. Must be day, week, month, or year (plural forms days, weeks, months, years are also accepted).
step	Required. Must be an integer ≥ 1. See Understanding step below.
schedule_date_utc	Required on the parent request whenever repeat_settings is present. Must be a future UTC timestamp for the first send.

step	repeat_by	Meaning
1	day	Every day
2	day	Every 2 days
3	day	Every 3 days
14	day	Every 14 days
1	week	Every week
2	week	Every 2 weeks (biweekly)
4	week	Every 4 weeks
1	month	Every month (same day of month as schedule_date_utc)
2	month	Every 2 months
3	month	Every 3 months (quarterly)
1	year	Every year (same month/day as schedule_date_utc)
2	year	Every 2 years

Field	Rule
times	Stop after this many total sends (including the first).
end_date	Stop after this UTC date. Must be in the future.
(neither)	The series repeats until you cancel it.

repeat_by	Meaning (N = step)	Extra fields
day	Repeats every N day(s)	—
week	Repeats every N week(s)	Optional days array for specific weekdays
month	Repeats every N month(s) on the same day of month as schedule_date_utc	—
year	Repeats every N year(s) on the same month/day as schedule_date_utc	—

Example request

{
  "body": "Don't forget the Family and Friends sale at our Toledo location on 6-15-2021 at 8:00PM!",
  "sender_name": "Bill Cassidy",
  "recipient_name": "Bruce Wayne",
  "status_callback": "enter-url-here",
  "location_callback": "enter-url-here",
  "schedule_date_utc": "2023-01-12T19:19:11.8032151Z",
  "repeat_settings": {
    "repeat_by": "week",
    "step": 1,
    "times": 5,
    "end_date": "2026-12-31T23:59:59Z",
    "days": [
      "Monday",
      "Wednesday"
    ]
  }
}

Response

The message was received by Text Request and request fields were validated. For immediate sends, the message is being sent and status will be "sending". For scheduled sends, status will be "scheduled" and the message will be sent at schedule_date_utc. This does not mean that the message was successfully delivered - it is possible for a valid message to be rejected and not delivered due to a number of factors such as an invalid recipient, the destination handset being switched off, or if the message is filtered as spam by the receiving carrier. For delivery confirmation, please add a valid webhook URL for the status_callback parameter.

message_idstring

The message's unique identifier.

segments_countinteger

The total number of segments for this message.

fromstring

The eleven digit phone number in your Text Request account that the message was sent from

tostring

The eleven digit phone number that you sent the message to.

status'sending' | 'scheduled' | 'error'

This will be "sending" for immediate sends, "scheduled" when schedule_date_utc is provided, or "error". An error may occur if the phone number is invalid or the recipient has previously opted out.

schedule_date_utcstring date-time

Timestamp of the next scheduled send for this message. Returned when status is "scheduled".

Example response

{
  "message_id": "eb2a0cc2-5b88-468b-b3f4-926b07bcb275",
  "segments_count": 2,
  "status": "sending",
  "schedule_date_utc": "2023-01-12T19:19:11.8032151Z"
}

v1

Sends a message

Scheduling

Request body

Required fields

Understanding step

Optional stop conditions (pick one or neither)

Repeat mode reference

Not allowed

Example request

Response

Example response