Interswitch Real-Time Communication Platform

API Documentation v2

General

General Information

The Interswitch Real-Time Communications Platform API is for the mobile phone application to communicate with RTCP. It uses the HTTPS standard for connections. Request parameters can either be submitted via Query String or for POST requests by providing a JSON string as data. Responses are served in JSON.

Examples showing both variants for device registration:

Query String:

https://rtcp.vanso.com/api/devices/register_device?device[api_version]=_API_VERSION_&device[device_type]=_DEVICE_TYPE_&device[hardware_id]=_HARDWARE_ID_&device[platform_type]=_PLATFORM_TYPE_&device[push_token]=_PUSH_TOKEN_

JSON:

{
   "device":{
      "hardware_id":"_HARDWARE_ID_",
      "platform_type":"_PLATFORM_TYPE_",
      "push_token":"_PUSH_TOKEN_",
      "device_type":"_DEVICE_TYPE_",
      "api_version":2,
   }
}

The examples in this documentation show the JSON type with relevant HTTP Requests and Responses (without the protocol version) for POST requests.

Documentation Styling

This documentation follows a certain styling which is exemplarily shown here. For each API endpoint documentation you will find a section having this layout.

This paragraph decribes briefly the purpose of the API endpoint.

API endpoint URL (i.e. https://rtcp.vanso.com/api/api/url_endpoint)

Request parameters:

Parameter	Description
Required parameter	This table lists all accepted parameters. Required parameters are written in bold.
Optional parameter	This describes an optional parameter

Request example:

HTTP Method Call (i.e. POST https://rtcp.vanso.com/api/api_url_endpoint)
Optionally: additional headers

{
   "response in json":"value"
}

Success response:

HTTP Status Code and Message (i.e. 200 OK)

{
   "response in json":"value"
}

Error response example:

HTTP Status Code and Message (i.e. 400 Bad Request)

{
   "response in json":"value"
}

Authentication

Making API Requests from your app

Use of the API for the Interswitch Real-Time Communications Platform requires proper authentication.
Authentication is provided through a custom HTTP Request Header as shown below.

Request parameters:

Header	Description
AUTH-APP-ID	The "AUTH-APP-ID" header must contain the Application ID which is assigned to each Application you create on our platform. This must be a valid Application ID.

Request example:

POST https://rtcp.vanso.com/api/devices/register_device
AUTH-APP-ID: 03867f7fcdae3265

<Request Data>

Success response example:

200 OK

{
   "processed":true
}

Error response examples:

400 Bad Request

{
   "error":"Bad Request",
   "message":"HTTP_AUTH_APP_ID is invalid. No application with this ID was found."
}

Making API Requests to send notifications

In addition to the AUTH-APP-ID, requests to send notifications require HMAC (keyed-Hash Message Authentication Code) type authentication. Authentication and Signature are provided through custom HTTP Request Headers as shown below.

Request parameters:

Header	Description
AUTH-APP-ID	The "AUTH-APP-ID" header must contain the Application ID which is assigned to each Application you create on our platform. This must be a valid Application ID. Example: AUTH-APP-ID: '03867f7fcdae3265'
AUTH-TIMESTAMP	The "AUTH-TIMESTAMP" header must contain a current timestamp. The timestamp must be in UTC (Coordinated Universal Time) and in the ISO8601 format. The timestamp is required to be within the last 60 seconds. Example: AUTH-TIMESTAMP: '2024-11-21T07:18:39Z'
AUTH-SIGNATURE	The "AUTH-SIGNATURE" header contains a calculated signature which is used to complete the authentication process. (Information about calculating the signature appears in the section below.) Example: AUTH-SIGNATURE: '3d10982d604c3b58246e0e09bcab406ee11d7b5c6c9ff5b512709223c545afce'

Request example to send a broadcast push:

POST /api/push/broadcast
AUTH-APP-ID: caddda6f21daca0f
AUTH-SIGNATURE: a005574ee8353fcddcff46cee659e23accc34c7ebca654f7305c00502ca97969
AUTH-TIMESTAMP: 2021-05-08T09:31:25Z

{
   "push":{
      "message":"My broadcast message"
   }
}

Success response example:

200 OK

{
   "processed":true
}

Error response examples:

400 Bad Request

{
   "error":"Unauthorized Request",
   "message":"Signature is invalid."
}

Calculating Signature

A signature must be provided via the HTTP_AUTH_SIGNATURE ("AUTH-SIGNATURE") header of the request in order to successfully authenticate with the Interswitch Real-Time Communications Platform. The signature is calculated using the client secret of the application, the API request URL and the "AUTH-TIMESTAMP" value. Create a SHA256 hash of the timestamp appended to the request URL using the secret token from your application. Here is an example:

OpenSSL::HMAC.hexdigest('SHA256', _YOUR_SECRET_TOKEN_, _URL_ + _TIMESTAMP_)

This is the signature that you will send in the AUTH-SIGNATURE header.

Follow these steps to authenticate a request with the Interswitch Real-Time Communications Platform:

Generate the URL for the API request. Choose the API Endpoint you want to call and assemble the necessary parameters.
_URL_ = 'https://rtcp.vanso.com/api/push/broadcast?push%5Bapp_id%5D=03867f7fcdae3265&push%5Bmessage%5D=Hello!'"
Generate a timestamp. Must be UTC in ISO8601 format!
_TIMESTAMP_ = '2014-12-08T10:47:06Z'
Calculate the signature. Using the SECRET_TOKEN from your application create a SHA256 hash of the TIMESTAMP appended to the URL.

_YOUR_SECRET_TOKEN_ = '58598b9c3f07258651680db501717e70'

= "SIGNATURE = OpenSSL::HMAC.hexdigest('SHA256', _YOUR_SECRET_TOKEN_, _URL_ + _TIMESTAMP_)"

= "SIGNATURE = OpenSSL::HMAC.hexdigest('SHA256', '58598b9c3f07258651680db501717e70', 'https://rtcp.vanso.com/api/push/broadcast?push%5Bapp_id%5D=03867f7fcdae3265&push%5Bmessage%5D=Hello!' + '2014-12-08T10:47:06Z')"

SIGNATURE = 'c0116de802b6c2b2ccd1d2041ffaa7fb06e9f945c3b025386b7a5909784309e2'
Set the request headers. HTTP_AUTH_APP_ID, HTTP_AUTH_TIMESTAMP and HTTP_AUTH_SIGNATURE are required!
AUTH-APP-ID: '03867f7fcdae3265', AUTH-TIMESTAMP: '2014-12-08T10:47:06Z', AUTH-SIGNATURE: 'c0116de802b6c2b2ccd1d2041ffaa7fb06e9f945c3b025386b7a5909784309e2'
POST the request.
curl --header 'AUTH-APP-ID: 03867f7fcdae3265' --header 'AUTH-SIGNATURE: c0116de802b6c2b2ccd1d2041ffaa7fb06e9f945c3b025386b7a5909784309e2' --header 'AUTH-TIMESTAMP: 2014-12-08T10:47:06Z' -X POST 'https://rtcp.vanso.com/api/push/broadcast?push%5Bapp_id%5D=03867f7fcdae3265&push%5Bmessage%5D=Hello!' -d ''

Get User's Applications

Get the list of applications for a specific user.

The URL to your POST request to get a list of applications is:

https://rtcp.vanso.com/api/user_applications

Request parameters:

Parameter	Description
email	The email address which is registered for application and used as user name for login.
password	To secure your applicaiton and data password is used for.
app_version	The app version of the mobile app. Required to ensure API compatibility.

Request example:

POST https://rtcp.vanso.com/api/user_applications

{
  "email":"superuser@superuser.com",
  "password":"123456789",
  "app_version":"1"
}

Success response:

200 OK

{
  "user_apps":{
    "0":{
      "app_name":"_APPLICATION_NAME_",
      "app_id":"_APPLICATION_ID_",
      "app_secret":"_APPLICATION_SECRET_"
    }
  },
  "countly_apps":[
  ],
  "user_type":"Super User"
}

Error response examples:

400 Bad Request

{
  "message":"Invalid password",
  "error":"Bad Request"
}

400 Bad Request

{
  "message": "User not registered with this email",
  "error":"Bad Request"
}

Device Endpoints

Register Device

Use this API endpoint to register or update a device with the Interswitch Real-Time Communications Platform. A device must be registered before we can send push notifications to it. Use this same API endpoint to update a device that was previously registered.

The URL to POST your request to register a device is:

https://rtcp.vanso.com/api/devices/register_device

Request parameters:

Parameter	Description
device	A Hash defining the device by the parameters below.
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
push_token	The push token for the device. This is received from an external push service provider such as Apple or Google.
platform_type	The platform type for the device. There are two supported platform types: 'IosPlatform' and 'AndroidPlatform'.
device_type	The type of device you are registering. There are five supported device types: 'phone', 'tablet', 'notebook', 'pc' and 'other'.
api_version	The version of the RTCP API this device uses. Required for any version above 1.
language	The default language for the device. ISO 639-1 Language Codes are required. Examples: 'en', 'hi', 'de'
time_zone	The default time zone for the device. This is a floating point number, offset from GMT. Examples: 0.0, -9.0, 4.5
os	A string which represents information about the device OS. Examples: 'Intel Mac OS X 10_9_3', 'Linux; Android 4.4.2; LG-E975'
email	An email address associated with this device. This can be used as a fallback for notifications. This must be a properly formatted email address. Example: 'fake@example.com'
mobile	A mobile phone number associated with this device. This can be used as a fallback for notifications.
tags	Tags are a hash of user defined keys and values. They can be used to target audiences for distribution of push notifications. The key and value can be whatever you choose. All values are treated as strings. Examples: { awesome: 'true', foo: 'bar' }

Request example:

POST https://rtcp.vanso.com/api/devices/register_device

{
   "device":{
      "hardware_id":"_HARDWARE_ID_",
      "platform_type":"_PLATFORM_TYPE_",
      "push_token":"_PUSH_TOKEN_",
      "device_type":"_DEVICE_TYPE_",
      "api_version":2,
      "email":"_EMAIL_",
      "language":"_LANGUAGE_",
      "mobile":"_MOBILE_NUMBER_",
      "os":"_OS_",
      "tags":{
         "bar":"_BAR_",
         "foo":"_FOO_"
      },
      "time_zone":"_TIMEZONE_ "
   }
}

Success response:

HTTP/1.1 200 OK

{
   "processed":true
}

Error response example:

400 Bad Request

{
   "message":"push_token parameter is missing.",
   "error":"Bad Request"
}

Unregister Device

Use this API endpoint to unregister a device with the Interswitch Real-Time Communications Platform. This will delete the device from our platform. It can be re-added by calling register_device again.

The URL to POST your request to unregister a device is:

https://rtcp.vanso.com/api/devices/unregister_device

Request parameters:

Parameter	Description
device	A Hash defining the device by the parameters below.
hardware_id	The hardware ID of the device. This is a unique identifier for the device.

Request example:

POST https://rtcp.vanso.com/api/devices/unregister_device

{
   "device":{
      "hardware_id":"_HARDWARE_ID_"
   }
}

Success response:

200 OK

{
   "processed":true
}

Error response example:

400 Bad Request

{
   "error":"Bad Request",
   "message":"The hardware_id is not associated with any registered device. Please register the device with that hardware_id first."
}

Push Endpoints

Single Push

Use this API endpoint to send push notifications to specific devices with the Interswitch Real-Time Communications Platform.

The array "results" in the response contains the response codes stated below and the unique push id. It follows the same order as the "pushes" array in the request.

The URL to POST your request to push to a single device is:

https://rtcp.vanso.com/api/push/single

Authentication:

This endpoint requires HMAC Authentication.

Request parameters:

Parameter	Description
pushes	Array of Hashes containing parameters stated below.
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
message	The message to send to the device. This is a text string.
expiry_date	Inform the push vendors (Google, Apple) to attempt to deliver the Push Notification until this date (optional, max if unset). Must be in ISO8601 format.
app_data	A hash of user-defined keys and values to be passed through the platform to the device. This allows for you to specify custom data that is meaningful to your mobile application. The length of this data may not be more than 2000 characters total. Example: { vibrate: 'true', do: 'that', show: { big: true, align: 'top', icon: 'smiley' } }

Response codes:

Status Code	Message
-1	Push creation failed
0	Push Accepted
1	Hardware ID not provided
2	Message not provided
10	Hardware ID not found

Request example:

POST https://rtcp.vanso.com/api/push/single

{
  "pushes": [
    {
      "hardware_id": "abcdef123456",
      "message": "Single Push Message",
      "expiry_date": "2021-06-11T12:42:04+02:00"
    },
    {
      "hardware_id": "123456abcdef",
      "message": "Single Push Message 2",
      "app_data": { "somekey": "somevalue" }
    }
  ]
}

Success response:

200 OK

{
  "results": [
    {
      "status": 0,
      "message": "Push Accepted",
      "push_id": 1234
    },
    {
      "status": 0,
      "message": "Push Accepted",
      "push_id": 1235
    }
  ]
}

Error response examples:

200 OK

{
  "results": [
    {
      "status": 1,
      "message": "Hardware ID not provided"
    },
    {
      "status": 2,
      "message": "Message not provided"
    }
  ]
}

Broadcast Push

Use this API endpoint to send a push notification to all registered devices for an application with the Interswitch Real-Time Communications Platform.

The URL to POST your request to push to all registered devices is:

https://rtcp.vanso.com/api/push/broadcast

Authentication:

This endpoint requires HMAC Authentication.

Request parameters:

Parameter	Description
message	The message to send to the device. This is a text string.
start_date	The time at which the Push is sent. If omitted the Push is sent instantly. The timestamp must be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: '2021-06-26T12:34Z'
expiry_date	Inform the push vendors (Google, Apple) to attempt to deliver the Push Notification until this date (optional, max if unset). Must be in ISO8601 format.
app_data	A hash of user-defined keys and values to be passed through the platform to the device. This allows for you to specify custom data that is meaningful to your mobile application. The length of this data may not be more than 2000 characters total. Example: { vibrate: 'true', do: 'that', show: { big: true, align: 'top', icon: 'smiley' } }

Request example:

POST https://rtcp.vanso.com/api/push/broadcast

{
  "message": "_MESSAGE_",
  "start_date": "2021-06-26T12:34Z",
  "expiry_date": "2021-06-11T12:42:04+02:00",
  "app_data": {
    "somekey": "somevalue"
  }
}

Success response:

200 OK

{
  "processed": true
}

Targeted Push

Use this API endpoint to send a push notification to targeted devices with the Interswitch Real-Time Communications Platform. The filters are applied to devices which have been registered previously. A search is applied on attributes of the devices which were supplied with their registration. Device attributes may also be set from the website.

The URL to POST your request to push to targeted devices is:

https://rtcp.vanso.com/api/push/targeted

Request parameters:

Parameter	Description
message	The message to send to the device. This is a text string.
filters	Filters are a hash of keys and values. You must include at least one filter. Example: { platform_types: ['IosPlatform'] } There are five supported filters: platform_types, device_types, language, time_zone and tags. platform_types: An array which must include one or more of the two supported platform types: 'IosPlatform', 'AndroidPlatform'. Example: { platform_types: ['IosPlatform', 'AndroidPlatform'] } device_types: An array which must include one or more of the five supported device types: 'phone', 'tablet', 'notebook', 'pc' or 'other'. Example: { device_types: ['phone', 'tablet'] } language: A ISO 639-1 Language Code Examples: 'en', 'hi', 'de' time_zone: This is a floating point number, offset from GMT. Examples: 0.0, -9.0, 4.5 tags: Tags are a hash of user defined keys and values. The key and value can be whatever you choose. All values are treated as strings. Examples: { awesome: 'true', foo: 'bar' }
start_date	The time at which the Push is sent. If omitted the Push is sent instantly. The timestamp must be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: '2021-06-26T12:34Z'
expiry_date	Inform the push vendors (Google, Apple) to attempt to deliver the Push Notification until this date (optional, max if unset). Must be in ISO8601 format.
app_data	A hash of user-defined keys and values to be passed through the platform to the device. This allows for you to specify custom data that is meaningful to your mobile application. The length of this data may not be more than 2000 characters total. Example: { vibrate: 'true', do: 'that', show: { big: true, align: 'top', icon: 'smiley' } }

Request example:

POST https://rtcp.vanso.com/api/push/targeted

{
  "message": "Test targeted push.",
  "expiry_date": "2021-06-11T12:42:04+02:00",
  "app_data": {
    "page_id": "52085"
  },
  "filters": {
    "device_types": [
      "tablet",
      "phone"
    ],
    "platform_types": [ "IosPlatform" ],
    "tags": {
      "sports": "true"
    }
  }
}

Success response:

200 OK

{
  "processed": true
}

GeoZone Push

Use this API endpoint to create a GeoZone with the Interswitch Real-Time Communications Platform which will trigger push notifications for location aware devices. This API will create the GeoZone. The location API above is used to set the location of a device. If the device is within a defined GeoZone then a push notification will be sent.

The URL to POST your request to push to targeted devices is:

https://rtcp.vanso.com/api/push/area

Request parameters:

Parameter	Description
message	The message to send to the device. This is a text string.
geo_zone	geo_zone is a hash of keys and values. There are two types of GeoZones which are supported: circle and polygon. Each GeoZone shape has a unique set of required parameters. The required parameters for a cicle geo_zone are: { geo_zone: { name: 'My Circle GeoZone', circle: { pt_1: { lat: '21.289673096761867', lng: '-74.590855185956' }, radius: '1234.5678' } } } name: This is the user-defined name for the GeoZone that will be created. Names are not unique. pt_1: This is a hash which contains a lat (latitude) parameter and a lng (longitude) parameter. It represents the center of the circle. Example: pt_1: { lat: '21.289673096761867', lng: '-74.590855185956' } radius: This is a string which specifies the radius of the GeoZone as measured in meters. It should have a value larger than 1. It can be a fractional value. Example: radius: '1234.5678' The required parameters for a polygon geo_zone are: { geo_zone: { name: 'My Polygon GeoZone', polygon: { pt_1: { lat: '7.27117569176742', lng: '-105.83362499999998' }, pt_2: { lat: '23.359474210566834', lng: '-72.42634375000006' } } } } name: This is the user-defined name for the GeoZone that will be created. Names are not unique. pt_1: This is a hash which contains a lat (latitude) parameter and a lng (longitude) parameter. It represents the top left corner of the polygon. Example: pt_1: { lat: '7.27117569176742', lng: '-105.83362499999998' } pt_2: This is a hash which contains a lat (latitude) parameter and a lng (longitude) parameter. It represents the bottom right corner of the polygon. Example: pt_2: { lat: '23.359474210566834', lng: '-72.42634375000006' }
start_date	The push notifications may be scheduled for a GeoZone. The GeoZone will become active at this time. The timestamp must be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: '2021-08-26T12:34Z'
end_date	The push notifications may be scheduled for a GeoZone. The GeoZone will cease to be active at this time. The timestamp must be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: '2021-08-28T23:59Z'
cool_down	This can be used to specify how often a device can receive a push notification for this GeoZone. This is an integer which measures hours. The default is 24 hours.
app_data	A hash of user-defined keys and values to be passed through the platform to the device. This allows for you to specify custom data that is meaningful to your mobile application. The length of this data may not be more than 2000 characters total. Example: { vibrate: 'true', do: 'that', show: { big: true, align: 'top', icon: 'smiley' } }

Request examples

Circle type GeoZone:

POST https://rtcp.vanso.com/api/push/area

{
  "message": "_MESSAGE_",
  "start_date": "_START_DATE_",
  "end_date": "_END_DATE_",
  "cool_down": "_COOL_DOWN_",
  "geo_zone": {
    "name": "_NAME_",
    "circle": {
      "center": "_CENTER_",
      "radius": "_RADIUS_"
    }
  }
}

Polygon type GeoZone:

POST https://rtcp.vanso.com/api/push/area

{
  "message": "_MESSAGE_",
  "start_date": "_START_DATE_",
  "end_date": "_END_DATE_",
  "cool_down": "_COOL_DOWN_",
  "geo_zone": {
    "name": "_NAME_",
    "polygon": {
      "pt_1": {
        "lat": "_LATITUDE_",
        "lng": "_LONGITUDE_"
      },
      "pt_2": {
        "lat": "_LATITUDE_",
        "lng": "_LONGITUDE_"
      }
    }
  }
}

Success response:

200 OK

{
  "processed": true
}

App Endpoints

Recent Notifications

Use this API endpoint to query Interswitch Real-Time Communications Platform for recent notifications sent to a device. By default we will send you the ten most recent notifications. When this URL is called the returned notification's status will be set to 'received'.

The URL to POST your request to get recent notifications is:

https://rtcp.vanso.com/api/notifications/recent

Request parameters:

Parameter	Description
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
count	The number of recent notifications for this device that you would like returned. Must be an integer between 1 and 100.

Request example:

POST https://rtcp.vanso.com/api/notifications/recent

{
  "hardware_id":"7c4c2c5c04e7fc13"
}

Success response with notifications: (Notifications is an array of hashes. Each hash is for one push notification.)

200 OK

{
   "processed":true,
   "count":3,
   "notifications":[
      {
         "push_id":"P123",
         "message":"Push message P123",
         "time":"2021-04-28T10:17:27Z",
         "read":false
      },
      {
         "push_id":"P122",
         "message":"Push message P122",
         "time":"2021-03-27T18:28:09Z",
         "read":false
      },
      {
         "push_id":"P121",
         "message":"Push message P121",
         "time":"2021-03-22T13:34:08Z",
         "read":false
      }
   ]
}

Success response with no notifications present:

200 OK

{
   "processed":true,
   "message":"No notifications exist for this device."
}

Error response example:

400 Bad Request

{
   "error":"Bad Request",
   "message":"The hardware_id is not associated with any registered device. Please register the device with that hardware_id first."
}

Delete Notifications

Use this API endpoint to delete certain Notification from a user's Inbox.

The URL to POST your request to delete notifications is:

https://rtcp.vanso.com/api/notifications/delete

Request parameters:

Parameter	Description
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
push_id	This is the push ID which was sent in the app_data of the push notification payload. This parameter can either be a String containing a single push ID or, to delete multiple pushes at once, an Array of Strings with each containing a push ID.

Request example:

POST https://rtcp.vanso.com/api/notifications/delete

{
  "hardware_id":"7c4c2c5c04e7fc13",
  "push_id":[
    "_PUSH_ID1_",
    "_PUSH_ID2_"
  ]
}

Success response:

200 OK

{
   "processed":true
}

Error response example:

400 Bad Request

{
   "message":"Device not found"
}

Read Receipts

Use this API endpoint to inform the Interswitch Real-Time Communications Platform that one or more push notifications have been read on a device.

The URL to POST your request to set device location is:

https://rtcp.vanso.com/api/read_receipt/read (formerly /api/read_receipt/opened)

Request parameters:

Parameter	Description
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
push_id	This is the push ID which was sent in the app_data of the push notification payload. This parameter can either be a String containing a single push ID or, to update multiple pushes at once, an Array of Strings with each containing a push ID.
time	The time the push notification was read on the device. The timestamp should be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: '2021-08-28T23:59:59Z'

Request example:

POST https://rtcp.vanso.com/api/read_receipt/read

{
   "hardware_id":"_HARDWARE_ID_",
   "push_id":[
      "_PUSH_ID1_",
      "_PUSH_ID2_"
   ],
   "time":"_TIME_"
}

Success response:

200 OK

{
   "processed":true
}

Error response example:

400 Bad Request

{
   "message":"Device not found"
}

Set Location

Use this API endpoint to set the location of a device with the Interswitch Real-Time Communications Platform. The device must be registered with the platform first.

The URL to POST your request to set device location is:

https://rtcp.vanso.com/api/location/set

Request parameters:

Parameter	Description
hardware_id	The hardware ID of the device. This is a unique identifier for the device.
location	The location parameter is a hash which must contain 'lat' (latitude) and 'lng' (longitude) keys. Example: { lat: '49.7925039', lng: '9.9448982' }

Request example:

POST https://rtcp.vanso.com/api/location/set

{
  "hardware_id": "_HARDWARE_ID_",
  "location": {
    "lat": "_LATITUDE_",
    "lng": "_LONGITUDE_"
  }
}

Success response:

200 OK

{
  "processed": true
}

Error response example:

400 Bad Request

{
  "error": "Bad Request",
  "message": "location parameter is missing."
}

Application Rating Endpoints

Set Application Rating

Use this API endpoint to set the rating of a application with the Interswitch Real-Time Communications Platform. The user must set application rating with account number.

The URL to POST your request to set application rating is:

https://rtcp.vanso.com/api/app_ratings/create

Request parameters:

Parameter	Description
account_no	This is the bank account number of user.
rating	This is the rating, you want to set to application. It must be between 0 to 5.
version	This is application version number.
message	This is a short feedback message from the user.

Request example:

POST https://rtcp.vanso.com/api/app_ratings/create

{
  "app_rating": {
    "rating": "_RATING_",
    "version": "_VERSION_",
    "account_no": "_ACCOUNT_",
    "message": "_MESSAGE_"
  }
}

Success response:

200 OK

{
   "processed":true
}

Error response example:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Missing rating params. account_no parameter is missing. rating parameter is missing. invalid rating"
}

Get Application Rating

Use this API endpoint to get the avarage rating of a application with the Interswitch Real-Time Communications Platform.

The URL to GET your request to set application rating is:

https://rtcp.vanso.com/api/app_ratings/get_rating

Request parameters:

Parameter	Description
app_id *	This is the application ID which is assigned to each application you create on our platform.
version *	This is the application version number.

Request example to get application rating:

GET https://rtcp.vanso.com/api/app_ratings/get_rating?version=_VERSION_

Success response:

200 OK

{
  "processed": true,
  "message": {
    "average": 5
  }
}

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Missing version number"
}

