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

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

Parameters

Examples

# 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

{
   "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": {} 
   }

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

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

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

Valid names/attributes for a filter

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.

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