{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/messages","auth":"required","examples":{"codes":[{"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\n# Basic text message with unpublish_at date\ncurl -X POST -u :$API_KEY -d '{\"message\":{\"to\":\"*\", \"title\":\"test\",\"text\":\"test message\", \"unpublish_at\": \"2019-09-01T00:00:00Z\"}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages\n","name":"","language":"curl"}]},"method":"post","params":[{"name":"message","type":"object","default":"","desc":"JSON model of message","required":false,"in":"body","ref":"","_id":"5673830958c4890d00bb54cf"}],"results":{"codes":[{"status":201,"language":"json","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}","name":""},{"status":401,"language":"json","code":"// This error is given when your API client credentials are not correct. \n{\n  \"error\":\"unauthorized\"\n}","name":""},{"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}","status":403,"language":"json"},{"status":422,"language":"json","code":"{\nerror: # Dependant on why the request body was incorrect. \n}\n"}]},"settings":"","apiSetting":null},"next":{"description":"","pages":[]},"title":"Messages","type":"endpoint","slug":"messages","excerpt":"Send push notifications and in-app notifications to segments of your users.","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. **\n\n## unpublish_at field\n\nOptional field.\n\nWhen passed, the message will be unpublished from the device's message stream once the specified time has passed.\n\nThe unpublish_at field's date must be specified using a UTC time with the following format: 'YYYY-MM-DDTHH:mm:SSZ'. Example: \"2019-09-01T00:00:00Z\".","updates":[],"order":3,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5e6156bf5e4a51006dcd814e","__v":55,"editedParams":true,"editedParams2":true,"project":"55e67aaa9cc7c62b00c4a1ea","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"},"createdAt":"2015-09-22T03:10:42.533Z","githubsync":"","parentDoc":null,"user":"55d2bd8e2463351700f67dd7","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"}}