iBeacon Endpoints

Register iBeacon

Use this API endpoint to register or update an iBeacon with the Interswitch Real-Time Communications Platform. An iBeacon must be registered before we can return data for it. Use this same API to update an iBeacon that was previously registered.

The URL to POST your request to register an iBeacon is:

https://rtcp.vanso.com/api/ibeacons/register

Request parameters:

Parameter	Description
ibeacon	A Hash containing the parameters below.
uuid	The uuid of the iBeacon. This is the main identifier for your iBeacons. It must be 64 characters or less.
major	The major ID for the iBeacon. This is a sub identifier for an iBeacon. It must be exactly 2 characters.
minor	The minor ID for the iBeacon. This is a sub identifier for an iBeacon. It must be exactly 2 characters.
data	The data that you would like returned for a query about this iBeacon. It must be 512 characters or less. It should be in a valid JSON format. RTCP will return this data from the data API endpoint detailed below.
name	This is a name you can use to easily identify the iBeacon.

Request example:

POST https://rtcp.vanso.com/api/ibeacons/register

{
  "uuid": "_UUID_",
  "major": "_MAJOR_",
  "minor": "_MINOR_",
  "data": "_DATA_",
  "name": "_NAME_"
}

Success response:

200 OK

{
   "processed":true
}

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "uuid parameter is missing."
}

