RingPlan API

Scroll down for code samples, example requests and responses.

Welcome to documentation for RingPlan API.

The current API URL is https://ssp-backend.ringplan.com.

RingPlan API is built upon REST and each request is based on the HTTP methods of GET, PUT, POST, PATCH and DELETE. All you need to have in order to access the API is an HTTP client capable of using these methods, setting HTTP headers as well as sending JSON payloads. In addition, RingPlan provides a WebSocket API.

Example Python snippets using the requests library are provided for you in the column on the right. WebSocket examples are given in JavaScript using the Socket.IO library.

This document is structured in the following main sections:

• Overview, which you are reading right now, explaining the structure of the document.

• Guides, containing tutorials and walkthroughs for common use-cases of this API.

• REST, for descriptions of REST API endpoints with examples.

• WebSocket, for descriptions of WebSocket API endpoints with examples.

• Objects, where fields and uses of internal objects are described.

Guide

Example request headers for a specific contact

API_KEY = 'secret_string'
headers = {
  'Authorization': 'Bearer ' + API_KEY
  'X-User-Id': '60190ce750fe88ed1a544a7a'
}

Example request headers for the primary contact

API_KEY = 'secret_string'
headers = {
  'Authorization': 'Bearer ' + API_KEY
  'X-User-Id': 'primary'
}

RingPlan REST API supports OAuth-based authentication, using the Authorization header, whose value must be Bearer followed by the company's API key. API keys can be obtained from the Self Service Portal. Each API key is tied to a single company. The user sending the request provides their contact id with the X-User-Id header.

Each company has a special user with administrator permissions named primary.

Any user in the company (including the primary user) can be impersonated with the X-User-Id header.

REST

Constant values for examples

import requests

API_URL = 'https://ssp-backend.ringplan.com'
API_KEY = 'secret string'
USER_ID = 'id of acting user'

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer ' + API_KEY,
  'X-User-Id': USER_ID
}

Each endpoint supplies status codes in conformance with RFC 7231.

Endpoint return values are described in the Responses section. If they return ad hoc objects, the fields are described separately under said section.

Error messages are always in the following format:

All methods will return 401 Unauthorized for failed authorization due to invalid or missing API_KEY or X-User-Id headers.

Company

company endpoints

Get company information

Get the current company

request = requests.get(API_URL + '/system/company', headers = headers)

print(request.json())

GET /system/company

Return the company object of the company the given user belongs to.

Responses

Update company

Update the current company

headers['X-User-Id'] = 'primary'

body = {
  'name': 'New Company',
  'email': 'new@example.net'
}

request = requests.patch(API_URL + '/company', headers = headers, json = body)

print(request.json())

PATCH /company

Partially update the company the current user belongs to.

Parameters

Responses

Users

contact endpoints

Get users in company

Return users in current company with given work email

query = {
  'work_email': 'sales@example.com'
}

request = requests.get(API_URL + '/system/company/contacts', headers = headers, params = query)

print(request.json())

GET /system/company/contacts

Return the list of users that share the same company as the current user, optionally filtered and sorted by query parameters.

Parameters

Responses

Add user to company

Add new user to current company

headers['X-User-Id'] = 'primary'

body = {
  'first_name': 'Jane',
  'contacts': {
    'email': 'janedoe@example.com'
  }
}

request = requests.post(API_URL + '/company/contacts', headers = headers, json = body)

print(request.json())

POST /company/contacts

Create a new user, add it to the current company and return the contact object. Only the company owner, i.e the primary user, is allowed to create new users.

Parameters

Responses

Update user

Updating a user's details

contact_id = '60190ce750fe88ed1a544a7a'

headers['X-User-Id'] = contact_id

body = {
  'emergency_contact_number': '15554441234',
  'last_name': 'Smith'
}

request = requests.patch(API_URL + '/company/contacts/' + contact_id, headers = headers, json = body)

print(request.json())

PATCH /company/contacts/{contact_id}

Partially update contact with the provided contact_id and return the updated contact object.

Parameters

Responses

Delete user

Deleting a user from the company

contact_id = '60190ce750fe88ed1a544a7a'

headers['X-User-Id'] = 'primary'

