API

RingRx exposes all functions via API.

Swagger 

We have a robust REST api documented in Swagger

Authentication 

We make use of JWT Authentication. This means that all requests except an initial login MUST bear a authorization token.

Make sure whatever library you are working is prepared to handle fetching new auth tokens as needed

Obtaining a Token 

Authentication is performed against the POST /auth/token endpoint. Two credential types are supported, both of which return the same token data object on success.

Username and password:: Supply username and password (and otp if the user has two factor authentication enabled). This is the same credential a user logs into the portal with.
API token and secret:: Supply token and secret from an API key. This is the preferred method for integrations and automation. See API Keys for how to create one.

A successful response returns a token data object:

{
  "token_type" : "Bearer",
  "access_token" : "eyJhbGciOiJ...",
  "expires_in" : 3600,
  "refresh_token" : "eyJhbGciOiJ..."
}

access_token:: The JWT to present on all subsequent requests.
refresh_token:: A longer lived token used to obtain a new access token when the current one expires.
expires_in:: The lifetime of the access token, in seconds.
token_type:: The token scheme. Always Bearer.

API keys are the recommended way to authenticate non-interactive integrations. Each key consists of a token and a secret generated under a user’s account, and the resulting access token inherits that user’s role and permissions. See API Keys for details on creating and managing keys.

To authenticate with an API key, exchange the token and secret for an access token:

curl -X POST "https://<your-portal-host>/auth/token?token=<TOKEN>&secret=<SECRET>"

The call returns the same token data object shown above. Take the access_token from the response and present it as a bearer token on every subsequent request:

curl "https://<your-portal-host>/myphones" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Note

Unlike the username/password flow, API token authentication is never subject to a one-time passcode (OTP) challenge, which makes it suitable for unattended use.

Important

Treat the secret like a password. The secret is only shown once when the key is created and cannot be retrieved afterwards. If a key is compromised, delete it (DELETE /myphones/api_key/{token}) and issue a new one. Deleting a key immediately invalidates any access tokens minted from it.

Authorization Header 

Every request other than the initial token request and the refresh request MUST include the access token in the Authorization header using the Bearer scheme:

Authorization: Bearer <ACCESS_TOKEN>

Requests made without a valid token, or with an expired token, are rejected with a 401 Not Authenticated response.

Refreshing a Token 

Access tokens are short lived. Rather than re-submitting credentials, exchange the refresh_token for a fresh access token using POST /auth/refresh:

curl -X POST "https://<your-portal-host>/auth/refresh?refresh_token=<REFRESH_TOKEN>"

A successful refresh returns a new token data object. Your client should detect a 401 (or anticipate expiry using expires_in) and refresh transparently before retrying the original request. If the refresh token is itself invalid or expired, re-authenticate from the beginning via POST /auth/token.

Full request and response schemas for all of the above are documented in Swagger

Callbacks 

RingRx supports a robust callback system to allow you to build out your own integrations based upon receiving events from us. Callbacks can be configured from our existing REST api as documented in Swagger

Each callback is completely configurable with token replacements from the object being sent

`Name`

This is a descriptive name for the callback and will be used inside audit logs.

`Callback Type`

This is what kind of callback is being configured (these are described in more detail below)

sms:: This configures a callback that can be bound to a Phone Number. When that phone number receives an SMS this callback is triggered. This type of callback can be bound to multiple phone numbers
voicemail:: This configures a callback that can be bound to a mailbox. When a voicemail (only voice not fax) is deposited in that mailbox this callback is triggered. This type of callback can be bound to multiple mailboxes
fax:: This configures a callback that can be bound to a fax services. When a fax is received, this callback is triggered. This type of callback can be bound to multiple fax services.
cdr:: This callback is global. It will generate an event for EVERY call that is completed by the customer. Take care not to configure many of these.
recording:: This callback is global. It will generate an event for EVERY call that has a recording attached to it. Take care not to configure many of these.
outreach:: This configures a callback subscription to a specific outreach profile. The destination will receive updates to all events attached to that subscription including creation, updates and dispostioning of outreach events.
call_alert:: This configures a callback subscription to real-time call events passing through a configured group.

