API Concepts

Twinpush is a platform designed and built with the goal of making the process of sending push notifications to users really easy and intuitive. With that goal in mind, we offer a REST API that offers a wide functionality to be consumed through simple Web Service calls.

What is REST?

It is a style of software architecture for distributed systems based on representations of resources and the manipulation of these resources through those representations.

TwinPush Resources

TwinPush handle the following resources:

  • Application: Is the first level of every API request. Represents a mobile application present in one or more platforms (iOS or Android).
  • Device: Is the representation of a mobile device registered in an Application of the platform.
  • Notification: A message created to be sent through a Push Notification to the devices of an Application. A notification is related to an application, but also with the devices to which it is targeted.

RESTful routes

TwinPush offers the functionality through the API using RESTful routes that utlizes HTTP verbs to keep unique paths to a minimum, while making it easy to integrate and debug.

To access to a resource methods, URL must contain the correct path for the desired object:

resource example path
Application /apps/:app_id/method
Notification /apps/:app_id/notifications/:notif_id/method
Device /apps/:app_id/devices/:device_id/method
Device Notifications /apps/:app_id/devices/:device_id/notifications/:notif_id/method

SSL

All the requests will be done with SSL, though HTTPS secure protocol calls.

Input & Output Format

All API methods will return JSON objects as result and will expect JSON objects as body parameters in UTF-8 Character set.

For POST and PUT requests, it is required to include the following header:

Content-Type: application/json; charset=utf-8

Pagination

In order to allow working with a big amount of records, TwinPush offers paginated results for every Web Service that returns a collection of objects.

param description default
per_page The number or results per pageĀ  30
page Current page. First page is 0. If 0 or negative value is given, page 1 will be returnedĀ  1

Let's see an example

curl -X GET \
-H "X-TwinPush-REST-API-Token: ${REST_API_TOKEN}" \
-H "Content-Type: application/json" \
https://{{subdomain}}.twinpush.com/api/{{version}}/apps/1a2b3c4d5f/devices?page=1&per_page=2

The response will be:

{
  "offset": 0,
  "total_pages": 2,
  "total_entries": 4,
  "per_page": 2,
  "current_page": 1,
  "objects": [
    {
      "id": "2b3c4d5f6g",
      "alias_device": "techie4",
      "created_at": "2013-07-30 20:16:55 +0000",
      "updated_at": "2013-08-28 14:20:35 +0000",
      "last_registered_at": "2013-07-30 20:16:55 +0000",
      "app_id": "1a2b3c4d5f",
      "type": "Device"
    },
    {
      "id": "3c4d5f6g7h",
      "alias_device": "techie4",
      "created_at": "2013-07-30 20:16:55 +0000",
      "updated_at": "2013-08-28 14:20:35 +0000",
      "last_registered_at": "2013-07-30 20:16:55 +0000",
      "app_id": "1a2b3c4d5f",
      "type": "Device"
    }
  ],
  "references": [] 
}

In some cases, when a page without results is requested the answer will be the error NotFound, with the HTTP code 404.

Note: For clarity, the pagination options will be omitted in the rest of the documentation.

HTTP Status Codes

For each request you make to the this API, we will return an HTTP status code. Following convention, the following status codes can be returned:

  • 200 Success. The object was found, created, updated or deleted successfully.

  • 404 The object you're looking for doesn't exist.

  • 402 Not authorized to view this object.

  • 406 Not Acceptable (invalid format). You're probably sending wrong JSON or you need to specify the HTTP headers correctly.

  • 422 Unprocessable entity. Some of the given parameters is incorrect.

  • 500 Server Error (hopefully not!). This means our server has some sort of problem while processing the request.

Common error messages

When an error in a request occurred, in addition to the HTTP error code, the system will try to return a detailed error message to help the developer to debug its integration. The details of the error will be returned as a JSON String in the response body with the following format:

{
  "errors": {
    "type": "ErrorType"
    "message": "Detailed error message",
  }
}

The possible errors returned by the API Web Services are listed below:

Code Error Type Description
403 InvalidToken API Key Token is not valid or does not match with App ID
403 InvalidCreatorToken Creator API Key Token is not valid or does not match with App ID
404 AppNotFound Application not found for given application_id
404 DeviceNotFound Device not found for given device_id
404 NotificationNotFound Notification not found for given notification_id
404 DeliveryNotFound Delivery not found for given notification and device
422 NotificationNotCreated Some of the parameters given when trying to create a notification is not valid
422 DeviceNotCreated Some of the parameters given when trying to register a device is not valid
422 DeviceNotUpdated Some of the parameters given when trying to update a device info is not valid
422 InvalidProperty The type or the value given when trying to assign a device property is not valid

