Phone

Create a basic route

Creates a new basic route (phone) with external API credentials.

For some external API providers, this method automatically updates webhook URLs configured with the external provider so that incoming messages/calls and call status events are routed to Telerivet. In this case, if you have already configured a webhook URL with the external provider, it will be overwritten. For other external API providers, webhook URLs may require manual configuration in order for the route to be fully functional.

Note: This API can only create routes that connect to external gateway APIs using your own account credentials. To add Android phones, WhatsApp routes, or routes with Telerivet-managed billing, use the web app instead.

Credentials are passed via the external_account_id, external_id, external_secret, and external_config parameters. The meaning of these parameters for each phone type is as follows:

Twilio Virtual Number (phone_type: twilio):

external_id (optional): Twilio phone number SID (starts with 'PN'); looked up by phone_number if not provided
external_account_id (required): Twilio Account SID (starts with 'AC')
external_secret (required): Twilio Auth Token

Twilio Messaging Service (phone_type: twilio_messaging_service):

external_id (required): Twilio messaging service SID (starts with 'MG')
external_account_id (required): Twilio Account SID (starts with 'AC')
external_secret (required): Twilio Auth Token

Twilio Shortcode (phone_type: twilio_shortcode):

external_id (optional): Twilio shortcode SID (starts with 'SC'); looked up by phone_number if not provided
external_account_id (required): Twilio Account SID (starts with 'AC')
external_secret (required): Twilio Auth Token

Twilio Caller ID (phone_type: twilio_caller_id):

external_account_id (required): Twilio Account SID (starts with 'AC')
external_secret (required): Twilio Auth Token

Vonage Virtual Number (phone_type: nexmo):

external_account_id (required): Vonage API Key
external_secret (required): Vonage API Secret

Vonage Sender ID (phone_type: nexmo_sender_id):

external_account_id (required): Vonage API Key
external_secret (required): Vonage API Secret

Telesign SMS (phone_type: telesign):

external_account_id (required): Telesign Customer ID
external_secret (required): Telesign API Key
external_config.message_type: ARN, MKT, or OTP
external_config.sender_type: one_way (default) or two_way

Infobip SMS (phone_type: infobip):

external_account_id (required): Infobip username
external_secret (required): Infobip API key
external_config.sender_type: one_way (default) or two_way
external_config.india_dlt_principal_entity_id: India DLT Principal Entity ID (only for India)

Infobip USSD (phone_type: infobip_ussd):

No external credentials required

Africa's Talking SMS (phone_type: africas_talking):

external_account_id (required): Africa's Talking username
external_secret (required): Africa's Talking API key
external_config.sender_type: one_way (default) or two_way

Africa's Talking USSD (phone_type: africas_talking_ussd):

No external credentials required

Simulated Phone (phone_type: simulated):

No external credentials required
Messages are simulated locally and not sent to any external provider
Useful for testing

Webhook URL Setup

Some route types require manual configuration of callback URLs in the external provider's dashboard. When the Phone response includes an external_setup object, you will need to configure the webhook URLs in your provider's account settings.

The following phone types require manual webhook setup:

africas_talking: message_status_url (always), incoming_message_url (if two_way)
africas_talking_ussd: incoming_call_url
infobip_ussd: incoming_call_url
twilio_messaging_service: incoming_message_url
telesign (two_way only): incoming_message_url

Telerivet automatically configures webhooks for the following phone types as follows:

twilio - automatically updates incoming SMS and voice configuration for the Twilio virtual number associated with the phone_number or external_id parameter
twilio_shortcode - automatically updates incoming SMS configuration for the Twilio short code associated with the phone_number or external_id parameter
nexmo - automatically updates incoming SMS and voice configuration for the Vonage virtual number matching the phone_number parameter
infobip - automatically updates incoming SMS configuration for the Infobip virtual number matching the phone_number parameter or external_id parameter

post/v1/projects/{project_id}/phones

Request

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

namestring

Name of the basic route to create

phone_numberstring required

Phone number or sender ID

phone_typestring required

Type of basic route to create. Supported values: twilio, twilio_messaging_service, twilio_shortcode, twilio_caller_id, nexmo, infobip, africas_talking, africas_talking_ussd, infobip_ussd, telesign, simulated. Other types of basic routes can only be created via the web app.

external_account_idstring

Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). See the description above for the meaning of this parameter for each phone type.

external_idstring

External phone/resource ID within the external API account (if applicable). For twilio and twilio_shortcode routes, this is optional and will be looked up automatically from the phone_number if not provided.

external_secretstring

Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). This value is required when creating a new route but is never returned in API responses. See the description above for the meaning of this parameter for each phone type.

external_configobject

Additional configuration settings specific to the phone_type. See the description above for available settings for each phone type.

countrystring

2-letter country code (ISO 3166-1 alpha-2) where phone is from. This country code is used to automatically convert phone numbers in local format to international format. If not provided, will be set to the organization's country by default.

send_pausedboolean

True if sending messages should initially be paused, false otherwise

timezone_idstring

A string specifying the time zone used when sending messages; see List of tz database time zones Wikipedia article. When not provided, the project's default time zone is used.

validate_recipient_numbersboolean

Set to true to validate recipient phone numbers before sending. Messages to invalid numbers will fail without being sent.

allowed_recipient_countriesstring[]

Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. If not provided, there is no restriction.

send_delaynumber

Number of seconds to wait after sending each message, to avoid exceeding carrier rate limits.

quiet_mode'off' | 'delay' | 'confirm'

