Message

Send a message

Sends one message (SMS, MMS, chat app message, voice call, or USSD request).

If Message Review is enabled for the project and this message requires approval (because the project requires approval for messages sent via AI tools, or its review threshold is 0 or its daily or monthly review budget is exhausted), the message 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 message properties. The project's message_review property (returned by getProjectById) shows in advance whether sends will require approval.

post/v1/projects/{project_id}/messages/send

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/messages/send
  • 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_type'text' | 'sms' | 'mms' | 'ussd' | 'call' | 'chat' | 'service'

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 (if message_type is call, the text will be spoken during a text-to-speech call)

to_numberstring

Phone number to send the message to

contact_idstring

ID of the contact to send the message to

route_idstring

ID of the phone or route to send the message from

status_urlstring

Webhook callback URL to be notified when message status changes

status_secretstring

POST parameter 'secret' passed to status_url

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.

route_paramsobject

Route-specific parameters for the message.

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.

label_idsstring

List of IDs of labels to add to this message

varsobject

Custom variables to store with the message

priority1 | 2

Priority of the message. Telerivet will attempt to send messages with higher priority numbers first (for example, so you can prioritize an auto-reply ahead of a bulk message to a large group).

simulatedboolean

Set to true to test the Telerivet API without actually sending a message from the route

service_idstring

Service that defines the call flow of the voice call (when message_type is call)

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 world",
  "to_number": "+16505550123"
}

Response

Successful response

idstring

ID of the message

direction'incoming' | 'outgoing'

Direction of the message: incoming messages are sent from one of your contacts to your phone; outgoing messages are sent from your phone to one of your contacts

status'ignored' | 'processing' | 'received' | 'sent' | 'queued' | 'failed' | 'failed_queued' | 'cancelled' | 'delivered' | 'not_delivered' | 'read'

Current status of the message

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

Type of the message

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

How the message originated within Telerivet

time_createdinteger

The time that the message was created on Telerivet's servers

time_sentinteger nullable

The time that the message was reported to have been sent (null for incoming messages and messages that have not yet been sent)

time_updatedinteger

The time that the message was last updated in Telerivet.

from_numberstring

The phone number that the message originated from (your number for outgoing messages, the contact's number for incoming messages)

to_numberstring

The phone number that the message was sent to (your number for incoming messages, the contact's number for outgoing messages)

contentstring

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

starredboolean

Whether this message is starred in Telerivet

simulatedboolean

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

label_idsstring

List of IDs of labels applied to this message

route_paramsobject nullable

Route-specific parameters for the message.

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.

variantinteger nullable

For outgoing messages sent with variants, the index (starting at 0) of the variant used to send the message. Undefined if the default message body was used.

varsobject

Custom variables stored for this message. 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.

priorityinteger

Priority of this message. Telerivet will attempt to send messages with higher priority numbers first. Only defined for outgoing messages.

send_attemptsnumber nullable

The number of times Telerivet has attempted to send the message. Will be greater than 1 if the message has been resent. Only defined for outgoing messages.

error_messagestring

A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.)

error_codestring

A route-specific error code encountered while sending a message. The error code values depend on the provider and may be described in the provider's API documentation. Error codes may be strings or numbers, depending on the provider. (This field is omitted from the API response if there is no error code.)

external_idstring

The ID of this message from an external SMS gateway provider (e.g. Twilio or Vonage), if available.

num_partsnumber nullable

The number of SMS parts associated with the message, if applicable and if known.

pricenumber nullable

The price of this message, if known.

price_currencystring

The currency of the message price, if applicable.

durationnumber nullable

The duration of the call in seconds, if known, or -1 if the call was not answered.

ring_timenumber nullable

The length of time the call rang in seconds before being answered or hung up, if known.

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

track_clicksboolean

If true, URLs in the message content are short URLs that redirect to a destination URL.

network_codestring

A string identifying the network that sent or received the message, if known. For mobile networks, this string contains the 3-digit mobile country code (MCC) followed by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit number. For lists of mobile network operators and their corresponding MCC/MNC values, see Mobile country code Wikipedia article. The network_code property may be non-numeric for messages not sent via mobile networks.

time_clickedinteger

If the message contains any short URLs, this is the first time that a short URL in the message was clicked. This property is undefined for messages that do not contain short URLs.

service_idstring

ID of the service that handled the message (for voice calls, the service defines the call flow)

phone_idstring

ID of the phone (basic route) that sent or received the message

contact_idstring

ID of the contact that sent or received the message

route_idstring

ID of the custom route that sent the message (if applicable)

broadcast_idstring

ID of the broadcast that this message is part of (if applicable)

scheduled_idstring

ID of the scheduled message that created this message is part of (if applicable)

user_idstring

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

project_idstring

ID of the project this contact belongs to

urlstring

URL to the message detail page in the Telerivet web app

Example response

{
  "id": "SM1629708e59c5c781",
  "direction": "outgoing",
  "status": "sent",
  "message_type": "sms",
  "source": "service",
  "time_created": 1390347812,
  "time_sent": 1390347814,
  "time_updated": 1390347818,
  "from_number": "+16505550001",
  "to_number": "+16505550123",
  "content": "Thank you for registering!",
  "starred": true,
  "priority": 1,
  "send_attempts": 1,
  "external_id": "142092393",
  "num_parts": 1,
  "price": 0.01,
  "price_currency": "USD",
  "service_id": "SV3d246818d0e3d1fb",
  "phone_id": "PN4d246818d0ecd1fa",
  "contact_id": "CTa1299c3d0e371023",
  "route_id": "RT2a586298d3412adf",
  "broadcast_id": "MB98918598dab29800",
  "scheduled_id": "SEa502e6f9d23f1cb6",
  "user_id": "URba3e403e98f49735",
  "project_id": "PJ2ad0100821a98bea",
  "url": "https://telerivet.com/p/asdf/message/SM1629708e59c5c781"
}

Changes

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