Get Single iBeacon Data

Use this API endpoint to query Interswitch Real-Time Communications Platform for data associated with a registered iBeacon. We will return whatever data was set when the iBeacon was registered.

The URL to POST your request to get iBeacon data is:

https://rtcp.vanso.com/api/ibeacons/data

Request parameters:

Parameter	Description
ibeacon	A Hash containing the parameters below.
uuid	The uuid of the iBeacon. This is the main identifier for your iBeacons. It must be 64 characters or less.
major	The major ID for the iBeacon. This is a sub identifier for an iBeacon. It must be exactly 2 characters.
minor	The minor ID for the iBeacon. This is a sub identifier for an iBeacon. It must be exactly 2 characters.

Request example:

POST https://rtcp.vanso.com/api/ibeacons/data

{
  "ibeacon": {
    "uuid": "_UUID_",
    "major": "_MAJOR_",
    "minor": "_MINOR_"
  }
}

Success response:

200 OK

{
  "processed": true,
  "message": {
    "foo": "bar"
  }
}

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "uuid parameter is missing."
}

Get All iBeacon Data

Use this API endpoint to query Interswitch Real-Time Communications Platform for all data associated with all registered iBeacons. We will return whatever data was set when the iBeacon was registered. You may supply an optional timestamp as a parameter. If no timestamp is provided we will return all iBeacon data. If a timestamp is supplied then we will only return iBeacons data if the most recently updated iBeacon is newer than the timestamp.

