Using the API to send transactional push notifications

It is possible to use the Ortto API to send SMS messages by using a dedicated transactional push notification API.

Mobile push notifications are only available on selected Ortto plans.

HTTP method and request resources

Requests to send transactional push notifications in Ortto are submitted as a single POST method to the following URL:


 https://api.ap3api.com/v1/transactional/send-push

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Sending transactional push notifications

Ortto supports sending transactional push notifications via the API. You might want to use this feature to notify users of important updates, such as order status changes, new messages, or system alerts, directly to their devices in real-time.

Example of sending a single push notification

The example below sends a single transactional email to the contact ID 0065df3747712d384818ef00

json
 {
  "async": false,
  "pushes": [
    {
      "asset": {
        "push_name": "Example",
        "title": "Hi {{ people.first-name }}",
        "message": "Example transactional push notification",
        "image": "https://avatars.githubusercontent.com/u/47131913",
        "primary_action": {
          "title": "Primary",
          "link": "https://google.com"
        },
        "secondary_actions": [
          {
            "title": "youtube",
            "link": "https://youtube.com"
          },
          {
            "title": "google",
            "link": "https://google.com"
          }
        ],
        "platforms": ["web"]
      },
      "contact_id": "0065df3747712d384818ef00"
    }
  ]
}

Asset options for transactional push notifications

`push_name`	The campaign name. This can be any name you like, the recipient won’t see it.
`title`	The title of the push notification, which will be publicly visible.
`message`	The body message of the push notification.
`image`	The URL of the image that will be displayed.
`primary_action`	Triggered when the user clicks the notification, consisting of a `title` and `link` parameter.
`secondary_actions`	Triggered when the user clicks the notification, consisting of a `title` and `link` parameter. You can add up to 4 secondary actions.
`platforms`	Platforms where the push notification will appear. Supported values: `web`, `ios`, `android`. Mobile push notifications are only available on selected Ortto plans

Validation criteria

Below you can find the validation criteria for this API endpoint.

push_name, title, and message must not be empty.
platforms must contain at least one of the three supported values: web, ios, or android (non-matching options are ignored).
The URL in the image parameter must be valid.
primary_action must have a valid link provided for each platform listed in platforms (additional platforms are ignored).
Each secondary_action must have a valid link for every platform provided.