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-qa.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-qa.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-qa.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-qa.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-qa.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-qa.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-qa.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-qa.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-qa.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
}