Message

Send a message to a group

Sends a text message (optionally with mail-merge templates) or voice call to a group or a list of up to 500 phone numbers.

With message_type=service, invokes an automated service (such as a poll) for a group or list of phone numbers. Any service that can be triggered for a contact can be invoked via this method, whether or not the service actually sends a message.

If Message Review is enabled for the project and the broadcast requires approval (because it exceeds the project's review threshold, or because the project requires approval for messages sent via AI tools), the broadcast will not be sent immediately; instead, it will be submitted for review as a scheduled message, and will be sent when a reviewer approves it. In this case, the response will contain status=pending_review, scheduled_message_id, and url (a link to the approval page in the web app) properties instead of the normal broadcast properties (no id property will be returned). The project's message_review property (returned by getProjectById) shows in advance whether sends will require approval.

post/v1/projects/{project_id}/send_broadcast

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/send_broadcast
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://telerivet.com/oauth/authorize, token URL https://api.telerivet.com/oauth/token)

Path parameters

project_idstring required

ID of the Project

Request body

message_typestring

Type of message to send. If text, will use the default text message type for the selected route.

contentstring

Content of the message to send

group_idstring

ID of the group to send the message to

to_numbersstring[]

List of up to 500 phone numbers to send the message to

route_idstring

ID of the phone or route to send the message from

titlestring

Title of the broadcast. If a title is not provided, a title will automatically be generated from the recipient group name or phone numbers.

status_urlstring

Webhook callback URL to be notified when message status changes

status_secretstring

POST parameter 'secret' passed to status_url

label_idsstring

Array of IDs of labels to add to all messages sent (maximum 5). Does not apply when message_type=service, since the labels are determined by the service itself.

exclude_contact_idstring

Optionally excludes one contact from receiving the message (only when group_id is set)

replace_variablesboolean

Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)

track_clicksboolean

If true, URLs in the message content will automatically be replaced with unique short URLs.

short_link_paramsobject

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

varsobject

Custom variables to set for each message

route_paramsobject

Route-specific parameters for the messages in the broadcast.

When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons.

For more details, see Route-Specific Parameters.

service_idstring

Service to invoke for each recipient (when message_type is call or service)

audio_urlstring

The URL of an MP3 file to play when the contact answers the call (when message_type is call).

If audio_url is provided, the text-to-speech voice is not used to say content, although you can optionally use content to indicate the script for the audio.

For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.

tts_lang'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE'

The language of the text-to-speech voice (when message_type is call)

tts_voice'female' | 'male'

The name of the text-to-speech voice (when message_type=call)

Example request

{
  "content": "hello [[contact.name]]!",
  "status_url": "https://example.com/sms_status.php",
  "status_secret": "t0psecr3t",
  "replace_variables": true
}

Response

Successful response

idstring

ID of the broadcast

recipientsobject[]

List of recipients. Each recipient is an object with a string type property, which may be "phone_number", "group", or "filter".

If the type is "phone_number", the phone_number property will be set to the recipient's phone number.

If the type is "group", the group_id property will be set to the ID of the group, and the group_name property will be set to the name of the group.

If the type is "filter", the filter_type property (string) and filter_params property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the filter_type or filter_params properties, as they may change without notice.)

titlestring

Title of the broadcast. If a title was not provided when the broadcast was sent, it is automatically set to a human readable description of the first few recipients (possibly truncated)

time_createdinteger

Time the broadcast was sent in Telerivet

last_message_timeinteger nullable

Time the most recent message was queued to send in this broadcast

last_send_timeinteger nullable

Time the most recent message was sent (or failed to send) in this broadcast, or null if no messages have been sent yet

status_countsobject

An object whose keys are the possible status codes ("queued", "sent", "failed", "failed_queued", "delivered", "not_delivered", and "cancelled"), and whose values are the number of messages in the broadcast currently in that status.

message_countinteger

The total number of messages created for this broadcast. For large broadcasts, the messages may not be created immediately after the broadcast is sent. The message_count includes messages in any status, including messages that are still queued.

estimated_countinteger

