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 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 note, if you use several spaces, in every space user has an individual User API token.

In order to display the notifications on the device, an SDK integration is required.

Push notifications

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, the answer is a 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, the 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 below.

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%	Access error. User has no access to this application.
403	14	Access denied. You have no access to the report file %file id value%	Access error. 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.	Access error. 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.	Access error. 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:

• Android (Firebase)
• iOS (APNS)
• Windows (WNS)