API¶

RingRx exposes all functions via API.

Swagger
Authentication
Callbacks
- Name
- Callback Type
- URL
- Basic Auth
- Custom Headers
- Token Replacement
- SMS
- Voicemail
- Fax
- CDR
- Recording
- Outreach
- Call_Alert

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

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