{"_id":"5b720760c44b7600034b79d7","__v":52,"editedParams":true,"editedParams2":true,"project":"55e67aaa9cc7c62b00c4a1ea","category":{"_id":"5b720760c44b7600034b79a9","__v":20,"pages":["5b720760c44b7600034b79c0","55ed079b0d968e2100de8339","5b720760c44b7600034b79c1","55ed0bb078319821005005cf","5b720760c44b7600034b79c2","5b720760c44b7600034b79c3","5b720760c44b7600034b79c4","5b720760c44b7600034b79c5","5b720760c44b7600034b79c6","5b720760c44b7600034b79c7","5b720760c44b7600034b79c8","5b720760c44b7600034b79c9","5b720760c44b7600034b79ca","5b720760c44b7600034b79cb","5b720760c44b7600034b79cc","5b720760c44b7600034b79cd","5b720760c44b7600034b79ce","5b720760c44b7600034b79d6","5b720760c44b7600034b79d7","5b720760c44b7600034b79df"],"project":"55e67aaa9cc7c62b00c4a1ea","version":"5b720760c44b7600034b7a08","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-09-02T04:30:21.948Z","from_sync":false,"order":5,"slug":"rest-api","title":"REST API"},"githubsync":"","parentDoc":null,"user":"55d2bd8e2463351700f67dd7","version":{"_id":"5b720760c44b7600034b7a08","project":"55e67aaa9cc7c62b00c4a1ea","__v":0,"forked_from":"5b1f2cbdfd653400031d8d9f","createdAt":"2015-09-02T04:27:23.612Z","releaseDate":"2015-09-02T04:27:23.612Z","categories":["5b720760c44b7600034b79a7","5b720760c44b7600034b79a8","5b720760c44b7600034b79a9","5b720760c44b7600034b79aa","5b720760c44b7600034b79ab","561c61b4ad272c0d00a892df","586c014c0abf1d0f000d04d4","58991d2ad207df0f0002186b","5b720760c44b7600034b79ac","5b720760c44b7600034b79ad","5af0fe494ca2730003cbc98a","5af0fe55ec80af0003804ca2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"API V6","version_clean":"1.4.0","version":"1.4"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-22T03:10:42.533Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","name":"","code":"# Basic text message\ncurl -X POST -u :$API_KEY -d '{\"message\":{\"to\":\"*\", \"title\":\"test\",\"text\":\"test message\"}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages\n\n# Basic text message with message attributes \ncurl -X POST -u :$API_KEY -d '{\"message\":{\"to\":\"*\", \"title\":\"test\",\"text\":\"test message\", \"custom\":{\"my_key\":\"my value\"}}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages\n\n# Link message\ncurl -X POST -u :$API_KEY -d '{\"message\":{\"to\":\"*\",\"title\":\"test\",\"url\":\"http://google.com\"}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages\n\n# Message with push notification attached\ncurl -X POST -u :$API_KEY -d '{\"message\":{\"to\":\"*\",\"title\":\"test\",\"text\":\"test message\",\"notification\":{\"payload\":{\"alert\":\"foo\",\"bar\":\"baz\"}}}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages\n"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n   \"created_at\": \"2019-01-08T01:47:01.527Z\",\n   \"state\": \"scheduled\",\n   \"id\": \"5c34011507492800095c97e5\",\n   \"to\": {\n       \"id\": \"5c1c35670798cd000973ce87\",\n       \"type\": \"Audience\"\n    },\n    \"notification\": {\n       \"id\": \"5c34011507492800095c97e6\",\n       \"created_at\": \"2019-01-08T01:47:01.535Z\",\n       \"payload\": {\n          \"alert\": \"foo\",\n          \"bar\": \"baz\"\n       }\n    },\n   \"title\": \"test\",\n   \"text\": \"test message\",\n   \"html\": \"<p>test message</p>\\n\",\n   \"custom\": {}\n}","language":"json","status":201},{"name":"","code":"// This error is given when your API client credentials are not correct. \n{\n  \"error\":\"unauthorized\"\n}","language":"json","status":401},{"language":"json","status":403,"code":"// This error is given when your API client does not have the ability to send Push Notifications.\n{\n  \"error\":\"your api client does not have the correct roles\"\n}"},{"code":"{\nerror: # Dependant on why the request body was incorrect. \n}\n","language":"json","status":422}]},"settings":"","apiSetting":null,"auth":"required","params":[{"_id":"5673830958c4890d00bb54cf","ref":"","in":"body","required":false,"desc":"JSON model of message","default":"","type":"object","name":"message"}],"url":"/messages"},"isReference":true,"order":3,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Retention policy\",\n  \"body\": \"Rich Messages created through the API have a retention policy of 3 months.  Messages in a user's stream will be deleted after this time.\"\n}\n[/block]\n## To Field \n\nThere are three options for sending \n * `\"*\"` will send to everyone\n * A key audience with the value set as the audience ID, retrieved via [Audiences](doc:audiences),  will send to the specified audience.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"to\\\":{\\\"audience\\\":\\\"AUDIENCE_KEY\\\"} ,\\\"title\\\":\\\"test\\\",\\\"type\\\":\\\"text_message\\\",\\\"text\\\":\\\"test message\\\"}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n * An array of filters for creating an \"on-the-fly\" audience will send to users who match the filters. See the [Filters](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-filters) section for available filters.\n\n## Filters\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\": \"Device attribute on which the criteria will be applied.\\n\\nExample: `{ \\\"name\\\": \\\"locale\\\", \\\"criteria\\\": [\\\"en-us\\\"] }` will match devices with en_US locale. See the list of valid [names/attributes](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-valid-names-attributes-for-a-filter) below.\",\n    \"1-0\": \"**criteria**\",\n    \"1-1\": \"Values to match in filtering.\\n\\nA criteria should always be an array with at least one element of type string, integer, float, or a range object (see below [how to define a range object](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-specifying-criteria-ranges)).\",\n    \"2-0\": \"**not_filter**\",\n    \"2-1\": \"Boolean value (false by default). When true, it will match devices that *don't* match the criteria.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\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\": \"**locale**\",\n    \"1-0\": \"**time_zone**\",\n    \"2-0\": \"**created_at**\",\n    \"3-0\": \"**registered_at**\",\n    \"4-0\": \"**badge**\",\n    \"5-0\": \"**os_name**\",\n    \"6-0\": \"**os_version**\",\n    \"7-0\": \"**app_version**\",\n    \"8-0\": \"**sdk_version**\",\n    \"9-0\": \"**tags**\",\n    \"10-0\": \"**device_id**\",\n    \"11-0\": \"**country**\",\n    \"0-1\": \"Language used on the device. Possible values can be found [here](http://www.science.co.il/Language/Locale-codes.asp).\",\n    \"1-1\": \"Time zone used on the device. Possible values can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).\",\n    \"2-1\": \"The date of device registration\",\n    \"3-1\": \"The date of last device update\",\n    \"4-1\": \"The current badge count\",\n    \"5-1\": \"The device OS name\",\n    \"6-1\": \"The device OS version\",\n    \"7-1\": \"The app version on the device\",\n    \"8-1\": \"The Sailthru SDK version\",\n    \"9-1\": \"The tags on the device\",\n    \"10-1\": \"The device ID assigned by Sailthru\",\n    \"11-1\": \"The country based on user location (can be inaccurate, since sometimes the user doesn't enable GPS tracking and this value be defined using the user IP).\",\n    \"12-0\": \"**marketing_name**\",\n    \"12-1\": \"The device model.\\n\\nExamples: `iPhone 5`, `iPhone 6`, `Samsung Galaxy S5`\",\n    \"13-0\": \"**user_id**\",\n    \"13-1\": \"The user id on the device (Array of strings)\"\n  },\n  \"cols\": 2,\n  \"rows\": 14\n}\n[/block]\n\n### Filtering by custom attributes\n\nThe filter name should be composed as follows: \n\n`custom.` + `type of attribute (string, integer, float, date or boolean).` + `attribute_name`\n\nExamples:\n\n* `custom.string.favorite_color`\n* `custom.date.last_purchased`\n* `custom.boolean.completed_setup`\n\n### Filtering by custom events\n\nThe filter name should be composed as follows: \n\n`events.` + event name.\n\nExamples:\n\n* `events.shared_post_on_twitter`\n* `events.video_plays`\n\n#### Specifying criteria ranges\n\nA range is an object with at least of the following keys: `gt`, `lt`, `gte` and `lte`.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Range key\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**gt**\",\n    \"1-0\": \"**lt**\",\n    \"2-0\": \"**gte**\",\n    \"3-0\": \"**lte**\",\n    \"0-1\": \"Greater than value\",\n    \"1-1\": \"Less than value\",\n    \"2-1\": \"Greater than or equal to value\",\n    \"3-1\": \"Less than or equal to value\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nExamples of valid ranges:\n\n* `{ \"gt\": 0 }` - return values greater than 0\n* `{ \"gt\": 0, \"lt\": 10 }` - return values greater than zero and less than 10 (non-inclusive)\n* `{ \"gte\": 0 }` - return values greater than or equal to 0\n\n**Note: Make sure to use the same type of double quotation marks (e.g. both smart or both straight) when testing using the message box below. **","excerpt":"Send push notifications and in-app notifications to segments of your users.","slug":"messages","type":"endpoint","title":"Messages"}

