--- title: "Send a message to the contact with the given phone number" method: POST path: "/dashboards/{dashboard_id}/contacts/{phone_number}/messages" tags: ["Conversations", "Messages"] --- # Send a message to the contact with the given phone number `POST /dashboards/{dashboard_id}/contacts/{phone_number}/messages` 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 | Mode | Fields to include | Response delivery_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 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 ** 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. ## Path parameters - `dashboard_id` integer, required - `phone_number` string, required ## Request body - ContactMessageRequest — Send a message to a specific contact. For scheduling examples, use the **Request body** examples on POST /dashboards/{dashboard_id}/contacts/{phone_number}/messages. For repeat mode rules, see the **repeat_settings** schema. - `body` string — The message's text. - `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' - `status_callback` string, 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_callback` string, 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_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. - `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 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 new message. - Message - `message_id` string — The message's unique identifier. - `body` string — The message's text. - `message_direction` string — 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_username` string — Name of Text Request user that sent the most recent message response - `message_timestamp_utc` string, 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_utc` string, date-time — When the message is scheduled to send. Present when delivery_status is "scheduled". - `delivery_error` string — An alphanumeric error code that can be used for reference when troubleshooting. This will be null if the status is "sending". - `mms_media` string[] — An array of MMS media urls to access the mms media that was attached and sent with this message. ## Other responses - `400` — Bad request. Some required parameters were missing. - `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)