Push API

To use Push API you need to have individual User API token, which can be found in the settings of space.

You’ll see the block with User API token on the space settings page only in case if your tariff plan and access rights allow to use devtodev API. You can reset User API token or create it again on the same page.

Please attend, if you use several spaces, in every space user has individual User API token.

Request format

The request of assignment should be sent to:

​https://www.devtodev.com/api/v1/push/send?user_token=USER_API_TOKEN

Where

  • user_token - individual User API token of a user. It could be sent with both GET and POST methods.

  • v1 - the current version of API

Request content is sent with POST method in JSON format.

The body of a request can contain the following properties:

Property

Type

Description

user_token

string

Required. An individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods.

app_id

string

Required. An application identifier. It can be found in the application’s settings in the Integration section. Required.

campaign_tag

string

Optional. The name of a campaign. The grouping of statistics for the assessment of the efficiency of a campaign is made by the name of a campaign. The API Stats report can be found in the Push section.

pack_id

string

Optional. The unique identifier of a request. It is specified by a developer. It is used for the filtering of repeated sendings of identical requests in case of the loss of connection, etc. Requests with the same identifier can't be repeated during 10 minutes after their sending.

audience

array

Required. An array of mailing audience. The element of an array is an object with an individual for every platform set of user identifiers. It is allowed to specify several known identifiers for one user. The maximum number of elements of an array is 1000.

The lists of available identifiers can be found in the description to each platform.

ios

object

An object containing a notification and its properties for the iOS platform.

android

object

An object containing a notification and its properties for the Android platform.

win

object

An object containing a notification and its properties for the Windows platform. Use this object for any version of Windows (Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10).

uwp

object

An object containing a notification and its properties for the Windows 10 / WP 10. Don’t use this object for sending to other versions of Windows.

An example of a request for sending a simple notification to an iOS device:

​https://devtodev.com/api/v1/push/send

POST

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "idfa": "XXXXX-XXXXX-XXXXXX-XXXXXX"
    },
    {
        "idfa": "YYYYY-YYYYY-YYYYYY-YYYYYY"
    }],
    "ios": {
        "payload": {
            "text": "Hello world!"
        },
        "options": {
            "priority": "normal",
            "expire": 36000
        }
    }
}

Response format

If a request is formed correctly and there are no obstacles for sending a notification to users, an answer is JSON of the following type:

{
    "status_code": 200,
    "data": {
        "status": "complete",
        "result": {
            "audience": 100500,
            "successful": 100477,
            "erroneous": 23,
            "error_details": []
        }
    }
}

where

  • audience (number) - the number of users found

  • successful (number) - the number of successfully sent notifications

  • erroneous (number) - the number of notifications rejected by the delivery service

  • error_details (array) - a detailed description of reasons of a delivery fail

In case there is an error in a request, an answer is made in the following format:

{
    "status_code": 400,
    "errors": [{
        "code": 3,
        "msg": "Error description"
    }]
}

where

  • status_code (number) - a general status of an error

  • errors (array) - an array of error descriptions

  • code (number) - the exact code of an error from the table of errors

  • msg (string) - a brief description of an error

The list of possible errors is given in a table.

List of possible errors

Status code

Code

Value of "msg" field

Error description

500

1

Unknown Error

Unknown error. Please contact devtodev technical support.

400

2

Request body is empty

The empty body of the request. There is no POST data in the request.

400

3

Malformed json

JSON error in the body of the request. Fix the formatting error.

400

4

Field not found: %field_name%

An obligatory field can not be found. You need to complete the request with this field.

400

6

Invalid app id %app id value%

The requested project can not be found. An unknown application. This error can arise when a user makes a mistake with an app ID or when an application with this ID has been removed.

401

11

Authorization error. Wrong user token %user_token value%

Authorization error. The set token is wrong. “User_token” field. User API token.

401

12

Authorization error. User_token is not set.

Authorization error. “User_token” field is absent. User API token should be set either as a parameter in GET string of the request or in POST body of the request.

403

13

Access denied. You have no access to the app %app id value%

The error of access. User has no access to this application.

403

14

Access denied. You have no access to the report file %file id value%

The error of access. User has no access to this file. This error can arise if you have to access the application used in a previously created request.

403

15

Access denied. You have no access to API.

The error of access. No access to User API token. This error can arise when access rights have been changed (as a consequence of changing a user role or tariff plan)

403

23

Access denied. You have no access to Push API.

The error of access. This error can arise when you have no rights to Push API for your user role or tariff plan.

400

24

Push service is not enabled in an application settings.

Push service is disabled. Enable the service on the settings page of an app.

400

25

The devtodev SDK is not integrated with the application you specified

The SDK is not integrated

400

26

No push token has been received from the devtodev SDK integrated with the app you specified. Please make sure the SDK is integrated correctly.

No push token has been received from the devtodev SDK integrated with the app you specified. Please make sure the SDK is integrated correctly.

400

27

The audience array should not contain more than 1000 elements.

The audience array contains more than 1000 elements. Reduce the number of users in one request.

400

28

Unexpected value for field %field%. Received value: %value%. Expected values: %values%.

There is an unexpected value for the field. Use the recommendation and correct the request.

400

29

Unexpected field %field%

The request contains the field not specified in the documentation. The field must be excluded from the request.

400

30

Invalid value for field %field%. Received value: %value%. Expected: %description%

Invalid value has been attributed to the field. Use the recommendation and correct the request.

400

31

Notification payload size limit exceeded.

Reduce the payload size.

400

32

The sending was blocked. The request with the %pack_id% identifier has already been sent during previous 10 minutes.

Requests with the same identifier can't be repeated during 10 minutes after their sending.

400

33

The requested users have not been found, or there have been no push-token received from them.

The requested users have not been found, or there have been no push-token received from them.

Besides the errors listed above, error_details field may contain errors from the connected notification services. You can find descriptions of such errors in documentation for these services:

Last updated