POST Messages

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

URL Endpoint: https://api.carnivalmobile.com/v6/messages

Parameters

Name	Type	Required	Definition
message	object	No	JSON model of message

Examples

Copy

# Basic text message
curl -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

# Basic text message with message attributes 
curl -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

# Link message
curl -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

# Message with push notification attached
curl -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

# Message with push notification containing interruption level attached
curl -X POST -u :$API_KEY -d '{"message":{"to":"*","title":"test","text":"test message","notification":{"payload":{"alert":"foo","bar":"baz","interruption_level":"time-sensitive"}}}}' -H 'Content-Type:application/json' -H 'Accept: application/json' https://api.carnivalmobile.com/v6/messages

# Basic text message with unpublish_at date
curl -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

Result Format

201 Created

Copy

{
   "created_at": "2019-01-08T01:47:01.527Z",
   "state": "scheduled",
   "id": "5c34011507492800095c97e5",
   "to": {
       "id": "5c1c35670798cd000973ce87",
       "type": "Audience"    },
    "notification": {
       "id": "5c34011507492800095c97e6",
       "created_at": "2019-01-08T01:47:01.535Z",
       "payload": {
          "alert": "foo",
          "bar": "baz"       }
    },
   "title": "test",
   "text": "test message",
   "html": <p>"test message\n",</p>   "custom": {} 
   }

401 Unauthorized

Copy

// This error is given when your API client credentials are not correct. 
{
  "error":"unauthorized"}

403 Forbidden

Copy

// This error is given when your API client does not have the ability to send Push Notifications.
{
  "error":"your api client does not have the correct roles"}

422 Unprocessable Entity

Copy

{
error: # Dependant on why the request body was incorrect. 
}

Note: 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.

Notification Payload Field

Please refer to Notifications Payload Field section.

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, will send to the specified audience.
```
{"to":{"audience":"AUDIENCE_KEY"} ,"title":"test","type":"text_message","text":"test message"}
```
An array of filters for creating an "on-the-fly" audience will send to users who match the filters. See the Filters section for available filters.

Filters

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
locale	Language used on the device. Possible values can be found here.
time_zone	Time zone used on the device. Possible values can be found here.
created_at	The date of device registration
registered_at	The date of last device update
badge	The current badge count
os_name	The device OS name
os_version	The device OS version
app_version	The app version on the device
sdk_version	The Sailthru SDK version
tags	The tags on the device
device_id	The device ID assigned by Sailthru
country	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).
marketing_name	The device model. Examples: `iPhone 5`, `iPhone 6`, `Samsung Galaxy S5`
user_id	The user id on the device (Array of strings)

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

Filter 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.

Range key	Description
gt	Greater than value
lt	Less than value
gte	Greater than or equal to value
lte	Less than or equal to value

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.

unpublish_at Field

Optional field. When passed, the message will be unpublished from the device's message stream once the specified time has passed. The 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".