Authentication

TwinPush requires the inclusion of some parameters in the request to grant access to the functionality through the REST API:

Auth Param Description Required
App ID Identifier of the TwinPush application Always
Device ID Identifier of the device Requests of already registered devices
API Token Randomly generated authentication key Register and unregister device requests
API Creator Token Authentication key for creating notifications Sending notifications

Application ID

All the requests must identify the application by providing the Application ID as an URL parameter:

https://app.twinpush.com/api/v2/apps/${app_id}/...

The Application ID is a 16 alphanumeric characters string that can be obtained from the TwinPush console and that will be different for every registered application.

Examples of application ids are:

cs555ab2356a37a0
ab42d6512343133a

Additional authentication

In addition to Application ID, it is necessary an extra authentication parameter in every request. Depending on request type, this additional parameter method will vary:

  • Device ID: Required for already registered devices
  • API Token: Required for register and unregister requests
  • API Creator Token: Required for requests that creates a notification

Device ID

Request that are launched from already registered devices will authenticate by providing its device_id. If device_id and current application matches, access will be granted.

The Device ID is a 16 characters alphanumeric string that is provided from TwinPush when the device is registered.

It is set in every request as a request parameter:

https://app.twinpush.com/api/v2/apps/${app_id}/devices/${device_id}/...

API Token

Required for register and unregister requests, it is a 32 alphanumeric characters string that can be obtained in the TwinPush web console.

These are examples of valid tokens:

1c5cabc4055e03c64f123d9dbfb4d0e9
ca044e0bc6a4f1cg23d9dbfb4251dhy6

The token will be passed as a header with X-TwinPush-REST-API-Token key, like in this example:

curl -X GET \
-H "X-TwinPush-REST-API-Token: ${REST_API_TOKEN}"
https://app.twinpush.com/api/v2/....

API Creator token

With the same format than the API Token, the Creator Token is required for requests that creates a notification.

It is included as a header with X-TwinPush-REST-API-Key-Creator, like it is displayed in the following example:

curl -X POST \
-H "X-TwinPush-REST-API-Key-Creator: ${REST_API_TOKEN_CREATOR}" \
-H "Content-Type: application/json; charset: utf-8" \
https://app.twinpush.com/api/v2/notifications

Devices

The device model is a representation of a phisical device that can be registered in the TwinPush platform (like a smartphone or a tablet). Android and iOS devices are supported.

Available methods

To access to the full functionality of the devices resources, the following methods are available:

method name description
GET index obtains the paginated list of application devices associated
POST register create or update device registration in TwinPush
GET get badge obtains the current badge count of the device.
POST update badge updates the badge count of the device.
POST open notification notifies that the notification has been opened by the user
POST open app reports that the user opened the application
POST close app notifies that the application has been closed or went to background execution
POST update location updates the current location of the device
POST search notifications search of the notifications received by a device
POST set custom property assigns value for a device custom property
DELETE clear properties deletes all the properties values associated with a device

Model

Device resources will contain the following information:

attribute type description
id string Unique identifier device in the platform
alias_device string Alias assigned to device. It is commonly used as a link with bussiness logic
platform string Physical device platform. Available values are ios or android.
created_at datetime Device first registration date
updated_at datetime Device last update date. This field will change when any device usage stat is reported, and will represent the last usage time
last_registered_at datetime Represents the last time that the device called register service to update its token, device alias or custom properties
language string Language and region, joined by undescore
device_code string Physical device model code
device_model string Physical device commercial name
device_manufacturer string Physical device manufacturer
app_version string Client application version
sdk_version string Version of the TwinPush SDK integrated in the client application
os_version string Android or iOS Operating System version

GET index

Obtains the paginated list of devices associated with the given application.

Request

Path

GET /apps/${app_id}/devices

Headers: It is required to include the TwinPush Token in the X-TwinPush-REST-API-Token header.

 X-TwinPush-REST-API-Token: ${REST_API_TOKEN}

Optional Params

The following URL parameters are optional:

param description
date If present, it will only return devices which registration info has changed since given date. Valid date formats are ("2014-04-21" or "2014-04-21T13:00:43+02:00"). Registration info will be considered changed when any of the following fields is updated: active, alias_device, push_token, custom_properties
alias If present, it will only return devices whose alias_device property match with the given parameter (ignoring case). Can be used to obtain the active devices associated to a given alias

Example request

curl -X GET "https://app.twinpush.com/api/v2/apps/12mj18sja89/devices?date=2014-11-01&page=1&per_page=50" \
  -H "X-TwinPush-REST-API-Token: xxxx
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices

Response

Response body will contain the array of application devices that match the included filters (if any).

Example response

{
  "objects": [
    {
      "id": "a7c9dc0555019759",
      "push_token": "5geamqy5 6xmrxfk1 5zpbcxmw ez3w7ksf cscpr55t trknkzap 7yyt41ss g6jrw7qz",
      "last_registered_at": "2016-03-01 12:47:25 UTC",
      "created_at": "2016-03-01 12:47:25 UTC",
      "updated_at": "2016-03-01 12:47:25 UTC",
      "app_id": "816b6f7f555b5982",
      "platform": "ios",
      "language": "en_GB",
      "device_code": "iPad2",
      "device_model": "iPad 2",
      "device_manufacturer": "Apple",
      "app_version": "1.4.2",
      "sdk_version": "1.0",
      "os_version": "9.1",
      "alias_device": "techie4",
      "type": "Device"
    }
  ],
  "references": []
}

POST register

Creates or updates the subscription of a device in the platform.

Request

Path

POST /apps/${app_id}/devices/register

Headers: To launch this request it is needed to include the TwinPush Token in the X-TwinPush-REST-API-Token header.

 X-TwinPush-REST-API-Token: ${REST_API_TOKEN}
 Content-Type: application/json; charset: utf-8

Required params

The register request requires the following parameters:

param description
udid unique identifier of the device per application and platform. A good choice is the ANDROID_ID for Android and the identifierForVendor for iOS
platform Device platform. Available values are: "ios" for Apple iOS devices and "android" for Google Android devices
push_token Token provided for the device by the Push notification services (known as registrationId for Android and token for iOS). If the push token is not provided, the device will not receive push notifications, but it will be able to report usage statistics.

Optional Params

Register service accepts some optional parameters that can be included or not in the request body. The associated properties to each param will be set to null if value is empty and will be ignored if not present in the request.

param description example
alias_device Value to associate the device to a user of the client platform "username"
language Language and region, joined by undescore "en_ES", "en_GB"
device_code Device model code "osprey_umts"
device_model Device commercial name "iPad 2", "iPhone 6S"
device_manufacturer Manufacturer "Apple", "Samsung"
app_version Client application version "1.0", "2.0.1"
sdk_version TwinPush SDK version "2.0.3", "3.1"
os_version OS (Android or iOS) version "9.1", "5.1"

Example request body

{
  "udid": "002ebf12a1255ddfa73967c3c5d20177",
  "platform": "ios",
  "push_token": "5geamqy5 6xmrxfk1 5zpbcxmw ez3w7ksf cscpr55t trknkzap 7yyt41ss g6jrw7qz",
  "alias_device": "techie4",
  "platform": "ios",
  "language": "en_GB",
  "device_code": "iPad2",
  "device_model": "iPad 2",
  "device_manufacturer": "Apple",
  "app_version": "1.4.2",
  "sdk_version": "1.0",
  "os_version": "9.1"
}
{
  "udid": "f12a1255ddfjd123",
  "platform": "android",
  "push_token": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjv9YtT8OvPWGJhQMRK3rZuJEcl7B38q",
  "alias_device": "techie4"
}

Example request

curl -X POST \
  -H "X-TwinPush-REST-API-Token: ${REST_API_TOKEN}" \
  -H "Content-Type: application/json; charset: utf-8" \
  -d '{ "udid": "002ebf12a1255ddfa73967c3c5d20177", "platform": "ios", "push_token": "5geamqy5 6xmrxfk1 5zpbcxmw ez3w7ksf cscpr55t trknkzap 7yyt41ss g6jrw7qz",  "alias_device": "techie4"}' \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices/register

Response

The request will return an array of Device objects that will only contain the created (or updated) device.

The id value of the device will be necessary to identify the device in subsequent requests.

Example response

