The RingRx API can be used to integrate existing 3rd party services with RingRx
API
RingRx exposes all functions via API.
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
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. |
| 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. |
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 |