postMessages

Send push notifications and in-app notifications to segments of your users.

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

message:
object
JSON model of message

Examples


Result Format


Documentation

[block:callout] { "type": "warning", "title": "Retention policy", "body": "Rich Messages created through the API have a retention policy of 3 months. Messages in a user's stream will be deleted after this time." } [/block] ## To Field There are three options for sending * `"*"` will send to everyone * A key audience with the value set as the audience ID, retrieved via [Audiences](doc:audiences), will send to the specified audience. [block:code] { "codes": [ { "code": "{\"to\":{\"audience\":\"AUDIENCE_KEY\"} ,\"title\":\"test\",\"type\":\"text_message\",\"text\":\"test message\"}", "language": "json" } ] } [/block] * An array of filters for creating an "on-the-fly" audience will send to users who match the filters. See the [Filters](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-filters) section for available filters. ## Filters 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": "Device attribute on which the criteria will be applied.\n\nExample: `{ \"name\": \"locale\", \"criteria\": [\"en-us\"] }` will match devices with en_US locale. See the list of valid [names/attributes](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-valid-names-attributes-for-a-filter) below.", "1-0": "**criteria**", "1-1": "Values to match in filtering.\n\nA criteria should always be an array with at least one element of type string, integer, float, or a range object (see below [how to define a range object](https://docs.mobile.sailthru.com/v1.4/docs/messages#section-specifying-criteria-ranges)).", "2-0": "**not_filter**", "2-1": "Boolean value (false by default). When true, it will match devices that *don't* match the criteria." }, "cols": 2, "rows": 3 } [/block] ### Valid names/attributes for a filter [block:parameters] { "data": { "h-0": "Name/Attribute", "h-1": "Description", "0-0": "**locale**", "1-0": "**time_zone**", "2-0": "**created_at**", "3-0": "**registered_at**", "4-0": "**badge**", "5-0": "**os_name**", "6-0": "**os_version**", "7-0": "**app_version**", "8-0": "**sdk_version**", "9-0": "**tags**", "10-0": "**device_id**", "11-0": "**country**", "0-1": "Language used on the device. Possible values can be found [here](http://www.science.co.il/Language/Locale-codes.asp).", "1-1": "Time zone used on the device. Possible values can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "2-1": "The date of device registration", "3-1": "The date of last device update", "4-1": "The current badge count", "5-1": "The device OS name", "6-1": "The device OS version", "7-1": "The app version on the device", "8-1": "The Sailthru SDK version", "9-1": "The tags on the device", "10-1": "The device ID assigned by Sailthru", "11-1": "The country based on user location (can be inaccurate, since sometimes the user doesn't enable GPS tracking and this value be defined using the user IP).", "12-0": "**marketing_name**", "12-1": "The device model.\n\nExamples: `iPhone 5`, `iPhone 6`, `Samsung Galaxy S5`", "13-0": "**user_id**", "13-1": "The user id on the device (Array of strings)" }, "cols": 2, "rows": 14 } [/block] ### Filtering by custom attributes The filter name should be composed as follows: `custom.` + `type of attribute (string, integer, float, date or boolean).` + `attribute_name` Examples: * `custom.string.favorite_color` * `custom.date.last_purchased` * `custom.boolean.completed_setup` ### Filtering by custom events The filter name should be composed as follows: `events.` + event name. Examples: * `events.shared_post_on_twitter` * `events.video_plays` #### Specifying criteria ranges A range is an object with at least of the following keys: `gt`, `lt`, `gte` and `lte`. [block:parameters] { "data": { "h-0": "Range key", "h-1": "Description", "0-0": "**gt**", "1-0": "**lt**", "2-0": "**gte**", "3-0": "**lte**", "0-1": "Greater than value", "1-1": "Less than value", "2-1": "Greater than or equal to value", "3-1": "Less than or equal to value" }, "cols": 2, "rows": 4 } [/block] Examples of valid ranges: * `{ "gt": 0 }` - return values greater than 0 * `{ "gt": 0, "lt": 10 }` - return values greater than zero and less than 10 (non-inclusive) * `{ "gte": 0 }` - return values greater than or equal to 0 **Note: Make sure to use the same type of double quotation marks (e.g. both smart or both straight) when testing using the message box below. **

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 }}