---
title: "Send SMS, MMS or WhatsApp to a Segment"
method: POST
path: "/orgunit/{orgunitId}/groups/{groupId}/messages/segment"
tags: ["Send"]
---

# Send SMS, MMS or WhatsApp to a Segment

`POST /orgunit/{orgunitId}/groups/{groupId}/messages/segment`

## Request

- Base URL: `https://api-docs.ministrybytext.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.ministrybytext.com/orgunit/{orgunitId}/groups/{groupId}/messages/segment`
- Auth: none declared
- TypeScript: <https://skmtc.dev/ministrybytext/apis/pbt-api-documentation/docs/orgunit/:orgunitId/groups/:groupId/messages/segment/post.ts> (a function with typed inputs; its response is checked against the schema)

To send an SMS, MMS or WhatsApp to only a few subscribers in a group, you can either upload a CSV file through the Upload file for segment API and attach the file URL in the segment API, attach an array of ListIds, or pass subscriberNumbers in the request body schema.

**Audience Resolution Precedence Logic:**
1. If 'segmentSubscriberFileUrl' is provided, the system processes the CSV file and completely ignores both 'listIds' and 'subscriberNumbers'.
2. If 'segmentSubscriberFileUrl' is null/omitted and 'listIds' is provided, the system delivers the message to the specified segment lists and ignores 'subscriberNumbers'.
3. If both 'segmentSubscriberFileUrl' and 'listIds' are null/omitted, the system defaults to sending the message directly to the array of numbers provided in 'subscriberNumbers'.

Supports multi-channel delivery including SMS, MMS (requires pre-uploading media files to attach a valid 'mediaPath'), 
and WhatsApp (requires an approved WhatsApp template layout).

## Path parameters

- `orgunitId` string, required
- `groupId` string, required

## Request body

- SegmentMessageRequest
  - `from` string: The sending entity identifier or group name displayed to the recipient in the message's start.
  - `message` string, required: The raw text payload to be delivered to subscribers. Leave empty or omit if you are utilizing a pre-configured template layout via 'templateId'.
  - `templateId` string, nullable: The unique identifier of a message template. When passed, the system will deliver the structured template message layout. For sending WHATSAPP broadcast, this field is mandatory.
  - `type` 'BroadcastMessage'
  - `mediaDetails` MediaDetails
    - `mediaPath` MediaPath[], nullable
      - `fileName` string
      - `extension` string
      - `fileSaveId` string
      - `mimetype` string
      - `url` string
  - `referenceId` string, nullable: An optional external tracking or transaction identifier used to correlate this transmission with your internal database records.
  - `subscriberNumbers` string[], nullable: An array of specific destination mobile phone numbers. Used to isolate delivery to individual subscribers instead of the entire group list.
  - `segmentSubscriberFileUrl` string, nullable: Url of csv file containing specific destination mobile phone numbers. Used to isolate delivery to individual subscribers instead of the entire group list.
  - `listIds` object[], nullable: An array of list objects targeting specific segment lists for audience delivery.
    - `ListId` string, required: The unique identifier of the target segment list.
  - `channelType` 'SMS' | 'MMS' | 'WHATSAPP': Specifies the target communication network channel for delivery. Accepted values include SMS, MMS, or WHATSAPP.
  - `fallbackMessage` FallbackMessage
    - `from` string, nullable
    - `message` string
    - `channelType` string

## Response `201`

Success

- SegmentMessageResponseExternalApiResponseNew
  - `data` SegmentMessageResponse
    - `referenceId` string, nullable
  - `appCode` string, nullable
  - `message` string, nullable
  - `isError` boolean

## Other responses

- `400`: Bad Request

## Changes

- **2026-08-18** `ae1e3ddfb2fb`: 1 breaking, 1 info
  - the request property `message` became required
  - added the new optional request property `listIds`

[Operation history](https://skmtc.dev/ministrybytext/apis/pbt-api-documentation/changes/orgunit/:orgunitId/groups/:groupId/messages/segment/post.md)

---

[API](https://skmtc.dev/ministrybytext/apis/pbt-api-documentation.md) - [All operations](https://skmtc.dev/ministrybytext/apis/pbt-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/ministrybytext/apis/pbt-api-documentation/revisions/7d64a1f0b0c3?raw)