{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/transactional/notifications","auth":"required","results":{"codes":[{"status":200,"language":"json","code":"{\n  \"id\" : \"5acfa75174bff800012754f0\",\n  \"results\": {\n    \"success\": 1,\n    \"uninstalled\": 2,\n    \"failures\": [\"5acaa58fa96e5d1a6c3716a3\"]\n  }\n}","name":""}]},"settings":"","params":[{"name":"to","type":"object","default":"","desc":"","required":true,"in":"body","ref":"","_id":"5bc803d345671b001d145f42"},{"name":"group","type":"string","default":"","desc":"","required":true,"in":"body","ref":"","_id":"5bc803d345671b001d145f41"},{"name":"notification","type":"object","default":"","desc":"","required":true,"in":"body","ref":"","_id":"5bc803d345671b001d145f40"},{"name":"extra_filters","type":"array_object","default":"","desc":"","required":false,"in":"body","ref":"","_id":"5cedc4e0c1fc98001b4cd699"}],"examples":{"codes":[{"language":"curl","code":"curl -X POST -u :$API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v6/transactional/notifications -d '{\n  \"to\": { \"field\": \"user_id\", \"value\": \"john_doe\" },\n  \"extra_filters\": [\n    {\n      \"name\": \"user_email\",\n      \"criteria\": [\"jdoe:::at:::example.com\", \"[email protected]\"]\n    }\n  ],\n  \"group\" : \"coupon-codes\",\n  \"notification\" : {\n    \"payload\": {\n      \"alert\" : \"Here is your coupon code: 12AF6CZ 🤑!\",\n      \"badge\" : 1\n    }\n  }\n}'"},{"code":"curl -X POST -u :$API_KEY -H \"Content-type: application/json\" -H 'Accept: application/json' https://api.carnivalmobile.com/v6/transactional/notifications -d '{\n  \"to\": { \"field\": \"user_id\", \"value\": \"john_doe\" },\n  \"group\" : \"coupon-codes\",\n  \"notification\" : {\n    \"payload\": {\n      \"alert\": \"Check out this rich push!\",\n      \"badge\": 1,\n      \"sound\": \"Default.caf\",\n      \"category\": \"TEST_CATEGORY\",\n      \"mutable_content\": true,\n      \"_st\": {\n        \"image_url\": \"https://www.mysite.com/img.png\"\n      }\n    }\n  }\n}'","language":"curl","name":"Rich Push"}]},"method":"post"},"next":{"description":"","pages":[]},"title":"Transactional Notifications","type":"endpoint","slug":"transactional-notifications","excerpt":"","body":"## Payload Field\n\nPlease refer to [Notifications Payload Field](https://docs.mobile.sailthru.com/docs/notifications#section-payload-field) section.\n\n## To Field\n\nThere are three possible fields that can be used as targets:\n\n- `device_id` (Unique identification of a device)\n- `user_id`\n- `sid` (Sailthru Profile ID)\n\n## Extra Filters\n\nIn addition to targetting 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](https://docs.mobile.sailthru.com/docs/notifications#section-filters) except in a more limited manner.\n\nA filter is an object composed of three attributes: `name`, `criteria` and `not_filter`.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Filter attribute\",\n    \"h-1\": \"Details\",\n    \"0-0\": \"`name`\",\n    \"0-1\": \"String. Device attribute on which the criteria will be applied.\\n\\nExample: `{ \\\"name\\\": \\\"user_email\\\", criteria: [\\\"[email protected]\\\"] }` will match devices with a user email set to the supplied value. See the list of valid names/attributes below.\",\n    \"1-0\": \"`criteria`\",\n    \"2-0\": \"`not_filter`\",\n    \"1-1\": \"Array with values to match.\\n\\nProvide at least one element of type string, integer, float or boolean.\",\n    \"2-1\": \"Boolean. When `true`, it will match devices that don't match the criteria. Default is `false`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n#### Valid names/attributes for a filter\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Name/Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`device_id`\",\n    \"0-1\": \"Sailthru Mobile generated Device ID\",\n    \"1-0\": \"`sid`\",\n    \"1-1\": \"Sailthru Profile ID\",\n    \"2-0\": \"`user_id`\",\n    \"2-1\": \"The ID assigned to the user\",\n    \"3-0\": \"`user_email`\",\n    \"3-1\": \"The email address of the user of a given device\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Group\n\nPushes 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 (`-`)\n\nExamples:\n\n- `promotion-2018-March`\n- `delivery`\n- `SALES`\n\n## Payload\n\nThe notification payload accepts:\n\n- `alert`, `title` and `subtitle` to compose the message text\n- `badge` which must be a non negative number\n- `collapse_key` which causes push notifications to merge if another push has the same key. Its length must not be greater than 64 characters.\n- `mutable_content`, `content_available`, `category` special keys\n- Any other custom key will be sent untouched as part of the payload\n\n\n    {\n      \"to\": { \"field\": \"user_id\", \"value\": \"john_doe\" },\n      \"group\" : \"coupon_codes\",\n      \"payload\": {\n        \"alert\" : \"Here is your coupon code: 12AF6CZ 🤑!\",\n        \"title\" : \"Coupon for you\",\n        \"subtitle\" : \"Grab your code here\",\n        \"collapse_key\" : \"coupon-message\",\n        \"coupon_code\" : \"12AF6CZ\"\n        \"badge\" : 100\n      }\n    }\n\n## Response\n\n    {\n      \"id\" : \"5acfa75174bff800012754f0\",\n      \"results\": {\n        \"success\": 1,\n        \"uninstalled\": 2,\n        \"failures\": [\"5acaa58fa96e5d1a6c3716a3\"]\n       }\n    }\n\nResults will include:\n\n- Number of successful devices that the gateway considered successfully sent;\n- Number of devices that got detected by the gateway as uninstalled;\n- Device IDs that failed to receive the push. The user must retry using `to` as:\n\n```\n{ \"field\": \"device_id\", \"value\": \"5acaa58fa96e5d1a6c3716a3\" }\n```\n\nFor each `device_id` returned on `failures`.\n\nThe results are the gateway perspective (APNs & Firebase) about the push.\n\n## Restrictions\nLiquid is not yet supported for this endpoint.\n\nThe follow keys should **not** be used:\n\n- `from`\n- `google`\n- `gcm`\n\n## Stats\n\nYou can use our [transactional notification stats endpoint](https://docs.mobile.sailthru.com/docs/stats-transactional-notifications) to retrieve aggregated performance statistics for your notification groups.","updates":[],"order":2,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5e6156bf5e4a51006dcd817d","project":"55e67aaa9cc7c62b00c4a1ea","version":{"version":"1.5","version_clean":"1.5.0","codename":"ST Rebrand","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5e6156bf5e4a51006dcd8120","5e6156bf5e4a51006dcd8121","5e6156bf5e4a51006dcd8122","5e6156bf5e4a51006dcd8123","5e6156bf5e4a51006dcd8124","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5e6156bf5e4a51006dcd8125","5e6156bf5e4a51006dcd8126","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2","5e69868cbd5dcb006b35867b","5e6986ca2c6652006791b6e8"],"_id":"5e6156bf5e4a51006dcd818c","project":"55e67aaa9cc7c62b00c4a1ea","__v":2,"forked_from":"5b720760c44b7600034b7a08","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z"},"category":{"sync":{"isSync":false,"url":""},"pages":["5e6156bf5e4a51006dcd8138","55ed079b0d968e2100de8339","5e6156bf5e4a51006dcd8139","55ed0bb078319821005005cf","5e6156bf5e4a51006dcd813a","5e6156bf5e4a51006dcd813b","5e6156bf5e4a51006dcd813c","5e6156bf5e4a51006dcd813d","5e6156bf5e4a51006dcd813e","5e6156bf5e4a51006dcd813f","5e6156bf5e4a51006dcd8140","5e6156bf5e4a51006dcd8141","5e6156bf5e4a51006dcd8142","5e6156bf5e4a51006dcd8143","5e6156bf5e4a51006dcd8144","5e6156bf5e4a51006dcd8145","5b720760c44b7600034b79ce","5e6156bf5e4a51006dcd814d","5e6156bf5e4a51006dcd814e","5e6156bf5e4a51006dcd8156"],"title":"REST API","slug":"rest-api","order":5,"from_sync":false,"reference":true,"_id":"5e6156bf5e4a51006dcd8122","__v":20,"createdAt":"2015-09-02T04:30:21.948Z","project":"55e67aaa9cc7c62b00c4a1ea","version":"5e6156bf5e4a51006dcd818c"},"user":"58c7437515c5a22500e19012","createdAt":"2018-10-17T03:48:08.702Z","__v":24,"parentDoc":null}

