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:

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.

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:

Authentication

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

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:

Model

Device resources will contain the following information:

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:

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 as a minimum information to register a new device:

If an existing device is already registered with given udid-platform, the record will be updated. Otherwise, a new device will be registered.

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.

Update-only params

As an alternative to udid-platform identifier to update an existing record, it is possible to include the device_id of the previously created device.

If device_id is included, the udid and platform parameters are no longer mandatory, and the existing device will be updated with the information included on the request.

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"
}

For only update requests:

{
  "device_id": "39068e2378d700cb",
  "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 show

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

Request

Path

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

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}

Example request

curl -X GET \
  -H "X-TwinPush-REST-API-Token: ${REST_API_TOKEN}" \
  https://{{subdomain}}.twinpush.com/api/{{version}}/apps/313639abc/devices/456abcdefg

Response

The request will return a Device object that will contain the requested device.

If a device with given ID does not exist in the current application, a 404 "Device not found" response will be returned.

Example response

{
    "id": "456abcdefg",
    "push_token": "ffk1HTeyE-0:APA91bFoqq7Ceup_pk9cz_...",
    "last_registered_at": "2016-05-24 22:02:29 UTC",
    "created_at": "2016-05-24 22:02:29 UTC",
    "updated_at": "2020-09-26 11:36:56 UTC",
    "app_id": "313639abc",
    "platform": "android",
    "language": "es_ES",
    "device_code": "Aquaris_E5_HD",
    "device_model": "Aquaris E5 HD",
    "device_manufacturer": "Bq",
    "app_version": "2.6.0",
    "sdk_version": "2.7.1",
    "os_version": "5.0",
    "alias_device": null,
    "type": "Device",
    "active": true,
    "registration_updated_at": "2016-05-24 22:02:29 UTC",
    "custom_properties": []
}

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:

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:

Depending on the value set the behavior may change:

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 received notification

Informs that the device has received the given Notification.

Request

Path

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

Example request

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

Response

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

POST open notification

Informs that the user interacted with a sent Notification (usually opened fom notifications center). It is useful 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:

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:

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:

The available custom property types are:

Example request body

This example will create the property age with the integer value 43 for the selected device:

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

The following request will create the property favorite_music and will set the list of values for the selected device:

{
  "name": "favorite_music",
  "type": "enum_list",
  "value": ["Rock", "Blues", "Jazz"]
}

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:

Model

Notification representation objects will contain the following information:

GET show notification

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: 2KB for iOS7 and above.
• Android: 4 kilobytes

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

Parameters

The different parameters available to define the details of the notification or its target are described below.

1. Notification params

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

2. Target parameters

The following parameters are used to indicate which devices should receive the notification. A distinction is made between simple target, in which each device receives an identical notification, and multiple target, in which it is possible to customize the content of the notification received by each device.

2. 1. Simple target params

It allows to specify a list of elements of many types to be receiver of the Push Notification. Use only one of the following options to define the target for the notification.

2. 1. 1 Broadcast

The notification will be sent to all the active devices registered on the application.

Example payload param for a broadcast notification:

{
  "broadcast": true,
}

2. 1. 2. Device Id array

The notification will be sent to the active devices that match with the provided device_id array:

Example payload param for notification with device_id target:

{
  "devices_ids": ["1a2b3c4d5f","2b3c4d5f6g","3c4d5f6g7h"]
}

2.1.3. Alias array

The notification will be sent to the active devices linked with any of the provided aliases:

Example payload param for notification with alias array target

{
  "devices_aliases": ["john01", "peter41", "martha78"],
}

2. 1. 4. Segments

The notification will be sent to the active devices present in any of the provided segments:

Example payload param for notification with segments:

{
  "segments": ["Gold Users", "Silver Users"]
}

2. 1. 5 Target property

This target offers the option of sending the notification to active devices that have certain values in some of their properties.

It is possible to provide values that devices must have for up to 5 different properties. This way, the notification will be sent to the active devices that have any of the values provided for ALL listed properties.

That is, for each property, a device must have any of the provided values in order to be chosen as target of the notification.

Example payload param for a notification that will be sent to any device with the roles "Student" or "Teacher" and whose class is "Grade 1A", "Grade 1B" or "Grade 1B":

{
  "target_properties": {
    "role": ["Student", "Professor"],
    "class": ["Grade 1A", "Grade 1B", "Grade 2A"]
  }
}

2. 1. 6 Target property and segment

Target property target also supports filtering by segments, using the format described before. The notification will be sent to the devices selected by the target_properties target (as stated in the previous point) that are included in any of the selected segments.

In that case both parameters target_properties and segments must be included.

Example payload params for a notification that will be sent to any device whose class is "Grade 1A", "Grade 1B" or "Grade 1B" and that is contained in any of the "Students" or "Professors" segments:

{
  "target_properties": {    
    "class": ["Grade 1A", "Grade 1B", "Grade 2A"]
  }
  "segments": ["Students", "Professors"]
}

2. 2. Multiple target params

Multiple customized notifications can be send through device ID or device 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:

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 requests body

Scheduled broadcast notification with emojis:

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

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"
      ]
    }
  ]
}

DELETE notification

Removes a notification from the system and from all users' inboxes. Any delivery in progress will be cancelled.

Request

Path

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

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

X-TwinPush-REST-API-Key-Creator: ${REST_API_TOKEN_CREATOR}

Example request

curl -X DELETE \
  http://{{subdomain}}.twinpush.com/api/v2/apps/12mj18sja89/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.

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 currently being sent.
  • "sent": the sending process has been completed. This does not necessarily indicate success, as errors may have occurred during delivery. Inspect the "errors" attribute to check for possible incidents.
  • "error": there has been an error in the notification target or in the app settings that has prevented the delivery from taking place
  • "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
• received_count (integer): Number of devices that reported the reception of the push 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,
  "received_count": 69771,
  "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
• received_at (datetime): moment when the notification was received by the device. Will be null if push acknowledgement is not enabled or the notification has not received the notification (as it could happen with a device turned off or with push notifications disabled)
• 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",
      "received_at": "2016-03-01 13:36:17 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:

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",
      "received_at": "2016-03-01 13:36:17 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:

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.