{
  "objects": [
    {
      "id": "a7c9dc0555019759",
      "push_token": "5geamqy5 6xmrxfk1 5zpbcxmw ez3w7ksf cscpr55t trknkzap 7yyt41ss g6jrw7qz",
      "last_registered_at": "2016-03-01 12:47:25 UTC",
      "created_at": "2016-03-01 12:47:25 UTC",
      "updated_at": "2016-03-01 12:47:25 UTC",
      "app_id": "816b6f7f555b5982",
      "platform": "ios",
      "language": "en_GB",
      "device_code": "iPad2",
      "device_model": "iPad 2",
      "device_manufacturer": "Apple",
      "app_version": "1.4.2",
      "sdk_version": "1.0",
      "os_version": "9.1",
      "alias_device": "techie4",
      "type": "Device"
    }
  ],
  "references": []
}

GET badge

Obtains the current badge count associated with the current device. This value can be altered when notifications are sent to the device or when the update_badge API method is called.

Request

Path

GET /apps/${app_id}/devices/${device_id}/badge

Example request

curl -X GET \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices/1a2b3c4d5f/badge

Response

It returns a simple hash object with one attribute:

attribute type description
badge int Badge count of current device

Example response

{
  "badge": 6
}

POST update badge

Updates the badge count of a device.

Request

Path

 POST /apps/:app_id/devices/:device_id/update_badge

Headers

 Content-Type: application/json; charset: utf-8

Required params

Update badge request requires a single parameter:

param description
badge New value for device badge

Depending on the value set the behavior may change:

value description example
numeric The badge will be updated to given value 0, 1
plus sign and number Device badge will be incremented by given amount "+1", "+2"
minus sign and number Device badge will be decreased by given amount "-1", "-2"

If the result value is negative it will be set to 0.

Example request body

{
  "badge": "+1"
}

Example request

curl -X POST \
  -H "Content-Type: application/json; charset: utf-8" \
  -d '{ "badge": 12 }' \
  https://{{subdomain}}.twinpush.com/api/{{version}}/update_badge

Response

It will return an OK (HTTP 200) code if request is successful.

POST open notification

Notifies that the user interacted with a sent Notification (usually opened fom notifications center). It is usefull to determine the success of a sent notification based on its opening rate.

Request

Path

 POST /apps/${app_id}/devices/${device_id}/notifications/${notif_id}/open_notification

Example request

curl -X POST \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/623c8befd3f1b7f3/devices/28be4fd32b731f3/notifications/1441befd34f112/open_notification

Response

It will return an OK (HTTP 200) code if request is successful.

POST open app

Notifies that the user opened the application. This info is used for statistics and activity reports and it is important to determinate wether a device is active or inactive for license limit purposes.

Request

Path

POST /apps/${app_id}/devices/${device_id}/open_app

Example request

curl -X POST \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/623c8befd3f1b7f3/devices/28be4fd32b731f3/open_app

Response

It will return an OK (HTTP 200) code if request is successful.

POST close app

Notifies that the application has been closed or went to background. This info is used for statistics and activity reports.

Request

Path

POST /apps/${app_id}/devices/${device_id}/close_app

Example request

curl -X POST \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/623c8befd3f1b7f3/devices/28be4fd32b731f3/close_app

Response

It will return an OK (HTTP 200) code if request is successful.

POST update location

Updates the current location (latitude and longitude) of a device. The location can be used for statistics or segmentation purposes.

Request

Path

POST /apps/${app_id}/devices/${device_id}/report_statistics

Headers

Content-Type: application/json; charset: utf-8

Required params

The following attributes are required, wrapped in a device JSON object:

param description range
latitude The latitude attribute of the device location -90 to 90
longitude The longitude attribute of the device location -180 to 180

Example request body

{
  "device": {
    "latitude": 4.111,
    "longitude": 10.111
  }
}

Example request

curl -X POST \
  -H "Content-Type: application/json; charset: utf-8" \
  -d '{ "device": {"latitude": 4.111, "longitude": 10.111} }' \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/623c8befd3f1b7f3/devices/28be4fd32b731f3/report_statistics

POST search device notifications

Makes a paginated search of the notifications received by a device. It allows filtering by notification tags.

Request

Path

POST /apps/${app_id}/devices/${device_id}/search_notifications

Headers

 Content-Type: application/json; charset: utf-8

Optional Params

The request allows the inclusion of the following optional parameters:

param description example
tags Returns notifications that contains all the given tags ["alerts", "critical"]
no_tags Returns notifications that does not contains any of the given tags ["main_inbox"]

Example request body

