POST Transactional Notifications

Endpoint URL: https://api.carnivalmobile.com/v6/transactional/notifications

Parameters

Body Parameters

Name Type Required
to object Yes
group string Yes
notification object Yes
extra_filters array of objects No

Examples

cURL

Copy 
curl -X POST -u :$API_KEY -H "Content-type: application/json" -H 'Accept: application/json' https://api.carnivalmobile.com/v6/transactional/notifications -d '{
  "to": { "field": "user_id", "value": "john_doe" },
  "group" : "coupon-codes",
  "notification" : {
    "payload": {
      "alert": "Check out this rich push!",
      "badge": 1,
      "sound": "Default.caf",
      "category": "TEST_CATEGORY",
      "mutable_content": true,
      "_st": {
        "image_url": "https://www.mysite.com/img.png"      }
    }
  }
}'

Rich Push

Copy 
curl -X POST -u :$API_KEY -H "Content-type: application/json" -H 'Accept: application/json' https://api.carnivalmobile.com/v6/transactional/notifications -d '{
  "to": { "field": "user_id", "value": "john_doe" },
  "group" : "coupon-codes",
  "notification" : {
    "payload": {
      "alert": "Check out this rich push!",
      "badge": 1,
      "sound": "Default.caf",
      "category": "TEST_CATEGORY",
      "mutable_content": true,
      "_st": {
        "image_url": "https://www.mysite.com/img.png"      }
    }
  }
}'

Result Format

200 OK

Copy 
{
  "id" : "5acfa75174bff800012754f0",
  "results": {
    "success": 1,
    "uninstalled": 2,
    "failures": ["5acaa58fa96e5d1a6c3716a3"]
  }
}

Payload Field

Please refer to Notifications Payload Field section.

To Field

There are three possible fields that can be used as targets:

  • device_id (Unique identification of a device)
  • user_id
  • sid (Sailthru Profile ID)

Extra Filters

In addition to targeting your push to devices by device ID, User ID or Sailthru Profile ID you can specify an extra_filters array which limits the devices to those which match. These filters work much the same as the notifications API filters except in a more limited manner. A filter is an object composed of three attributes: name, criteria and not_filter.

Filter attribute Details
name String. Device attribute on which the criteria will be applied.Example: { "name": "user_email", criteria: ["example@sailthru.com"] } will match devices with a user email set to the supplied value. See the list of valid names/attributes below.
criteria Array with values to match.Provide at least one element of type string, integer, float or boolean.
not_filter Boolean. When true, it will match devices that don't match the criteria. Default is false.

Valid names/attributes for a filter

Name/Attribute Description
device_id Sailthru Mobile generated Device ID
sid Sailthru Profile ID
user_id The ID assigned to the user
user_email The email address of the user of a given device

Group

Pushes will be grouped by a group identifier. Group identifiers must have at least 3 characters and at most 64 characters. Group identifiers can't include special characters other than hyphens (-) Examples:

  • promotion-2018-March
  • delivery
  • SALES

Payload

The notification payload accepts:

  • alert, title and subtitle to compose the message text
  • badge which must be a non negative number
  • collapse_key which causes push notifications to merge if another push has the same key. Its length must not be greater than 64 characters.
  • mutable_content, content_available, category, interruption_level, relevance_score special keys
  • Any other custom key will be sent untouched as part of the payload
Copy 
{
  "to": { "field": "user_id", "value": "john_doe" },
  "group" : "coupon_codes",
  "payload": {
    "alert" : "Here is your coupon code: 12AF6CZ !",
    "title" : "Coupon for you",
    "subtitle" : "Grab your code here",
    "collapse_key" : "coupon-message",
    "coupon_code" : "12AF6CZ"    "badge" : 100
  }
}
RESPONSE
Copy 
{
  "id" : "5acfa75174bff800012754f0",
  "results": {
    "success": 1,
    "uninstalled": 2,
    "failures": ["5acaa58fa96e5d1a6c3716a3"]
   }
}

Results will include:

  • Number of successful devices that the gateway considered successfully sent;
  • Number of devices that got detected by the gateway as uninstalled;
Device IDs that failed to receive the push. The user must retry using to as: 
{ "field": "device_id", "value": "5acaa58fa96e5d1a6c3716a3" }
For each device_id returned on failures. The results are the gateway perspective (APNs & Firebase) about the push.

Restrictions

Liquid is not yet supported for this endpoint. The follow keys should not be used:

  • from
  • google
  • gcm

Stats

You can use our transactional notification stats endpoint to retrieve aggregated performance statistics for your notification groups.