Subscriber Management API

15 min

Introduction

This document defines the exotel platform APIs adding, updating, viewing and deleting the subscribers for VoIP Calling. Subscriber is the entity who uses the app with voip calling feature.

Subscriber provisioning in exotel can happen in two ways,

Pre-provisioning

The customer pre-configures the client accounts even before the app is installed by the client.

Dynamic provisioning

A client account is created after the app is installed by the user and signs-up with the application backend.

All the APIs listed in this document are privileged APIs that need API Key and API Token for authentication. API key:token are generated on sign-up with exotel platform. Please contact [email protected]

Base URL

In all the APIs below, replace <base_url> with the following based on the stamp. Stamp info can be found in your Exotel dashboard under the API settings page.

MUM Stamp - https://chaotix.mum1.exotel.in

SGP Stamp - https://chaotix.apac-sg.exotel.in

Subscriber Response Object

The subscriber object returned in the APIs is described below

Parameter	Data Type	Description
subscriber_name	String	Subscriber name provided while creating the subscriber (Must be unique for a particular tenant) Maximum supported subscriber name length is 16 bytes and can contain numeric characters. Whitespace characters are not allowed. e.g. 123456, 9889899999 etc
status	Enum (active/ inactive)	Whether the subscriber is active or not
custom_field	String	Field to store custom metadata for the subscriber
date_created	DateTime	Time at which the subscriber was created
date_updated	DateTime	Time at which the subscriber was updated

Create Subscriber Token

Access to the exotel platform by ExotelVoiceClient is authenticated using a bearer token - subsriber_token. Clients must obtain this token from their application backend which in turn should fetch it from the exotel platform using the HTTPS endpoint listed here.

Method: POST

Request URL: https://<base_url>/v2/accounts/<account-sid>/subscriber-token

Authorization Type: Basic authentication using API key:token

Request Body Parameters:

Parameter	Data Type	Description
platform	String	Parameter (Android / iOS)
device_id	String	Device id (AndroidID / iOS UDID)
subscriber_name	String	Unique subscriber identifier

Response Type: JSON

Response Code:

200 Success

400 Bad Request, Malformed Parameters

401 Unauthorized

Response Body Parameters:

Parameter	Data Type	Description
subscriber_token	String	Token to access exotel platform
subscriber_name	String	Subscriber name used for token generation

Note - The Time-to-Live (TTL) for token expiry is as follows:

Refresh token expiry: 24 hours

Access token expiry: 30 minutes

Sample Request

https://<base_url>/v2/accounts/exotel13m2/subscriber-token
{
"platform": "android",
"device_id": "2fc4b5912826ad1",
"subscriber_name": “archit”
}

Sample Response

{
"request_id": "2f97c5e98e1d4c188c483cbfe8092869",
"method": "POST",
"http_code": 200,
“response”:
{
"code": 200,
"error_data": null,
"status": "success",
“data”:
{
	"subscriber_name": “archit”,
"subscriber_token": 
{ 
"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleG90ZWwiLCJzdWIiOiJBcmNoaXQiLCJpYXQiOjE1NzY2NDc5OTksImV4cCI6MTU3Njc0Nzk5OSwiY2xpZW50X2lkIjoiNUUwNTg2NUUifQ.Hc3umVfFlKIPiJ8R9kcP9o9hE9he51le08rO22u7eqs",
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleG90ZWwiLCJzdWIiOiJBcmNoaXQiLCJpYXQiOjE1NzY2NDc5OTksImV4cCI6MTU3Njc0Nzk5OSwic2NvcGUiOiJ2b2ljZSIsImNsaWVudF9pZCI6IjVFMDU4NjVFIn0.uQd_aHGBIT4XqTPfl-567dmjQrKlmLtPag0KpGB2QMA"
}
},
}
}

Create Subscribers

API is used for both single or bulk subscriber account creation in exotel platform.

Method: POST

Request Url: https://<base_url>/v2/accounts/<account-sid>/subscribers

Authorization Type: Basic authentication using API key:token

Request Body Parameters:

Parameter	Data Type	Requirement	Description
subscriber_name	String	Mandatory	Unique Username for the Subscriber
custom_field	String	Optional	Field to store custom metadata for the Subscriber

Please note that POST is a bulk operation and the request is actually an array of the above.

The maximum number of subscribers which can be created in a single request is 10.

Response Type: JSON

Response Body Parameters: Returns multipart response for request. Refer Subscriber Response Object

Sample Request

https://<base_url>/v2/accounts/<accountsid>/subscribers
{
  "subscribers": [
    {
      "subscriber_name": "bob",
      "custom_field": "support"
    },
    {
      "subscriber_name": "nidhi"
    },
    {
      "subscriber_name": "archit"
    }
  ]
}

Sample Response