The URL to POST your request to get all iBeacon data is:

https://rtcp.vanso.com/api/ibeacons/get

Request parameters:

Parameter	Description
timestamp	The timestamp for comparison. The timestamp should be in UTC (Coordinated Universal Time) and in the ISO8601 format. Example: 2002-22-02T02:22:02Z

Request example:

POST https://rtcp.vanso.com/api/ibeacons/get

{
  "timestamp": "_TIMESTAMP_"
}

Success response:

200 OK

{
  "processed": true,
  "timestamp": "2021-04-16T09:54:45Z",
  "data": [
    {
      "uuid": "uuid1",
      "major": "01",
      "minor": "01",
      "data": {
        "foo": "foo"
      }
    },
    {
      "uuid": "uuid2",
      "major": "01",
      "minor": "02",
      "data": {
        "bar": "bar"
      }
    }
  ]
}

Error response example:

400 Bad Request

{
  "error": "Bad Request",
  "message": "timestamp parameter is invalid. Please use ISO8601 format. Example: 2002-22-02T02:22:02Z"
}

Get Application Statistics

Use this API endpoint to get the application statistics like number of divices, number of beacons, active geo zones, number of notifications, read notifications etc.

The URL to your GET request to get application statistics is:

https://rtcp.vanso.com/api/app_statistics?start_date=_START_DATE_&end_date=_END_DATE_

