--- title: "Sends a message" method: POST path: "/messages" tags: ["Messages"] --- # Sends a message `POST /messages` 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 *\* 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. ## Request body - PostMessageRequest — Send a 1:1 message. For scheduling examples, use the **Request body** examples on POST /messages. For repeat mode rules, see the **repeat_settings** schema. - `from` string, 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. - `to` string, 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. - `body` string, 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_name` string — 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_name` string — 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_callback` string, 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_callback` string, 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_media` string[] — 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_id` string — The Authvia conversation Id for this payment request - `geolocation_requested` boolean — Whether the message should include a location request, appended to the end of the message body. - `schedule_date_utc` string, 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. - `repeat_settings` RepeatSettings — Controls how a scheduled message repeats. Only include this when creating a **recurring** message; one-time scheduled sends use **schedule_date_utc** alone. ### Required fields | 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. | ### Understanding step **`step`** is the number **N** in "every N {repeat_by units}". It only has meaning together with **`repeat_by`** — the unit comes from `repeat_by`, and `step` says how many of those units between sends. | 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 | **Weekly + days:** When **repeat_by** is `week` and **days** is set (e.g. `["Monday", "Wednesday"]`), **step** is the gap between *weeks* that contain sends. `step: 1` = Mon/Wed every week; `step: 2` = Mon/Wed on alternate weeks only. **First send:** Always at **schedule_date_utc**. Later sends follow the interval above. ### Optional stop conditions (pick one or neither) | 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. | **You cannot set both `times` and `end_date` in the same request.** ### Repeat mode reference | 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** | — | ### Not allowed * **repeat_settings** without **schedule_date_utc** * **schedule_date_utc** or **end_date** in the past * **step** omitted or `0` * **times** and **end_date** together * Invalid **repeat_by** values * Scheduling with **authvia_conversation_id**, **geolocation_requested**, or **location_callback** (on 1:1 send endpoints) - `repeat_by` 'day' | 'week' | 'month' | 'year', required — The unit of time between sends. Accepted values: `day`, `week`, `month`, `year` (plural forms are also accepted by the API). - `step` integer, required — How many **repeat_by** units between sends (the **N** in "every N days/weeks/months/years"). Examples: `step: 1` + `repeat_by: day` = daily; `step: 14` + `repeat_by: day` = every 14 days; `step: 2` + `repeat_by: week` = biweekly; `step: 3` + `repeat_by: month` = quarterly. Must be ≥ 1. See the **repeat_settings** schema for the full table. - `times` integer — Stop the series after this many total sends (including the first). **Mutually exclusive with end_date.** Omit both **times** and **end_date** to repeat until cancelled. - `end_date` string, date-time — UTC timestamp after which no further sends occur. Must be in the future. **Mutually exclusive with times.** - `days` string[] — Only applies when **repeat_by** is `week`. Limits sends to these weekdays. Day names are case-insensitive (e.g. `Monday` or `monday`). ## Response `200` 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. - PostMessageResponse - `message_id` string — The message's unique identifier. - `segments_count` integer — The total number of segments for this message. - `from` string — The eleven digit phone number in your Text Request account that the message was sent from - `to` string — 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_utc` string, date-time — Timestamp of the next scheduled send for this message. Returned when status is "scheduled". ## Other responses - `400` — Bad request. Sent if required properties are omitted or invalid. Check the return value to determine the reason that the message was rejected. - `401` — Unauthorized. Sent if the API key is omitted or invalid. --- [API](https://skmtc.net/textrequest/apis/text-request-api-v3.md) · [All operations](https://skmtc.net/textrequest/apis/text-request-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/textrequest/text-request-api-v3/revisions/e4e42efcd650/schema)