`URL`

this is the URL destination of the callback. This field MAY contain tokens in the URL or as part of the parameters.

`Basic Auth`

If “Use Basic Auth” is set to true then we will sent the username and password configured

Use basic auth:: Boolean
auth_username:: the basic auth username to be transmitted. This field is NOT token replaced
auth_password:: the basic auth password to be transmitted. This field it NOT token replaced

`Custom Headers`

You can add any custom headers to the request you wish. These headers will be token replaced.

Headers are parsed one per line (/r/n between) with header and value split by a colon :

Example:: AuthToken:DESIGN-thick-because-guard

Note

Custom headers can be a great way to validate and authenticate inbound callback requests

Token Replacement 

To allow for maximum customization of callback events to your system each event type can be configured with an array of tokens that will be replaced by values from the event. This should be used in the URL and headers to customize what you receive.

Voicemail example:: https://some.url.com/voicemail?accountID=some_account&calling_number={caller}&filename={filename}&recipient={called}&mailbox={mailbox}

In the above example

{caller}:: Will be replaced by the calling number
{called}:: Will be replaced by the called number
{filename}:: Will be replaced by the actual transmitted file name
{mailbox}:: Will be replaced by the mailbox that collected this message

SMS 

SMS Callbacks are configured on phone number objects and will execute only for inbound messages received by that number.

For SENDING SMS messages consult the Swagger documentation at Swagger

SMS Callbacks are sent a JSON Post messages

METHOD:: POST
BODY:: JSON body as below

{
  "from" : "8185551234",
  "to" : "8185559876",
  "message" : "Test callback",
  "timestamp" : "2019-02-15T23:48:54+00:00",
  "uuid" : "6ed8654e-a9d1-4a7c-9502-581210d0985f"
}

Available tokens are:

Token	Description
{from}	The number sending the SMS message
{to}	The number receiving the SMS message
{message}	The text body of the sms message
{timestamp}	The timestamp in GMT that the message was received

Voicemail 

Voicemail Callbacks are sent a POST messages with the file in the body

METHOD:: POST
BODY:: voicemail file
CONTENT-TYPE:: mime type of the body payload

Token	Description
{id}	The unique identifier of the message
{caller}	The calling number leaving the message
{called}	The number called prior to the call going to voicemail
{duration}	The duration of the message
{filename}	The filename contained in the body
{mailbox}	The mailbox that the voicemail was deposited in
{created_at}	Date and Time in GMT the message was left

Fax 

Fax Callbacks are sent a POST messages with the file in the body

METHOD:: POST
BODY:: fax file
CONTENT-TYPE:: mime type of the body payload

Token	Description
{id}	The unique identifier of the fax
{caller}	The sending number transmitting the fax
{called}	The number the fax was sent to
{pages }	The page count of the fax
{filename}	The filename contained in the body
{mailbox}	The mailbox that the voicemail was deposited in
{created_at}	Date and Time in GMT the message was received

CDR 

CDR Callbacks are configured globally and will execute for each and every call in the organization

CDR Callbacks are sent a JSON Post messages

METHOD:: POST
BODY:: JSON object of Call detail record

Available tokens are:

Token	Description
{id}	The unique id of the CDR
{domain_name}	The account domain
{aleg_uuid}	The unique identifier of the A leg of the call
{responsible_party}	Who “owns” this cdr
{start_time}	Timestamp of the beginning of the call
{hangup_cause}	What the final disposition of the call was
{dialed_digits}	Originally dialed digits (can change as call is routed
{calling_party}	Originator of the call
{caller_id_number}	CallerID number as transmitted or received
{caller_id_name}	CallerID name as transmitted or received
{duration}	Call total duration (includes ringing)
{bill_duration}	Call duration from answered
{direction}	Call direction (inbound, outbound, internal)
{mailbox}	If the call went to voicemail, which mailbox
{aleg_holdtime}	If the a_leg was placed on hold, for how long(total)
{bleg_holdtime}	If the b_leg was placed on hold, for how long(total)
{tags}	Comma separated list of tags applied to the call

Recording 

Recording Callbacks are configured globally and will execute for each and every recorded call in the organization

Recording Callbacks are sent a JSON Post messages

METHOD:: POST
BODY:: JSON object of Call detail record with new recording

Available tokens are:

Token	Description
{id}	The unique id of the CDR
{domain_name}	The account domain
{aleg_uuid}	The unique identifier of the A leg of the call
{responsible_party}	Who “owns” this cdr
{start_time}	Timestamp of the beginning of the call
{hangup_cause}	What the final disposition of the call was
{dialed_digits}	Originally dialed digits (can change as call is routed
{calling_party}	Originator of the call
{caller_id_number}	CallerID number as transmitted or received
{caller_id_name}	CallerID name as transmitted or received
{duration}	Call total duration (includes ringing)
{bill_duration}	Call duration from answered
{direction}	Call direction (inbound, outbound, internal)
{mailbox}	If the call went to voicemail, which mailbox
{aleg_holdtime}	If the a_leg was placed on hold, for how long(total)
{bleg_holdtime}	If the b_leg was placed on hold, for how long(total)
{tags}	Comma separated list of tags applied to the call

Outreach 

Outreach Callbacks are configured per-profile and will execute for all events attached to that profile.

Outreach Callbacks are sent a JSON Post messages

METHOD:: POST
BODY:: JSON object of Outreach Event

Available tokens are:

Token	Description
{id}	The unique id of the Event
{name}	The entered “Name” on the event
{phonenumber}	The phone number used for Voice\|SMS
{email_address}	The Email used for Email events
{call_state}	The status of the voice path of the event
{sms_state}	The status of the sms path of the event
{email_state}	The status of the email path of the event
{confirmed}	Boolean. The recipient has confirmed this event
{cancelled}	Boolean. The recipient has cancelled this event
{reminder_date}	The Date and Time of the event
{attempt}	Which Voice attempt we are on
{voice}	Boolean. This event will be notified via Call
{sms}	Boolean. This event will be notified via SMS
{email}	Boolean. This event will be notified via Email
{event_log}	Array. A log of all the attempts and responses

Call_Alert 

Call_Alert Callbacks are configured per-group and will be sent for each call being handled by that group just prior to EACH time the group offers a call to a user. This may mean you receive multiple call backs for the same call as it progresses through sequential offerings to each user on a group.

Call_Alert Callbacks are sent a JSON Post messages

METHOD:: POST
BODY:: JSON object of Call_Alert Event

{
  "uuid" : "5bab4386-14a6-46ea-b200-6e47a91837cb",
  "created_at" : "1709075290020813",
  "callback_id" : 99,
  "domain_name" : "customer.ringrx.com",
  "originally_dialed_number" : "+18885439876",
  "dialed_number" : "8000",
  "caller_number" : "+18185551234",
  "caller_nname" : "Dr Smith",
  "tags" : "inbound,reception_queue",
  "dialed_user_emails" : "ssmith@gmail.us,jjones@hotmail.us",
  "dialed_users" : "ssmith,jjones"
}

Available tokens are:

Token	Description
{uuid}	The unique id of the call
{created_at}	The unix timestamp when the call was begun
{callback_id}	The ID of the callback being executed
{domain_name}	The domain name of the customer
{originally_dialed_number}	The originally called number
{dialed_number}	The current dialed number/extension
{caller_number}	The caller id number of the caller
{caller_name}	The caller id name of the caller
{tags}	Comma separated list of tags applied to the call
{dialed_users}	Comma separated list of users or ext about to be dialed