Request parameters:

Parameter	Description
start_date	This is the start date from which statistics get calculated. Not mandatory, if you not provide then statistics calculated for last 30 days. Start Date format should be (DD/MM/YYYY) e.g 21/06/2021.
end_date	This is the end date upto which statistics get calculated. Not mandatory, if you not provide then statistics calculated for last 30 days. End Date format should be (DD/MM/YYYY) e.g 21/06/2021.

Request example to get application statistics:

GET https://rtcp.vanso.com/api/app_statistics?start_date=_START_DATE_&end_date=_END_DATE_

Success response:

200 OK

{
  "statistics": {
    "no_of_devices": 2,
    "beacons": 5,
    "active_geo_zones": 1,
    "pushes": [
      {
        "geo_zone_name": "mumbai",
        "id": 15,
        "push_type": "area",
        "message": "Geozone Example",
        "application_id": 4,
        "geo_zone_id": 3,
        "status": "pending",
        "start_date": "2021-04-12T07:35:00.000Z",
        "end_date": "2021-04-29T18:30:00.000Z",
        "user_id": 2,
        "created_at": "2021-04-05T07:36:17.082Z",
        "updated_at": "2021-04-05T07:36:17.082Z",
        "filters": {},
        "is_scheduled": true,
        "long_url": "",
        "cool_down": 24,
        "app_data": "",
        "is_api": false,
        "job_id": null
      },
      {
        "geo_zone_name": null,
        "id": 14,
        "push_type": "broadcast",
        "message": "Last Push To Make geozone Active",
        "application_id": 4,
        "geo_zone_id": null,
        "status": "sent",
        "start_date": "2021-04-20T07:26:00.000Z",
        "end_date": null,
        "user_id": 2,
        "created_at": "2021-04-05T07:27:12.811Z",
        "updated_at": "2021-04-05T07:27:13.106Z",
        "filters": {},
        "is_scheduled": true,
        "long_url": "",
        "cool_down": 24,
        "app_data": "",
        "is_api": false,
        "job_id": null
      }
    ]
  }
}

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Start Date should be less than End Date"
}