Controls behavior during quiet hours. Possible values: 'off' (disabled), 'delay' (messages delayed until quiet hours end), 'confirm' (requires manual confirmation; worker-based routes only).

quiet_startstring

Time when quiet hours begin, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'.

quiet_endstring

Time when quiet hours end, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'.

varsobject

Custom variables and values to set for this basic route

Example request

{
  "name": "Example Route",
  "phone_number": "+14155550123",
  "phone_type": "twilio",
  "external_account_id": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "external_secret": "your_api_secret_here",
  "country": "US",
  "timezone_id": "America/Los_Angeles",
  "send_delay": 1.5,
  "quiet_mode": "delay",
  "quiet_start": "22:00",
  "quiet_end": "08:00"
}

Response

Successful response

idstring

ID of the phone

namestring

Name of the phone

phone_numberstring

Phone number or sender ID

phone_typestring

Type of this phone/route (e.g. android, twilio, nexmo, etc)

countrystring

2-letter country code (ISO 3166-1 alpha-2) where phone is from

send_pausedboolean

True if sending messages is currently paused, false if the phone can currently send messages

time_createdinteger

Time the phone was created in Telerivet

last_active_timeinteger nullable

Approximate time this phone last connected to Telerivet

varsobject

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

project_idstring

ID of the project this phone belongs to

validate_recipient_numbersboolean

Set to true to check that recipient phone numbers appear to be valid before sending messages. Messages to invalid phone numbers will fail without being sent. Only applies to phones capable of sending messages.

allowed_recipient_countriesstring[] nullable

Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. When null, there is no restriction on recipient countries.

sent_message_limitinteger nullable

Maximum number of messages that can be sent from this phone in a given period. When the sent_message_count reaches this limit, sending is automatically paused. Set to null to disable the limit.

sent_message_countinteger

Number of messages sent from this phone since the counter was last reset (see sent_message_epoch). This property is not updated if sent_message_limit is null.

sent_message_epochinteger nullable

The UNIX timestamp when the sent_message_count was last reset to 0.

send_delaynumber nullable

Number of seconds to wait after sending each message from this phone, to avoid exceeding carrier rate limits.

timezone_idstring nullable

A string specifying the time zone that will be used when implementing quiet hours or estimating send times; see List of tz database time zones Wikipedia article. When null, the project's default time zone is used.

quiet_mode'off' | 'delay' | 'confirm'

Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours end), or 'confirm' (requires manual confirmation to send during quiet hours).

quiet_startstring nullable

Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.

quiet_endstring nullable

Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.

batteryinteger nullable

Current battery level, on a scale from 0 to 100, as of the last time the phone connected to Telerivet (only present for Android phones)

chargingboolean nullable

True if the phone is currently charging, false if it is running on battery, as of the last time it connected to Telerivet (only present for Android phones)

internet_typestring nullable

String describing the current type of internet connectivity for an Android phone, for example WIFI or MOBILE (only present for Android phones)

app_versionstring

Currently installed version of Telerivet Android app (only present for Android phones)

android_sdkinteger nullable

Android SDK level, indicating the approximate version of the Android OS installed on this phone; see list of Android SDK levels (only present for Android phones)

mccmncstring

Code indicating the Android phone's current country (MCC) and mobile network operator (MNC); see Mobile country code Wikipedia article (only present for Android phones). Note this is a string containing numeric digits, not an integer.

manufacturerstring

Android phone manufacturer (only present for Android phones)

modelstring

Android phone model (only present for Android phones)

send_limitinteger nullable

Maximum number of SMS messages per hour that can be sent by this Android phone. To increase this limit, install additional SMS expansion packs in the Telerivet Gateway app. (only present for Android phones)

external_account_idstring nullable

Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only present for routes that support external API configuration. See createPhone for the meaning of this field for each phone type.

external_idstring nullable

External phone/resource ID within the external API account (if applicable). Only present for routes that support external API configuration.

external_configobject nullable

Additional configuration settings specific to the phone_type. Only present for routes that support external API configuration. See createPhone for available settings for each phone type.

external_setupobject nullable

Configuration info for routes that require manual webhook setup. Only present for routes that require manual configuration of callback URLs with the external provider. Contains URL properties for each webhook type that needs to be configured (e.g., incoming_message_url, message_status_url, incoming_call_url).

external_secretstring nullable

Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). Only applicable for routes that support external API configuration. Write-only; not returned by the API when retrieving a phone.

urlstring

URL to this phone in the Telerivet web app

Example response

{
  "id": "PN4d246818d0ecd1fa",
  "name": "Android Phone 1",
  "phone_number": "+16505550001",
  "phone_type": "android",
  "country": "TZ",
  "time_created": 1390343779,
  "last_active_time": 1390353800,
  "project_id": "PJ2ad0100821a98bea",
  "validate_recipient_numbers": true,
  "sent_message_limit": 1000,
  "sent_message_count": 150,
  "sent_message_epoch": 1720300000,
  "send_delay": 1.5,
  "timezone_id": "America/Los_Angeles",
  "quiet_mode": "delay",
  "quiet_start": "22:00",
  "quiet_end": "08:00",
  "battery": 95,
  "internet_type": "WIFI",
  "app_version": "3.1.17",
  "android_sdk": 17,
  "mccmnc": "23203",
  "manufacturer": "LGE",
  "model": "Nexus 4",
  "send_limit": 900,
  "url": "https://telerivet.com/p/asdf/phone/PN4d246818d0ecd1fa"
}

Changes

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