Push API

Overview

This API documentation covers submitting push jobs from external services.

URL scheme: https://<customer-id>.push.delivery/push-api/<endpoint>

To use the service you need HTTP basic auth. Data is sent as JSON via POST.

REST Endpoints

push

Submit a push job. Tags to be addressed can be specified via their id’s or their source id’s. For this endpoint a specific push user is available and can be looked up in the administration UI. Alternatively any user login can also be used to submit a push. If no appId’s are specified, it means all apps that are connected to the specified tags will be addressed, this is the default behavior.

The payload is typically an encoded JSON object, which then is transformed using a template for each platform. See Push templates information.

Table 1. Request Parameter Description
Name	Type	Description	Required	Example
tagIds	Array	the IDs of the tags	Either tagIds or tagSourceIds required	101, 102
tagSourceIds	Array	the source IDs of the tags	Either tagIds or tagSourceIds required	sport_football_team_fcb_goal, sport_football_team_fca_goal
filterTagIds	Array	the IDs of the tags that should be always present	Optional	103, 104
filterTagSourceIds	Array	the source IDs of the tags that should be always present	Optional	sport_language_german
appIds	Array	the IDs of the apps	Optional	110, 111
payload	String	the payload of the push as string, typically a JSON object (escaped)	Required	{ \'message \' : \'test\' }

fields in the payload will be automatically stringified as otherwise Firebase will process the notification in a disadvantageous way.

if the tag is expired notification will be not delivered.

Example URL

https://<customer-id>.push.delivery/push-api/push

Example POST Request with tag ID (content type: application/json)

{
    "tagIds": [ <id-number>, <id-number> ... ],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }"
}

Example POST Request with tag source ID (content type: application/json)

{
    "tagSourceIds": ["sport_football_team_fcb_goal", "sport_football_team_fca_goal"],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }"
}

Example POST Request with specific app ID (content type: application/json)

{
    "tagIds": [ <id-number>, <id-number> ... ],
    "payload": "{ \"field1\" : \"value\", \"field2\" : \"value\" ... }",
    "appIds" : [ <id-number> ]
}

Example Response (content type: text/plain)

  adfb51b1-b037-cf17-b1f1-fafa60de1203

The response will be a push job id that can be used for status queries.

In case of an invalid request, the response will be a HTTP 422 code. Invalid requests are missing for example payload, or tag id’s or specify non-existant tag source id’s.

status

Query the status of a push job. The status response will have an entry for each app addressed in the push job. It also will carry the transformed (by the push template) payload for each app.

Example URL

https://<customer-id>.push.delivery/push-api/status/<status-id>

Example GET Request

https://<customer-id>.push.delivery/push-api/status/adfb51b1-b037-cf17-b1f1-fafa60de1203

Example Response (content type: application/json)

[
   {
        key: {
            id: "<job-id-string>",
            platformId: <platform-id>,
            appId: <app-id>
        },
        created: <timestamp-long>,
        finished: <timestamp-long>,
        state: "<state-string>",
        totalCount: <count-long>,
        successCount: <count-long>,
        noFeedbackCount: <count-long>,
        errorCount: <count-long>,
        messages: [ ],
        transformedPayload: "{ \"field1\" : \"value\"}",
        lastPushSendOn: <timestamp-long>,
        lastFeedbackReceivedOn: <timestamp-long>,
        attemptsWithRetry: [
            {
                "totalCount": <count-long>,
                "failedCount": <count-long>,
                "lastPushSendOn": <timestamp-long>,
                "lastFeedbackReceivedOn": <timestamp-long>,
                "attempt": <number>
            },
            {
                "totalCount": <count-long>,
                "failedCount": <count-long>,
                "lastPushSendOn": <timestamp-long>,
                "lastFeedbackReceivedOn": <timestamp-long>,
                "attempt": <number>
            }
        ]
    }
]

Table 2. Response Description
Name	Type	Description
key	Object	Key for push status
created	Number	Timestamp when push job was created
finished	Number	Timestamp when push job was ended
lastPushSendOn	Number	Timestamp when the last push send out
lastFeedbackReceivedOn	Number	Timestamp when last feedback is received.
attemptsWithRetry	Object	When retry attempts are done, this contains the breakup of each attempt. First one will be the original attempt and others are the retries.
totalCount	Integer	Total device tokens
successCount	Integer	Device tokens for which success feedback is received from APNS or firebase
errorCount	Integer	Device tokens for which error feedback is received from APNS or firebase
noFeedbackCount	Integer	Device tokens for which no feedback received from APNS or firebase until the timeout
messages	Array	Errors if any. It can be errors from APNS or firebase or internal ones.
transformedPayload	String	Stringified payload after JOLT transformation
state	String	Current state of push job. Possible states are STARTING, RUNNING, FINISHED or FAILED