request = requests.delete(API_URL + '/company/contacts/' + contact_id, headers = headers)

print(request.json())

DELETE /company/contacts/{contact_id}

Delete the given user in the current company.

Parameters

Responses

Locations

location endpoints

Get company locations

Get the list of locations belonging to the company

request = requests.get(API_URL + '/company/locations', headers = headers)

print(request.json())

GET /company/locations

Return the list of locations for the current company.

Responses

Add location to company

Add a second location to the company

body = {
  'name': 'Second Location',
  'country': 'United States',
  'state': 'California',
  'city': 'Carlsbad',
  'zip': '92008',
  'company_id': '611ced1255c44a89f8df7cc0'
}

headers['X-User-Id'] = 'primary'

request = requests.post(API_URL + '/company/locations', headers = headers, json = body)

print(request.json())

POST /company/locations

Create a new location, add it to the current company and return it.

Parameters

Responses

Update company locations

Partially update a company location

location_id = '61254e7ecbe793d0e26c7996'

headers['X-User-Id'] = 'primary'

body = {
  'name': 'Old Location'
}

request = requests.patch(API_URL + '/company/locations/' + location_id, \
  headers = headers, json = body)

print(request.json())

PATCH /company/locations/{location_id}

Partially update the given location with the provided request body data.

Parameters

Responses

Delete location

Delete a location from the company

location_id = '61254e7ecbe793d0e26c7996'

headers['X-User-Id'] = 'primary'

request = requests.delete(API_URL + '/company/locations/' + location_id, headers = headers)

print(request.json())

DELETE /company/locations/{location_id}

Delete the given location.

Parameters

Responses

Instances

instance endpoints

Get instances

Get the list of all instances in the company

request = requests.get(API_URL + '/instances', headers = headers)

print(request.json())

GET /instances

Return the list of PBX instances available to the company.

Responses

Extensions

extension endpoints.

Get extensions

Get the third page of an instance's softphone extensions, sorted by user names

instance_uuid = '279951a6-4f51-5019-a897-0e7624828abf'

query = {
  'by_user': 'on',
  'filter_by': 'softphone',
  'page': 3
}

request = requests.get(API_URL + '/instances/' + instance_uuid + '/bulks/extensions', \
  headers = headers, params = query)

print(request.json())

GET /instances/{instance_uuid}/bulks/extensions

Return the list of extensions by PBX ID.

Parameters

Enumerated Values

Responses

Response Headers

Add new extensions

Add a new extension to an instance

instance_uuid = '79951a6-4f51-5019-a897-0e7624828abf'

body = {
  'data': {
    'id': 1123,
    'name': 'Test',
    'description': null,
    'voicemail_email': 'voice@example.com',
    'outboundcid': null
  },
  'location_id': '60190fb650fe88ed1a544a85',
  'purpose': 'mobile-app'
}

request = requests.post(API_URL + '/instances/' + instance_uuid + '/bulks/extensions', \
  headers = headers, json = body)

print(request.json())

POST /instances/{instance_uuid}/bulks/extensions

Add a new extension to the given PBX instance and the database.

Parameters

Responses

Get all extensions assigned to a user

Get all softphone extensions assigned to a user

contact_id = '60190ce750fe88ed1a544a7a'

query = {
  'purpose': 'softphone'
}

request = requests.get(API_URL + '/account/' + contact_id + '/extensions', \
  headers = headers, params = query)

print(request.json())

GET /account/{contact_id}/extensions

Get the list of extensions assigned to the given user.

Parameters

Enumerated Values

Responses

Find extensions

Find the fifth page of unassigned extensions on an instance

instance_uuid = '79951a6-4f51-5019-a897-0e7624828abf'

query = {
  'filter_by': 'unassigned',
  'page': 5
}

request = requests.get(API_URL + '/instances/' + instance_uuid + '/extensions', \
  headers = headers, params = query)

print(request.json())

GET /instances/{instance_uuid}/extensions

Return the list of extensions, optionally filtered and sorted by query parameters.

Parameters

Enumerated Values

Responses

Check user extension assignments

Check for duplicate extensions on a given user

instance_uuid = '79951a6-4f51-5019-a897-0e7624828abf'