Get Advertise Details

Use this API endpoint to get the ads details like campaign name, campaign start date, campaign end date, weight, and banners image url etc.

The URL to your GET request to get Ads detail is:

https://rtcp.vanso.com/api/get_ads?zone_id=_ZONE_ID_

Request parameters:

Parameter	Description
zone_id	This is the zone ID for which data is returned.

Request example to get Ads Details:

GET https://rtcp.vanso.com/api/get_ads?zone_id=_ZONE_ID_

Success response:

200 OK

{
  "0": {
    "campaign_name": "Sample Campaign 3",
    "campaign_start_date": "2021-04-06",
    "campaign_end_date": null,
    "campaign_weight": "1",
    "banners": [
      "{campaignId: 1, bannerName: 'BannerName', storageType: 'StorageType', imageURL: 'ImageURL', width: '100', height: '50', weight: '10', url: 'URL', payload: 'Payload'}",
      "{campaignId: 1, bannerName: 'BannerName', storageType: 'StorageType', imageURL: 'ImageURL', width: '100', height: '50', weight: '10', url: 'URL', payload: 'Payload'}"
    ]
  }
}

Error response examples:

"{ "error": "Bad Request", "message": "Zone record not found" }, status: 400"

"{"error": "Bad Request", "message": "zone_id is missing" }, status: 400"