The estimated number of messages in this broadcast when it is complete. The estimated_count is calculated at the time the broadcast is sent. When the broadcast is completed, the estimated_count may differ from message_count if there are any blocked contacts among the recipients (blocked contacts are included in estimated_count but not in message_count), if any contacts don't have phone numbers, or if the group membership changed while the broadcast was being sent.

num_partsnumber nullable

The total number of SMS parts that have been sent in this broadcast. The number of SMS parts does not include messages that are still queued, or messages that failed to send.

message_type'sms' | 'mms' | 'ussd' | 'ussd_session' | 'call' | 'chat' | 'service'

Type of message sent from this broadcast

contentstring

The text content of the message (null for USSD messages and calls)

audio_urlstring

For voice calls, the URL of an MP3 file to play when the contact answers the call

tts_lang'en-US' | 'en-GB' | 'en-GB-WLS' | 'en-AU' | 'en-IN' | 'da-DK' | 'nl-NL' | 'fr-FR' | 'fr-CA' | 'de-DE' | 'is-IS' | 'it-IT' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ru-RU' | 'es-ES' | 'es-US' | 'sv-SE'

For voice calls, the language of the text-to-speech voice

tts_voice'female' | 'male'

For voice calls, the text-to-speech voice

replace_variablesboolean

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

status'queuing' | 'sending' | 'complete' | 'cancelled' | 'pending_review'

The current status of the broadcast. pending_review is returned by sendBroadcast when Message Review is enabled and the broadcast was submitted for review instead of being sent; in that case the response contains a scheduled_message_id property instead of the other broadcast properties.

source'phone' | 'provider' | 'web' | 'api' | 'service' | 'webhook' | 'scheduled' | 'integration' | 'mcp' | 'welcome'

How the message originated within Telerivet

simulatedboolean

Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)

track_clicksboolean

If true, URLs in the message content will automatically be replaced with unique short URLs.

clicked_countinteger nullable

The number of messages in this broadcast containing short links that were clicked. At most one click per message is counted. If track_clicks is false, this property will be null.

label_idsstring

List of IDs of labels applied to all messages in the broadcast

varsobject

Custom variables stored for this broadcast. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

route_paramsobject nullable

Route-specific parameters for the messages in the broadcast.

When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons.

For more details, see Route-Specific Parameters.

pricenumber nullable

The total price of all messages in this broadcast, if known.

price_currencystring

The currency of the message price, if applicable.

reply_countinteger

The number of replies received in response to a message sent in this broadcast. (Replies are not included in message_count ,status_counts, or price.)

last_reply_timeinteger nullable

Time the most recent reply was received in response to a message sent in this broadcast, or null if no replies have been sent yet

route_idstring

ID of the phone or route used to send the broadcast (if applicable)

service_idstring

The service associated with this broadcast (for voice calls, the service defines the call flow)

urlstring nullable

URL to this broadcast in the Telerivet web app

user_idstring

ID of the Telerivet user who sent the broadcast (if applicable)

project_idstring

ID of the project this broadcast belongs to

is_templateboolean

Set to true if Telerivet will render variables like [[contact.name]] in the message content

recipients_strstring

A string with a human readable description of the first few recipients (possibly truncated)

Example response

{
  "id": "MB2489812e59c5c781",
  "title": "+16505550123, Subscribers, Contact Filter",
  "time_created": 1390348075,
  "last_message_time": 1390348085,
  "last_send_time": 1390348086,
  "message_count": 8358,
  "estimated_count": 12942,
  "num_parts": 12321,
  "message_type": "sms",
  "content": "Hello [[contact.name]]!",
  "replace_variables": true,
  "status": "queuing",
  "source": "service",
  "clicked_count": 12,
  "price": 13.34,
  "price_currency": "USD",
  "reply_count": 43,
  "last_reply_time": 1390348132,
  "route_id": "RT2a586298d3412adf",
  "service_id": "SV3d246818d0e3d1fb",
  "url": "https://telerivet.com/p/asdf/broadcast/MB2489812e59c5c781",
  "user_id": "URba3e403e98f49735",
  "project_id": "PJ2ad0100821a98bea"
}

Changes

No recorded changes to this operation across all 1 revision of this API.