{
  "tags": ["moritaka","one"],
  "no_tags": ["two"]
}

Example request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["moritaka", "one"] }' \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices/1a2b3c4d5f/search_notifications

Response

It returns a paginated array of notification objects:

Example response

{
  "objects": [
    {
      "id": "fd99bf658771385a",
      "sound": null,
      "alert": "Notification message",
      "title": "Title for Android",
      "badge": "+1",
      "custom_properties": {
        "scope": "public",
        "campaign": "001"
      },
      "tp_rich_url": "http://twincoders.com/",
      "delivery_speed": "normal",
      "group_name": "API Deliveries",
      "send_since": "2016-03-01 13:34:50 UTC",
      "last_sent_at": "2016-03-01 13:34:51 UTC",
      "tags": [
        "tp_rich"
      ],
      "type": "Notification"
    }
  ]
}

POST set custom property

Assign the value for the given custom property at the selected device. Custom properties are useful to create segmented targets and to obtain statistics based on custom information.

Request

Path

POST /apps/${app_id}/devices/:device_id/set_custom_property

Headers

 Content-Type: application/json; charset: utf-8

Required params

The following parameters are required:

param description
name name of the custom property to assign value to. If property does not exist, it will be created
type type of the value of the property. Available types are described below
value value to assign to the property. If null, property will be deleted from device

The available custom property types are:

type description value example
string A text as a sequence of characters "iPhone X", "New York"
boolean Logic data type with two possible values: true or false true, false
integer A number without fractional component 26, -6
float A number with fraction precision using floating point. The decimal separator is the '.' (dot) character. 25.0, -1,999.95
enum A string value that is contained on a small set of possible values. Enum properties can be later used for segmentation "Female", "VIP client"

Example request body

{
  "name": "age",
  "type": "integer",
  "value": 43
}

Example request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "name": "age", "type": "integer", "value": 43 }' \
  https://{{subdomain}}.twinpush.com/api/v2/apps/623c8befd3f1b7f3/devices/923c8befd3f1b7f1/set_custom_property

Response

It will return an OK (HTTP 200) code if request is successful.

DELETE clear custom properties

Deletes all the custom property values associated with the given device.

Request

Path

DELETE /apps/${app_id}/devices/${device_id}/clear_custom_properties

Deletes all the custom property values associated with the given device

Example request

curl -X DELETE \
  -H "Content-Type: application/json" \
  http://{{subdomain}}.twinpush.com/api/v2/apps/12mj18sja89/devices/1a2b3c4d5f/clear_custom_properties

Response

It will return an OK (HTTP 200) code if request is successful.

Notifications

The notification resource is the representation of a message sent to a physical device through a Push Notification.

Available methods

To access to the full functionality of the notification resources, the following methods are available:

method name description
GET show obtains details from a previously created notification
POST create creates a new notification to be delivered from the platform
GET report obtains delivery statistics for a given notification
GET deliveries obtains paginated list of deliveries for a given notification
GET inbox retrieves the notifications sent to the user by the alias device
GET inbox_summary obtains the total and unopened count of the alias notifications inbox
DELETE delete inbox removes a notification from the inbox of the associated user

Model

Notification representation objects will contain the following information:

attribute type description
id string Unique identifier for the notification
title string Title to be displayed in Android notifications center or TwinPush inbox
alert string Message to be displayed in the Push Notification
tp_rich_url string Content URL for rich notifications
custom_properties HashMap Map of custom properties set for the notification
tags String[] List of tags set to categorize notification
send_since datetime Date and time of scheduled sending
sound string Custom sound set to notification
badge string Modifier for device badge count
name string Internal name for campaign identification
group_name string Name of the group where notification is included
delivery_speed string Defines the number of deliveries per minute when sending the notification. Available values are: instant, fast, normal or slow.
protected_content boolean If set to true, the content of the notification (alert and title) will be hidden from API requests and Web Platform and will only be displayed to the devices targetted by the notification.

GET show

Returns all the details of a previously created notification.

Request

Path

Find application notification from ID:

GET /apps/${app_id}/notifications/${notif_id}

Also for notifications received from a device:

GET /apps/${app_id}/devices/${device_id}/notifications/${notif_id}

Example request

curl -X GET \
https://{{subdomain}}.twinpush.com/api/{{version}}/devices/1a2b3c4d5f/notifications/2b3c4d5f6g

Response

It returns a single notification object:

Example response