Get Available Ad Zones

Use this API endpoint to get the available ad zones of account.

The URL to your GET request to get avaiable ad zones is:

https://rtcp.vanso.com/api/get_available_ad_zones

Request example to get Ads Details:

GET https://rtcp.vanso.com/api/get_available_ad_zones

Success response:

200 OK

[
  {
    "id": "1",
    "name": "Zone-1",
    "width": "200",
    "height": "50"
  },
  {
    "id": "2",
    "name": "Zone-2",
    "width": "200",
    "height": "50"
  }
]

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Error in processing request"
}

Notification Statistics

Use this API endpoint to get notification count and number of read notifications.

The URL to your GET request to get Notification statistics is:

https://rtcp.vanso.com/api/notification_statistics?push_id=_PUSH_ID_

Request parameters:

Parameter	Description
push_id	This is the push ID from which we get push message record.

Request example to get Notification Statistics:

GET https://rtcp.vanso.com/api/notification_statistics?push_id=_PUSH_ID_

Success response:

200 OK

{
  "notification_statistics": {
    "read_notifications": 0,
    "no_of_notifications": 4
  }
}

Error response examples:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Push Record not found"
}

Application Versions

Use this api to get the versions of application.

The URL to your GET request to get application versions is:

https://rtcp.vanso.com/api/app_ratings/get_versions

