Message

Add an incoming message

Add an incoming message to Telerivet. Acts the same as if the message was received by a phone. Also triggers any automated services that apply to the message.

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

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/messages/receive
  • 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

contentstring

Content of the incoming message

message_type'sms' | 'call' | 'chat'

Type of message

from_numberstring required

Phone number that sent the incoming message

phone_idstring required

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

to_numberstring

Phone number that the incoming message was sent to

simulatedboolean

If true, Telerivet will not send automated replies to actual phones

starredboolean

True if this message should be starred

label_idsstring

Array of IDs of labels to add to this message (maximum 5)

varsobject

Custom variables to set for this message

Example request

{
  "content": "help",
  "message_type": "sms",
  "from_number": "+16505550193",
  "to_number": "+16505551212"
}

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.