# Send bulk messages

Send messages in bulk on Twilio SMS, Twilio WhatsApp or Gupshup WhatsApp channel.
You can also send an image, a video or a file.
Calling this API will create a bulk messaging job, which you can also see and update on app.sociocs.com -> Bulk messaging -> History.

# Method

POST

# Path

/messages/bulk

# Body parameters

Name	Value	Data type	Required?
provider	`twlo` (for Twilio SMS), `twlowa` (for Twilio WhatsApp), `gswa` (for Gupshup WhatsApp)	String	Yes
channel_key	Channel key value from Profile & settings -> API	String	Yes
recipients	Array of object `{to: "phone_number", name: "recipient_name"}`	String	Yes
text	Message text	String	No (when image_url, image_urls or file_url is present)
image_url	Publicly accessible image URL	String	No (when text, video_url or file_url is present)
video_url	Publicly accessible video URL	String	No (when text, image_url or file_url is present)
file_url	Publicly accessible file URL	String	No (when text, image_url or video_url is present)
duplicates_allowed	`true` - Send message to duplicate phone numbers (if there are any), `false` - Send message only once per phone number (first occurrence)	Boolean	No (defaults to false)
schedule	ISO 8601 date & time (e.g., "2006-01-02T15:04:05-04:00"). If the value is in the past, messages will be sent immediately.	String	No

# Response

# HTTP status codes

Code	Remarks
200	Request was successful.
400	Validation error or request body was incorrectly formatted.
401	Authentication failed. Check `apikey` header.
404	Requested API endpoint not found.
429	The rate limit has been reached.
500-511	There was a problem processing the request on our server. Try again later.

# Response object

Name	Value	Remarks
status	`success` or `error`	-
errors	Array of object `{ msg: [error detail] }`	Only present when status is `error`.
data	Object `{ job_id: [bulk messaging job id] }`	Only present when status is `success`.

# Code sample

curl --location --request POST 'https://api.sociocs.com/messages/bulk' \
--header 'apikey: your_api_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "provider": "twlo",
    "channel_key": "your_channel_key",
    "recipients": [
        {
            "to": "phone_number_1",
            "name": "recipient_name_1"
        },
        {
            "to": "phone_number_2",
            "name": "recipient_name_2"
        }
    ],
    "text": "message",
    "schedule: "2023-12-25T11:00:00-04:00"
}'