{
  "id": "2b3c4d5f6g",
  "sound": null,
  "alert": "Notification message",
  "title": "Title for Android",
  "badge": "+1",
  "custom_properties": {
    "scope": "public",
    "campaign": "001"
  },
  "tp_rich_url": "http://twincoders.com/",
  "delivery_speed": "normal",
  "group_name": "API Deliveries",
  "send_since": "2016-03-01 13:34:50 UTC",
  "last_sent_at": "2016-03-01 13:34:51 UTC",
  "tags": [
    "tp_rich"
  ]
}

POST create

Creates a new notification to be delivered from the platform. It requires at least the specification of the message that will be displayed and a target to be delivered to.

Payload limit

The maximum length for the fields of a notification is conditioned by the maximum payload size allowed for Push Services of Apple and Google:

  • iOS: 256 bytes. Increased to 2KB for iOS7 and above.
  • Android: 1 kilobyte

Inside this size limit it is included all the notification info that is sent to the device: title, alert, sound, badge, custom_properties, etc.

TwinPush tries to adjust the size of the Payload by trimming the alert if needed, but is recommended to use short URLs and make a responsible use custom properties.

Notification Target

Each notification must have one (and only one) target parameter that defines wich devices will receive the message. Target can be defined by two different methods:

  • Simple target: Allows to specify a list of elements of many types to be addressee of the message
  • Multiple target: Offers the ability to customize the content of the message received by each addressee. This way each user may receive a different message customized for each within the same notification.

Request

Path

POST /apps/${app_id}/notifications

Headers: To create notifications it is required to include the Application Creator Token header.

X-TwinPush-REST-API-Key-Creator: ${REST_API_TOKEN_CREATOR}
Content-Type: application/json; charset: utf-8

Notification params

The parameters that define the content and category of the notification are the following:

param description
Content params
alert The text that will be shown in the push notification received in devices. This parameter is mandatory
title Notification title for Android and for TwinPush message inbox
url URL to be opened to display rich content when the user opens the notification
custom_properties Hash map of custom properties that will be reported to the user device in the notification payload
badge The number that the user will see in the badge indicator of the app when the notification is received (only iOS). Default value is +1
Additional params
delivery_speed Determines the number of deliveries per minute to be send for the recipients of this notice. Slowing delivery speed will help to avoid overloading client servers due to many simultaneous app openings. Available values are:
  • instant: will send all the notifications to the target as soon as possible
  • fast: will deliver 100.000 notifications per minute
  • normal: (default) will deliver 1.000 notifications per minute
  • slow: will deliver 100 notifications per minute
sound The name of the file you should have as a resource in your application, and it's the one that will be played when a notification is received
send_since The time when the push notification will be sent, in format yyyy-MM-dd HH:mm:ss Z
tags An array of strings to categorize or differentiate in the future this notification from others
name Internal campaign name. It makes easier to differentiate the notifications with a similar message.
group_name Name of the group where the notification will be included. Notification Groups allows to display combined information and statistics of multiple notifications.
inbox Boolean value that defines whether the notification will be included or not in the notifications inbox of the user associated with the target device.
protected_content Boolean value. If set to true, the content of the notification (alert and title) will be hidden from API requests and Web Platform and will only be displayed to the devices targetted by the notification. This option allows sending private information that will only be visible by the receiver.

Simple target params

Allows to specify a list of elements of many types to be addressee of the Push Notification:

param description type
broadcast If set to true, the notification will be sent to all the devices registered in the application Boolean
devices_ids Array of device identifiers to be target of the notification String[]
devices_aliases Array of device alias to be target of the notification String[]
segments Devices that fulfill the conditions of any of the previously created selected segments String[]
target_property Devices that have any of the selected values for given property.
This param is a JSON object formed by two additional attributes:
  • name: string property identifier
  • values: array of string values that devices will have to match to be selected as target of the notification
Object

Multiple target params

Multiple target notifications can be send through device ID or device alias:

param description
multiple_devices Target that allows to customize the content of the notification by device id
multiple_alias Target that allows to customize the content of the notification by alias

It is possible to customize the payload information sent to every device or alias targeted in a notification.

This is done specifying a the target through a Hash where every key is the target (device_id or alias) and the content is another hash of fields to override from the notification content parameters.

Through this method it is possible to customize the content fields of the notification received for every specified target:

