--- title: "Create a new group message." method: POST path: "/dashboards/{dashboard_id}/groupmessages" tags: ["Group Messages"] --- # Create a new group message. `POST /dashboards/{dashboard_id}/groupmessages` Create a regular, scheduled, or recurring group message. | Mode | Fields to include | |------|-------------------| | **Immediate** | Omit `schedule_date_utc` and `repeat_settings` | | **One-time scheduled** | `schedule_date_utc` only (future UTC) | | **Recurring** | `schedule_date_utc` + `repeat_settings` | See the **repeat_settings** schema for repeat mode rules and allowed values. ## Path parameters - `dashboard_id` integer, required ## Request body - PostGroupMessageRequest - `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. - `phone_numbers` string[] — The phone numbers this group message is sending to. You can use this in conjunction with group_ids. You must include either this or group_ids for the request to be valid. This cannot be more than 5,000 contacts. - `group_ids` integer[] — The group ids of the groups this group message is sending to. You can use this in conjunction with phone_numbers. You must include either this or phone_numbers for the request to be valid. If you wish to send a group message to more than 5,000 contacts, you must use this and not phone_numbers. - `excluded_phone_numbers` string[] — The phone numbers this group message should not send to. This is useful if you want to send to a group, but you want to exclude a few contacts. - `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 — Timestamp of the next scheduled send for this message. If this timestamp is in the past, the message has been sent and is completed. - `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 custom field object. - GroupMessageIdContainer - `id` string — This will be a Guid that you can use to make API calls on the group message. ## Other responses - `400` — Bad request. Sent if too many custom fields alreay exist for this dashboard, or invalid parameters were passed. - `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)