body = {
  'email': 'john@example.com',
  'id': 1001
}

request = requests.post(API_URL + '/instances/' + instance_uuid + '/bulks/extensions/check', \
  headers = headers, json = body)

print(request.json())

POST /instances/{instance_uuid}/bulks/extensions/check

Check possible duplicate assignments for extensions.

Parameters

Responses

Update extension

Replace an extension

body = new_extension

instance_uuid = '79951a6-4f51-5019-a897-0e7624828abf'
extension_id = '61254e7f884ca03e99ba0dfe'

request = requests.put(API_URL + '/instances/' + instance_uuid + '/bulks/extensions/' + extension_id, \
  headers = headers, json = body)

print(request.json())

PUT /instances/{instance_uuid}/bulks/extensions/{extension_id}

Update details for the given extension.

Parameters

Responses

Delete extension

Delete an extension from a given instance

instance_uuid = '79951a6-4f51-5019-a897-0e7624828abf'
extension_id = '61254e7f884ca03e99ba0dfe'

request = requests.delete(API_URL + '/instances/' + instance_uuid + '/bulks/extensions/' + extension_id, \
  headers = headers)

print(request.json())

DELETE /instances/{instance_uuid}/bulks/extensions/{extension_id}

Delete the given extension from the PBX instance and the database.

Parameters

Responses

Get extension configuration by ID

Get extension configuration

query = {
  'instance_uuid': '79951a6-4f51-5019-a897-0e7624828abf',
  'extension_id': '61254e7f884ca03e99ba0dfe'
}

request = requests.get(API_URL + '/phones/qr-config/advanced', headers = headers, params = query)

print(request.json())

GET /phones/qr-config/advanced

You can use that configuration to connect extension with any VoIP softphone

Parameters

Texting - Conversations

conversation endpoints.

Get all conversations

Get conversations