Request parameters:

Request example to get application versions:

GET https://rtcp.vanso.com/api/app_ratings/get_versions

Success response:

200 OK

{
  "versions": [
    "2.0",
    "1.0"
  ]
}

Troubleshooting

API Requests

Here are some common mistakes with making authenticated requests to the Interswitch Real-Time Communications Platform.

Are the headers present? You must have three custom headers in your request to successfully authenticate a request: HTTP_AUTH_APP_ID ("AUTH-APP-ID"), HTTP_AUTH_TIMESTAMP ("AUTH-TIMESTAMP") and HTTP_AUTH_SIGNATURE ("AUTH-SIGNATURE").
Is the timestamp valid? The timestamp must be of Coordinated Universal Time (UTC) in the ISO 8601 format. If this is the time now: 2024-11-21 07:18:39 +0000 (2024-11-21 07:18:39 UTC) then the time must be formatted like this: 2024-11-21T07:18:39Z.
The timestamp must be recent. We only authenticate 'new' requests. If your timestamp is too old it will not work. Timestamps in the future will not work either! You can check the time on our server to verify a discrepency: time now
Try alphabetizing your params. If you are having difficulty with a signature failure try to alphabetize the parameters in the request URL. The request parameters from the URL are processed by our server alphabetically when we create the comparison signature.
Signature should be lower-case. Make sure that the signature is in lower-case or else it will not match the one we create to authenticate your request.

Return to top

API Documentation v2

Authentication

Devices

Pushes

App Endpoints

iBeacons

APP Info

General

General Information

Documentation Styling

Authentication

Making API Requests from your app

Making API Requests to send notifications

Calculating Signature

Get User's Applications

Device Endpoints

Register Device

Unregister Device

Push Endpoints

Single Push

Broadcast Push

Targeted Push

GeoZone Push

App Endpoints

Recent Notifications

Delete Notifications

Read Receipts

Set Location

Application Rating Endpoints

Set Application Rating

Get Application Rating

iBeacon Endpoints

Register iBeacon

Get Single iBeacon Data

Get All iBeacon Data

Get Application Statistics

Get Application Statistics

Get Advertise Details

Get Advertise Details

Get Available Ad Zones

Get Available Ad Zones

Notification Statistics

Notification Statistics

Application Versions

Application Versions

Troubleshooting

API Requests