Sign in

v1

latestOpenAPI 3.0.02026-08-067074272.5 KB
Conversations
Messages

Send a message to the contact with the given phone number

Sends a message (starting a new conversation if the given phone number has no message history). You can optionally specify a delivery status callback URL to track the status of the message on a third-party site. Upon successful execution, delivery_status will be "sending" for immediate sends or "scheduled" when schedule_date_utc is provided. 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

ModeFields to includeResponse delivery_status
ImmediateOmit schedule_date_utc and repeat_settings"sending"
One-time scheduledschedule_date_utc only (future UTC)"scheduled"
Recurringschedule_date_utc + repeat_settings"scheduled"

Use the Request body examples dropdown for scheduling payloads. See the repeat_settings schema for the full step reference table and repeat mode rules.

Scheduling is not compatible with: 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/dashboards/{dashboard_id}/contacts/{phone_number}/messages

Path parameters

dashboard_idinteger required
Example:121

Id of dashboard

phone_numberstring required

Phone number

Request body

bodystring

The message's text.

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'

status_callbackstring uri

A URL that Text Request will callback with message delivery information. See https://app.swaggerhub.com/apis/Text-Request/Text-Request/3.0#/delivery_status_callback for the schema of the callback

location_callbackstring uri

A URL that Text Request will callback with location information. See https://app.swaggerhub.com/apis/Text-Request/Text-Request/3.0#/delivery_location_callback 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.

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

Example request

{
  "body": "I am reaching back out.",
  "sender_name": "Bill Cassidy",
  "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 new message.

message_idstring

The message's unique identifier.

bodystring

The message's text.

message_directionstring

The message direction. R if the message was sent from the contact's phone, S if the message was sent from the dashboard.

response_by_usernamestring

Name of Text Request user that sent the most recent message response

message_timestamp_utcstring date-time

Timestamp of when the message was queued to be sent.

delivery_status'accepted' | 'queued' | 'sending' | 'scheduled' | 'error' | 'sent' | 'failed' | 'undelivered' | 'delivered'

Message's current delivery state. Will be "scheduled" when the message was created with schedule_date_utc.

schedule_date_utcstring date-time

When the message is scheduled to send. Present when delivery_status is "scheduled".

delivery_errorstring

An alphanumeric error code that can be used for reference when troubleshooting. This will be null if the status is "sending".

mms_mediastring[]

An array of MMS media urls to access the mms media that was attached and sent with this message.

Example response

{
  "message_id": "eb2a0cc2-5b88-468b-b3f4-926b07bcb275",
  "body": "I am reaching back out.",
  "message_direction": "S",
  "response_by_username": "John Doe",
  "delivery_status": "sending",
  "schedule_date_utc": "2026-07-15T14:30:00Z",
  "delivery_error": "2005",
  "mms_media": [
    "https://textrequeststorage.com/182739/3fd60fc2-1759-4dee-ac6f-4a97b994b84f.jpeg",
    "https://textrequeststorage.com/182739/c89c8c6a-8883-44cd-b833-f8b4dc8fbba4.png"
  ]
}