request = requests.get(API_URL + '/texting/conversations, headers = headers)

print(request.json())

GET /texting/conversations

Get all conversations in the company.

Parameters

Response Headers

Search conversations

Search for text within conversations

query = {
  'text': 'Development Talks'
}

request = requests.get(API_URL + '/texting/conversations/search', headers = headers, params = query)

print(request.json())

GET /texting/conversations/search

Get messages from all conversations in the company by text search.

Parameters

Responses

Create new conversations

Create a conversation

body = {
  'contact_id': '615717df4b8fa06267cd2f6f',
  'from_number': '1235551234'
}

request = requests.post(API_URL + '/texting/conversations', headers = headers, json = body)

print(request.json())

POST /texting/conversations

Create a new conversation.

Parameters

Responses

Delete conversations

Delete a conversation

conversation_id = '616566b94b8fa0626751ef96'

request = requests.delete(API_URL + '/texting/conversations/` + conversation_id, headers = headers)

print(request.json())

DELETE /texting/conversations/{conversation_id}

Delete the given conversation with all the messages in it.

Parameters

Responses

Texting - Messages

message endpoints

Get messages from conversation

Fetch the third page of messages from a conversation

conversation_id = '616566b94b8fa0626751ef96'

query = {
  'page': 3
}

request = requests.get(API_URL + '/texting/conversations/' + conversation_id + '/messages', \
  headers = headers, params = query)

print(request.json())

GET /texting/conversations/{conversation_id}/messages

Get messages from a given conversation.

Parameters

Response Headers

Mark message as read

Mark a specific message in a conversation as seen

body = {
  'is_read': True
}

conversation_id = '615717df4b8fa06267cd2f73'
message_id = '615717dfaea77fef6ace1bbf'

request = requests.patch(API_URL + '/texting/conversations/' + conversation_id + '/messages/' + message_id, \
  headers = headers, json = body)

print(request.json())

PATCH /texting/conversations/{conversation_id}/messages/{message_id}

Update a message in a conversation as read.

Parameters

Responses

Send outbound message

Send a message

conversation_id = '615717df4b8fa06267cd2f73'

body = {
  'text': 'Hello world!'
}

request = requests.post(API_URL + '/texting/conversations/' + conversation_id + '/messages/publish', \
  headers = headers, json = body)

print(request.json())

POST /texting/conversations/{conversation_id}/messages/publish

Send an SMS or MMS message.

Parameters

Responses

Get messages in conversation

Get the ten latest messages in a conversation

query = {
  'per_page': 10,
  'page': 1
}

conversation_id = '615717df4b8fa06267cd2f73'

request = requests.get(API_URL + '/texting/conversations/' + conversation_id + '/messages', \
  headers = headers, params = query)

print(request.json())

GET /texting/conversations/{conversation_id}/messages

Return the list of messages in the given conversation.

Parameters

Responses

Response Headers

Delete messages in conversation

Delete two specific messages in a conversation

query = {
  'ids': ['61656c90730737f190ed288a', '615717dfaea77fef6ace1bbf']
}

conversation_id = '615717df4b8fa06267cd2f73'

request = requests.delete(API_URL + '/texting/conversations/' + conversation_id + '/messages', \
  headers = headers)

print(request.json())

DELETE /texting/conversations/{conversation_id}/messages

Delete multiple messages in given conversation.

Parameters

Responses

Texting - Contacts

texting contact endpoints

Create texting contact

Create a new contact for texting

body = {
  'number': '+12340009999'
}
request = requests.post(API_URL + '/texting/contacts', headers = headers, json = body)

print(request.json())

POST /texting/contacts

Create a texting contact. A company_id field will be added automatically.

Parameters

Responses

Get texting contacts

Find texting contacts named Jane

query = {
  'search': 'Jane'
}

request = requests.get(API_URL + '/texting/contacts', headers = headers, params = query)

print(request.json())

GET /texting/contacts

Return the list of texting contacts.

Parameters

Responses

Get texting contact by ID

Get a texting contact

texting_contact_id = '61254ea54b8fa062670a3fb1'

request = requests.get(API_URL + '/texting/contacts/' + texting_contact_id, headers = headers)

print(request.json())

GET /texting/contacts/{texting_contact_id}

Get texting contact by ID.

Parameters

Responses

Update texting contact

Replace a texting contact

texting_contact_id = '61254ea54b8fa062670a3fb1'

body = {
  'number': '11235554321'
}

request = requests.put(API_URL + '/texting/contacts/' + texting_contact_id, \
  headers = headers, json = body)

print(request.json())

PUT /texting/contacts/{texting_contact_id}

Update texting contact. company_id parameter will be added automatically.

Parameters

Responses

Texting - Numbers

texting number endpoints

Get texting numbers

Get available texting numbers

query = {
  'numformat': 'international'
}

request = requests.get(API_URL + '/texting/numbers', headers = headers, params = query)

print(request.json())

GET /texting/numbers

Return texting numbers owned by the current user.

Parameters

Enumerated Values

Example response

[
  {
    "company_id": "611ced1255c44a89f8df7cc0",
    "id": "61254e814b8fa062670a3e14",
    "number": "+18273717273",
    "ownership": [
      "janedoe@example.com"
    ]
  }
]

Responses

Update number ownership

Assign two email addresses to a texting number

number = '3215551234'

body = ['janedoe@example.com', 'johnsmith@example.com']

request = requests.put(API_URL + '/texting/numbers/' + number, headers = headers, json = body)

print(request.json())

PUT /texting/numbers/{number}

Update the owner emails of the texting number for the given number.

Parameters

Responses

Voicemails

voicemail endpoints

Get voicemails

Get the third page of voicemails from extensions 1001 to 1002

query = {
  'extension_source': 1001,
  'extension_destination': 1002,
  'page': 3
}

request = requests.get(API_URL + '/voicemail/messages/', headers = headers, params = query)

print(request.json())

GET /voicemail/messages

Return the list of all available voicemails, optionally filtered and sorted with query parameters.

Parameters

Responses

Response Headers

Fax - Destinations

destination endpoints

Create fax destination

Create new destination

body = {'emails': ['myfax@example.com']}

request = requests.post(API_URL + '/fax/destinations', headers = headers, json = body)

print(request.json())

POST /fax/destinations

Create a new destination for fax messages.

Parameters

Responses

Fax - Messages

fax message endpoints

Get inbound fax messages

Get messages from a specific sender with a specific subject between certain dates

query = {
  'name': 'Alyssa',
  'subject': 'Payment Details',
  'start_date': '2021-11-01T18:00:00',
  'end_date': '2021-06-01T09:00:00'
}

request = requests.get(API_URL + '/fax/messages/inbound', headers = headers, params = query)

print(request.json())

GET /fax/messages/inbound

Return the list of inbound fax messages, optionally filtered and sorted by paremeters.

Parameters

Responses

Response Headers

Delete an inbound fax message

Delete an inbound message

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.delete(API_URL + '/fax/messages/inbound/' + fax_message_id, headers = headers)

print(request.json())

DELETE /fax/messages/inbound/{fax_message_id}

Delete the given fax message.

Parameters

Responses

Update an inbound fax message

Partially update an inbound fax message

body = {
  'to_name': 'Alice'
}

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.patch(API_URL + '/fax/messages/inbound/' + fax_message_id, \
  headers = headers, json = body)

print(request.json())

PATCH /fax/messages/inbound/{fax_message_id}

Partially update the given inbound fax message.

Parameters

Responses

Get outbound fax messages

Get messages to a specific recipient with a specific subject between certain dates

query = {
  'name': 'Bob',
  'subject': 'Status Update',
  'start_date': '2021-11-01T18:00:00',
  'end_date': '2021-06-01T09:00:00'
}

request = requests.get(API_URL + '/fax/messages/outbound', headers = headers, params = query)

print(request.json())

GET /fax/messages/outbound

Return the list of outbound fax messages, optionally filtered and sorted by paremeters.

Parameters

Responses

Response Headers

Send a new fax message

Create an outbound message

body = {
  'emails': 'bob@example.com',
  'file': {'id': '30b19a2ff4cb9e50ac109eae'},
  'from': '2052726012',
  'from_name': 'Alice',
  'subject': 'Update my contact details',
  'to': '8584375000',
  'to_name': 'Bob'
}

request = requests.post(API_URL + '/fax/messages/outbound', headers = headers, json = body)

print(request.json())

POST /fax/messages/outbound

Create a new outbound fax message and send it.

Parameters

Responses

Delete an outbound fax message locally

Delete an outbound message

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.delete(API_URL + '/fax/messages/outbound/' + fax_message_id, headers = headers)

print(request.json())

DELETE /fax/messages/outbound/{fax_message_id}

Delete the local data for the given outbound fax message.

Parameters

Responses

Update a failed fax message

Update an outbound message before it is resent

body = {
  'to': '8584375001'
}

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.put(API_URL + '/fax/messages/outbound/' + fax_message_id, \
  headers = headers, json = body)

print(request.json())

PUT /fax/messages/outbound/{fax_message_id}

Update an outbound fax message that has failed.

Parameters

Responses

Retry a failed fax message

Resend outbound message

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.post(API_URL + '/fax/messages/outbound/' + fax_message_id + '/retry', \
  headers = headers)

print(request.json())

POST /fax/messages/outbound/{fax_message_id}/retry

Resend an outbound fax message that has failed.

Parameters

Responses

Get scheduled fax messages

Get scheduled messages to a specific number created before a certain date

query = {
  'number': '3215551234',
  'end_date': '2021-06-01T09:00:00'
}

request = requests.get(API_URL + '/fax/messages/scheduled', headers = headers, params = query)

print(request.json())

GET /fax/messages/scheduled

Return the list of fax messages scheduled for sending, optionally filtered and sorted by paremeters.

Parameters

Responses

Response Headers

Schedule a new fax message

Create new message to be sent at a given date

body = {
  'emails': 'bob@example.com',
  'file': {'id': '30b19a2ff4cb9e50ac109eae'},
  'from': '2052726012',
  'from_name': 'Alice',
  'subject': 'Remember to update my contact details',
  'to': '8584375000',
  'to_name': 'Bob',
  'send_at': '2021-11-15T09:00:00' # Time of schedule
}

request = requests.post(API_URL + '/fax/messages/scheduled', headers = headers, json = body)

print(request.json())

POST /fax/messages/scheduled

Create a new outbound fax message and schedule it for sending.

Parameters

Responses

Cancel a scheduled fax message

Delete a scheduled message

fax_message_id = '7081e68fcebe251d6b612fb2'

request = requests.delete(API_URL + '/fax/messages/scheduled/' + fax_message_id, headers = headers)

print(request.json())

DELETE /fax/messages/scheduled/{fax_message_id}

Delete a scheduled fax message before it could be sent.

Parameters

Responses

Update a scheduled fax message

Update a message before it can be sent

body = {
  'subject': 'Update my contact details (important!)'
}

fax_message_id = 'a8f3260b07657b92121973fc'

request = requests.put(API_URL + '/fax/messages/scheduled/' + fax_message_id, \
  headers = headers, json = body)

print(request.json())

PUT /fax/messages/scheduled/{fax_message_id}

Update a scheduled fax message.

Parameters

Responses

Get fax statistics

Get fax message statistics for the company

request = requests.get(API_URL + '/fax/statistics', headers = headers)

print(request.json())

GET /fax/statistics

Return the numbers of total fax messages in the company.

Responses

On 200 OK:

Fax - Numbers

Get fax numbers

Get all fax numbers

request = requests.get(API_URL + '/fax/numbers', headers = headers)

print(request.json())

GET /fax/numbers

Return the list of all fax numbers available in the company.

Responses

Meet - Authentication

Get calendar for current user

Get calendar

request = requests.get(API_URL + '/meet/app/calendar', headers = headers)

print(request.json())

GET /meet/app/calendar

Return the Google Calendar details for the current contact.

Responses

On 200 OK:

Get meeting link

Get URL for specified meeting

meeting_id = '214824405'

request = requests.get(API_URL + '/meet/app/calendar/events/get-link/' + meeting_id, \
  headers = headers)

print(request.json())

GET /meet/app/calendar/events/get-link/{meeting_id}

Return a meeting URL object for the given meeting ID.

Parameters

Responses

On 200 OK:

Get Google Calendar authentication link

Get Google Calendar OAuth2 link

request = requests.get(API_URL + '/meet/app/calendar/get-auth-url', headers = headers)

print(request.json())

GET /meet/app/calendar/get-auth-url

Return the Google Calendar OAuth2 authentication URL object for the current contact.

Responses

On 200 OK:

Get Outlook Calendar authentication link

Get Outlook Calendar OAuth2 link

request = requests.get(API_URL + '/meet/app/outlook/get-auth-url', headers = headers)

print(request.json())

GET /meet/app/outlook/get-auth-url

Return the Outlook Calendar OAuth2 authentication URL object for the current contact.

Responses

On 200 OK:

Revoke Google Calendar authentication

Revoke Google Calendar authentication

body = {
  'calendar': 'example@gmail.com'
}

request = requests.post(API_URL + '/meet/google/revoke, headers = headers, json = body)

print(request.json())

POST /meet/google/revoke

Revoke Google Calendar OAuth2 authentication for the current contact.

Parameters

Responses

On 200 OK or 400 Bad Request:

Revoke Outlook Calendar authentication

Revoke Outlook Calendar authentication

body = {
  'calendar': 'example@outlook.com'
}

request = requests.post(API_URL + '/meet/outlook/revoke, headers = headers, json = body)

print(request.json())

POST /meet/outlook/revoke

Revoke Outlook Calendar OAuth2 authentication for the current contact.

Parameters

Responses

On 200 OK or 400 Bad Request:

Meet - Events

Webhooks

webhook url and webhook event endpoints

Get webhook callback URL

Get webhook callback URL

request = requests.get(API_URL + '/webhooks/callbacks/url', headers = headers)

print(request.json())

GET /webhooks/callbacks/url

Return the webhook url for the current company.

Responses

Update webhook callback URL

Update callback URL of a webhook

body = {
  'url': 'https://www.example.com'
}

request = requests.put(API_URL + '/webhooks/callbacks/url', headers = headers, json = body)

print(request.json())

PUT /webhooks/callbacks/url

Update the webhook urls for the current company.

Parameters

Responses

Get subscribed webhook events

Get webhook callback events

request = requests.get(API_URL + '/webhooks/callbacks', headers = headers)

print(request.json())

GET /webhooks/callbacks

Get the subscribed webhook events.

Responses

Subscribe to webhook event

Subscribe to a webhook event

body = {
  'type': 'texting.message.inbound'
}

request = requests.post(API_URL + '/webhooks/callbacks', headers = headers, json = body)

print(request.json())

POST /webhooks/callbacks

Subscribe to a webhook event.

The event type is one of

• dial.action.started
• dial.action.completed
• call.action.hangup
• texting.message.inbound

Parameters

Responses

Unsubscribe from webhook event

Delete a subscribed webhook event

webhook_event_id = '6165732029a740a320e8031f'

request = requests.delete(API_URL + '/webhooks/callbacks/' + webhook_event_id, headers = headers)

print(request.json())

DELETE /webhooks/callbacks/{webhook_event_id}

Unsubscribe from webhook event.

Parameters

Responses

WebSocket

RingPlan websocket API works through the same URI as the one used for HTTP requests and is available on every environment. The details are generally uniform with the HTTP API unless noted otherwise.

Socket initialization in JavaScript

import { io } from 'socket.io-client';
const socket = io('https://ssp-backend.ringplan.com', {
  path: '/ws',
  transports: ['websocket'],
  secure: true,
  autoConnect: false,
  reconnectionDelay: 1500
});

Socket initialization in Python

import socketio

if __name__ == '__main__':
​    sio.connect('http://ssp-backend.ringplan.com', socketio_path='/ws/')
    sio.wait()

The server will emit three types of events:

Custom handler

if __name__ == '__main__':
​    # It is possible to override `trigger_event()` and write a custom handler.
    class MyCustomNamespace(socketio.ClientNamespace):
        # To catch all events:
        def trigger_event(self, event_name, sid, *args):
            print(f"{event_name=}, {sid=}")
            if args:
                print(f"data is {args[0]}")
    sio.register_namespace(MyCustomNamespace())
    sio.connect('http://ssp-backend.ringplan.com', socketio_path='/ws/')
    sio.wait()

In turn, the client can emit the following event:

After initializing the socket, the client should listen for the connect event, then reply with an authenticate event containing the authentication token.

Socket authentication in JavaScript

socket.connect()
socket.once('connect', function(socket) {
  socket.emit('authenticate', { token: API_KEY });
  socket.once('authenticated', function(socket) {
    console.log('Authentication successful.');
});

Socket authentication and event handling in Python

@sio.event
def connect():
    sio.emit('authenticate', {'token': API_KEY, 'user_email': USER_EMAIL})
    print('Connected.')

@sio.event
def disconnect():
    print('Disconnected.')
​
@sio.on('authenticated')
def authenticated(data):
    print('Authentication successful.')

@sio.on('unauthorized')
def unauthorized(data):
    print('Unauthorized!')​

The socket is ready to use once the client receives the authenticated event. ​

Messages - Client

Message events the client emits to the server and the other clients.

Mark messages as read

texting.message.markAsRead

Mark the given messages as read.

Messages - Server

Message events the server emits to the clients.

New message

texting.message.new

A new message has arrived.

The server will yield a message object.

Message deletion

texting.message.delete

A message has been deleted.

Message marked read

texting.message.markAsRead

The messages have been marked as read.

Chats - Server

Chat events the server emits to the clients.

Chat creation

Handle new message

@sio.on('texting.message.new')
def msg_new(data):
    print('texting.message.new', data)

texting.chat.new

A new conversation has been created.

The server will yield a conversation object.

Chat deletion

Handle message deletion

@sio.on('texting.message.delete')
def msg_delete(data):
    print('texting.message.delete', data)

texting.chat.delete

The conversation has been deleted.

User status - Server

user_status_updated

A texting contact's status has changed.

Objects

RingPlan API uses multiple different objects for internal representation.

Descriptions of object fields are provided below in alphabetical order, following the ID field.

Address

Address has fields that describe individual parts of a company or a user's physical address. Address objects do not have ID fields because they are user provided and are not necessarily unique.

Company

Company holds the information for each individual company. The company object forms the core of the object relations in RingPlan API.

Contact

Contact describes a user within a company. Each user belongs to a company.

Conversation

Conversation represents the communication between a texting contact and phone numbers. Each conversation contains messages.

Destination

Destination represents the end-point for a fax message.

Extension

Extension represents the internal phone number extensions within a location.