postTransactional Notifications


Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

to:
required
object
group:
required
string
notification:
required
object
extra_filters:
array of objects

Examples


Result Format


Documentation

## Payload Field Please refer to [Notifications Payload Field](https://docs.mobile.sailthru.com/docs/notifications#section-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 targetting 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](https://docs.mobile.sailthru.com/docs/notifications#section-filters) except in a more limited manner. A filter is an object composed of three attributes: `name`, `criteria` and `not_filter`. [block:parameters] { "data": { "h-0": "Filter attribute", "h-1": "Details", "0-0": "`name`", "0-1": "String. Device attribute on which the criteria will be applied.\n\nExample: `{ \"name\": \"user_email\", criteria: [\"[email protected]\"] }` will match devices with a user email set to the supplied value. See the list of valid names/attributes below.", "1-0": "`criteria`", "2-0": "`not_filter`", "1-1": "Array with values to match.\n\nProvide at least one element of type string, integer, float or boolean.", "2-1": "Boolean. When `true`, it will match devices that don't match the criteria. Default is `false`." }, "cols": 2, "rows": 3 } [/block] #### Valid names/attributes for a filter [block:parameters] { "data": { "h-0": "Name/Attribute", "h-1": "Description", "0-0": "`device_id`", "0-1": "Sailthru Mobile generated Device ID", "1-0": "`sid`", "1-1": "Sailthru Profile ID", "2-0": "`user_id`", "2-1": "The ID assigned to the user", "3-0": "`user_email`", "3-1": "The email address of the user of a given device" }, "cols": 2, "rows": 4 } [/block] ## 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` special keys - Any other custom key will be sent untouched as part of the payload { "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 { "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](https://docs.mobile.sailthru.com/docs/stats-transactional-notifications) to retrieve aggregated performance statistics for your notification groups.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}