attribute description
title If defined, it will replace the title of the notification received by the target
alert If defined, it will replace the displayed notification message
url If defined, it will override the URL of the rich content
badge If defined, it will override the badge indicator of the main notification
custom_properties Properties defined by target will be merged with the notification properties overwriting when two keys collide

If any of there parameters is not set, the message received by the user will contain the basic information defined in the main notification parameters.

Example request body

Scheduled broadcast notification:

{
  "broadcast": true,
  "title": "Welcome to TwinPush",
  "alert": "This is the message displayed in Notifications Center",
  "url": "http://www.inception-explained.com"",
  "custom_properties": {"key1": "value1", "key2": "value2"},
  "badge": "+1",
  "delivery_speed": "slow",
  "sound": "waves",
  "send_since": "2015-10-10 15:14:33 +0000",
  "tags": ["one", "two"],
  "group_name": "Commercial Offers"
}

Notification by device IDs with instant delivery:

{
  "alert": "This is the message displayed in Notifications Center",
  "devices_ids": ["1a2b3c4d5f","2b3c4d5f6g","3c4d5f6g7h"]
}

Notification by custom property with emojis:

{
  "alert": "Everything is OK \ud83d\udc4c\ud83c\udffb",
  "target_property": {
    "name": "Civil status",
    "values": [
      "Single",
      "Divorced"
    ]
  }
}

Notification with multiple target by alias:

{
  "alert": "This is the message displayed in Notifications Center",
  "multiple_alias": {
    "allan_poe": { "alert": "Hi Allan, welcome to TwinPush" },
    "edgar_allan": { "alert": "Hi Edgar, welcome to TwinPush", "custom_properties": { "private": true } },
    "mike_crichton": { "alert": "Hi Mike, welcome to TwinPush", "url": "http://example.com" },
    "annonymous": {}
  }
}

Example request

curl -X POST \
  -H "X-TwinPush-REST-API-Key-Creator: ${REST_API_TOKEN_CREATOR}" \
  -H "Content-Type: application/json; charset: utf-8" \
  -d '{
      "alert": "Test!",
      "send_since": "2013-10-10 15:14:33 +0000",
      "url": "http://www.inception-explained.com/",
      "devices_aliases": ["john"]
      }' \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/notifications

Response

It will return an array of notifications with a single object that represents the created notification:

Example response

{
  "objects": [
    {
      "id": "2b3c4d5f6g",
      "sound": null,
      "alert": "Notification message",
      "title": "Title for Android",
      "badge": "+1",
      "custom_properties": {
        "scope": "public",
        "campaign": "001"
      },
      "tp_rich_url": "http://twincoders.com/",
      "delivery_speed": "normal",
      "group_name": "API Deliveries",
      "send_since": "2016-03-01 13:34:50 UTC",
      "last_sent_at": "2016-03-01 13:34:51 UTC",
      "tags": [
        "tp_rich"
      ]
    }
  ]
}

GET report

Obtains delivery statistics for a given notification.

Request

Path

GET /apps/${app_id}/notifications/${notif_id}/report

Headers

X-TwinPush-REST-API-Token: ${REST_API_TOKEN}

Response

The response body contains an object with the following fields:

  • status (string): Current status of the notification. Available values are:
    • "draft": the notification has not been activated yet
    • "sending": the notification is being send
    • "sent": sending process has been completed
    • "scheduled": the notification has been scheduled for a future send
    • "campaign_active": a currently active campaign
    • "campaign_inactive": a currently inactive campaign
    • "campaign_expired": a finished campaign
  • delivery_count (integer): Number of deliveries made for the notification
  • opening_count (integer): Number of devices that did open the notification
  • errors (object[]): List of errors reported for notification
    • platform (string): Identifier of the platform, if the error is related just with a single platform. Possible values are "ios", "android" or "all"
    • level (string): Error level. Available values are "critical", "error" or "warning"
    • key (string): Error category key
    • message (string): Detailed error description
    • created_at (datetime): Moment when the error was registered
  • notification (object): Notification basic info

Example response

{
  "status": "sent",
  "delivery_count": 82640,
  "opening_count": 17534,
  "errors": [
    {
      "platform": "ios"
      "level": "critical",
      "key": "InvalidToken",
      "message": "Provided token is not valid",
      "created_at": "2015-01-14 10:31:57 UTC",
    }
  ],
  "notification": {
    "title": "Welcome to TwinPush",
    "alert": "Welcome to the Push notification platform TwinPush",
    "badge": "+1",
    "custom_properties": {},
    "id": "12342a1234b74abc",
    "sound": "",
    "tags": [
      "tp_rich",
      "vip-inbox"
    ],
    "tp_rich_url": "http://goo.gl/kf7bgq",
    "send_since": "2014-11-07 11:24:12 UTC"
  }
}