{
"request_id": "04386e350256448dae83c6db0f749a21",
"method": "POST",
"http_code": 207,
"metadata": {
"failed": 0,
"success": 3
},
"response": [
{
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-11-19T23:14:17+05:30",
"date_updated": "2019-11-19T23:14:17+05:30",
"subscriber_name": "bob",
"status": "active",
"custom_field": "support”
}
},
{
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-11-19T23:14:17+05:30",
"date_updated": "2019-11-19T23:14:17+05:30",
"subscriber_name": "nidhi",
"status": "active",
"custom_field": null
}
},
{
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-11-19T23:14:18+05:30",
"date_updated": "2019-11-19T23:14:18+05:30",
"subscriber_name": "archit",
"status": "active",
"custom_field": null
}
}
],
}

Update a Subscriber

API is used to update the subscriber account parameters after it has been created. Subscriber can be marked inactive for temporary suspension.

Method: PUT

Request Url: https://<base_url>/v2/accounts/<account-sid>/subscribers/<subscriber-name>

Authorization Type: Basic authentication using API key:token

Request Body Parameters:

Parameter	Data Type	Requirement	Description
custom_field	String	Optional	Field to store custom metadata for the subscriber
status	Enum	Mandatory	Indicates whether the subscriber is active or not enum {“active”, “inactive”}

Response Type: JSON

Response Body Parameters: Refer Subscriber Response Object

Sample Request

https://<base_url>/v2/accounts/<accountsid>/subscribers/archit
{
  "status": "inactive",
}

Sample Response

{
"request_id": "8019271c8d98422db509c2801e63435f",
"method": "PUT",
"http_code": 200,
"response": {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-11-19T23:14:18+05:30",
"date_updated": "2019-11-20T11:13:38+05:30",
"subscriber_name": "archit",
"status": "inactive",
"custom_field": null
}
}
}

Get Subscriber

API returns subscriber details.

Method: GET

Request Url: https://<base_url>/v2/accounts/<account-sid>/subscribers/<subscriber_name>

Authorization Type:Basic authentication using API key:token

Request Body Parameters: None

Response Type: JSON

Response Body Parameters: On success returns Subscriber Response Object

Sample Request

https://<base_url>/v2/accounts/<accountsid>/subscribers/archit

Sample Response

{
"request_id": "287c227674af40b38531a1c247262deb",
"method": "GET",
"http_code": 200,
"response": {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-11-19T23:14:18+05:30",
"date_updated": "2019-11-20T11:13:38+05:30",
"subscriber_name": "archit",
"status": "inactive",
"custom_field": null
}
}
}

List Subscribers

API returns a paginated list of subscribers.

Method: GET

Request Url: https://<base_url>/v2/accounts/<account-sid>/subscribers>?status=abc&page_size=xyz&offset=xyz

Authorization Type: Basic authentication using API key:token

Request Body Parameters:

Query Parameter	Data Type	Requirement	Description
status	Enum	Optional	Status for the subscriber
page_size	uint64	Optional	Page size for response. Default and maximum value is 100
offset	uint64	Optional	Offset from which to get the records. Defaults to 0

Response Type: JSON

Response Body Parameters: On success returns paginated list of Subscriber Response Object

Sample Request

https://<base_url>/v2/accounts/<accountsid>/subscribers?page=2&offset=3

Sample Response

{
"request_id": "b5f0c6780ec443d08947ba2015a06a04",
"method": "GET",
"http_code": 200,
"metadata": {
"prev_page_uri": "/v2/accounts/<accountsid>/subscribers?offset=6&page_size=3",
"next_page_uri": "/v2/accounts/<accountsid>/subscribers?offset=12&page_size=3",
"first_page_uri": "/v2/accounts/<accountsid>/subscribers?offset=0&page_size=3"
},
"response": [
  {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-12-30T17:12:00+05:30",
"date_updated": "2019-12-30T17:12:00+05:30",
"subscriber_name": "shyam",
"status": "active",
"custom_field": null
}
},
  {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-12-30T17:09:41+05:30",
"date_updated": "2019-12-30T17:09:41+05:30",
"subscriber_name": "kiran",
"status": "active",
"custom_field": "test"
}
},
  {
"code": 200,
"error_data": null,
"status": "success",
"data": {
"date_created": "2019-12-30T13:35:07+05:30",
"date_updated": "2019-12-30T13:35:07+05:30",
"subscriber_name": "mandeep",
"status": "active",
"custom_field": null
}
}
],
}

Delete Subscriber

API deletes a subscriber permanently.

Method: DELETE

Request Url: https://<base_url>/v2/accounts/<account-sid>/subscribers/<subscriber-name>

Authorization Type: Basic authentication using API key:token

Request Body Parameters: None

Response Type: JSON

Response Body Parameters: On success, HTTP response 204 is returned with no response body. In case of failure 404 is returned

Sample Request

https://<base_url>/v2/accounts/<accountsid>/subscribers/shyam

Sample Response

(a) Success: No body

(b) Failure:

{
    "request_id": "af0087d5331f479599d2c987efe9f664",
    "method": "DELETE",
    "http_code": 404,
    "response": {
        "code": 404,
        "error_data": {
            "code": 1000,
            "description": "Subscriber not found",
            "message": "Not Found"
        },
        "status": "failure",
        "data": null
    }
}