GET deliveries

Obtains paginated list of all the deliveries for a given notification. This is useful to obtain exactly who has been the recipient of the notification and also who has opened it.

Request

Path

POST /apps/${app_id}/notifications/${notif_id}/deliveries

Headers

 X-TwinPush-REST-API-Token: ${REST_API_TOKEN}

Response

Response body will contain a paginated array of delivery objects. Each delivery will contain the following information:

  • id (integer): Unique identifier of the delivery
  • created_at (datetime): moment when the notification was sent
  • open_at (datetime): moment when the notification was open in the device. Will be null if user has not opened the notification
  • device (object): Target device info

Example response

{
  "offset": 0,
  "total_pages": 1,
  "total_entries": 0,
  "per_page": 30,
  "current_page": 1,
  "objects": [
    {
      "id": 45264,
      "created_at": "2016-03-01 13:34:51 UTC",
      "open_at": null,
      "device": {
        "id": "a7c9dc047d019759",
        "push_token": null,
        "last_registered_at": "2016-03-01 12:47:25 UTC",
        "created_at": "2016-03-01 12:47:25 UTC",
        "updated_at": "2016-03-01 12:47:25 UTC",
        "app_id": "816b6f7f129b5982",
        "platform": "ios",
        "language": "en_GB",
        "device_code": "iPad2",
        "device_model": "iPad 2",
        "device_manufacturer": "Apple",
        "app_version": "1.4.2",
        "sdk_version": "1.0",
        "os_version": "9.1",
        "alias_device": "user@mail.com",
        "type": "Device"
      }
    }
  ]
}

GET inbox

Makes a paginated search of the notifications sent to an user through the device alias. It allows filtering by notification tags.

Request

Path

GET /apps/${app_id}/devices/${device_id}/inbox

Optional Params

The request allows the inclusion of the following optional parameters:

param description example
tags Returns notifications that contains all the given tags ["alerts", "critical"]
no_tags Returns notifications that does not contains any of the given tags ["main_inbox"]

Example request

curl -X GET \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices/1a2b3c4d5f/inbox?tags[]=alerts&tags[]=critical

Response

It returns a paginated array of objects that offers delivery information and wraps a notification object:

Example response

{
  "objects": [
    {
      "id": "2785b9d61574e029",
      "created_at": "2016-03-01 13:34:50 UTC",
      "open_at": "2016-03-01 13:34:50 UTC",
      "notification": {
        "id": "fd99bf658771385a",
        "sound": null,
        "alert": "Notification message",
        "title": "Title for Android",
        "badge": "+1",
        "custom_properties": {
          "scope": "public",
          "campaign": "001"
        },
        "tp_rich_url": "http://twincoders.com/",
        "delivery_speed": "normal",
        "group_name": "API Deliveries",
        "send_since": "2016-03-01 13:34:50 UTC",
        "last_sent_at": "2016-03-01 13:34:51 UTC",
        "tags": ["tp_rich"],
        "type": "Notification"
      }
    }
  ]
}

GET inbox summary

Obtains a fast summary of the notification inbox associated to the current device alias. It offers the total notification count and the unopened notification count.

Request

Path

GET /apps/${app_id}/devices/${device_id}/inbox_summary

Example request

curl -X GET \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/12mj18sja89/devices/1a2b3c4d5f/inbox_summary

Response

It returns a simple hash object with two attributes:

attribute type description
total_count int Total number of notifications present in the alias inbox
unopened_count int Number of notifications that has not been checked as opened. Useful to display a badge indicating pending notifications

Example response

{
  "total_count": 67,
  "unopened_count": 2
}

DELETE inbox notification

Removes the selected notification from the inbox of the user (or alias) associated to the device.

Request

Path

DELETE /apps/${app_id}/devices/${device_id}/notifications/${notification_id}

Example request

curl -X DELETE \
  http://{{subdomain}}.twinpush.com/api/v2/apps/12mj18sja89/devices/1a2b3c4d5f/notifications/8a2bdm1d50

Response

It will return an OK (HTTP 200) code if request is successful or a NotFound (HTTP 404) if notification can not be found.