Messages

Listing

Endpoint

https://api.gocarrot.com/v2/messages

Request Type

GET

Content-Type

application/json

Rate Limiting

5 requests per second

Description: The v2/messages endpoint allows for querying all notification groups for a given game.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

Optional Parameters

limit

The number of notification groups to return. Will be clamped to [1, 1000]. Defaults to 1,000

after

A pagination token from a previous call to v2/messages

Success Response

Status Code

200

Response Body

JSON dictionary with status and messages keys, and potentially a paging key.

status

'ok'

messages

An array of Message dictionaries.

paging

JSON dictionary with cursors and next keys.
cursors will be a dictionary containing an after key, whose value can be passed as the after parameter to v2/messages to retrieve the next page.
next will be the full path and non-authorization query parameters to retrieve the next page.

Example

{
  "status":"ok",
  "messages": [
    ...
  ]
}

Error Responses

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["v2/messages may only be called 5 times per second. Please wait a second and try again"]}}

Creating

Endpoint

https://api.gocarrot.com/v2/messages

Request Type

POST

Content-Type

application/json

Rate Limiting

5 requests per second

Description: The v2/messages endpoint allows for creating a notification group for a given game.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

identifier

A unique identifier for the Message you are creating.

opt_out_category

The unique identifier of the opt-out category the Message will belong to.

channels

A dictionary whose keys are Channel strings, and whose values are ChannelGroup dictionaries.

Optional Parameters

Not applicable.

Success Response

Status Code

200

Response Body

JSON dictionary …

status

'ok'

message

A Message dictionary.

Example

{
  "status":"ok",
  "message": {
    ...
  }
}

Error Responses

Not Found

Status Code

404

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary in which the keys are the parameter which could not be found, and the values will be an array of human readable messages indicating what could not be found.

Example

{"status":"error","errors":{"game_id":["Unknown app id 42"]}}

Invalid Parameter

Status Code

422

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'error'. 'errors' will be a dictionary containing keys indicating which parameters were invalid, with values being an array of human readable error messages.

Example

{"status":"error","errors":{"identifier":["must be present"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["v2/messages may only be called 5 times per second. Please wait a second and try again"]}}

Updating

Endpoint

https://api.gocarrot.com/v2/messages/:identifier

Request Type

PUT

Content-Type

application/json

Rate Limiting

5 requests per second

Description: The v2/messages endpoint allows for updating the Message with the identifier identifier in the request path.

Note: For the time being, only a Message in which no ChannelGroup contains more than one MessageInstance.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

identifier

A unique identifier for the Message you are creating.

opt_out_category

The unique identifier of the opt-out category the Message will belong to.

channels

A dictionary whose keys are Channel strings, and whose values are ChannelGroup dictionaries.

Optional Parameters

Not applicable.

Success Response

Status Code

200

Response Body

JSON dictionary …

status

'ok'

message

A Message dictionary.

Example

{
  "status":"ok",
  "message": {
    ...
  }
}

Error Responses

Not Found

Status Code

404

Response Body

Example

{"status":"error","errors":{"game_id":["Unknown app id 42"]}}

Invalid Parameter

Status Code

422

Response Body

Example

{"status":"error","errors":{"identifier":["must be present"]}}

Rate Limit Response

Status Code

429

Response Body

JSON dictionary with 'status' and 'errors' keys. 'status' will be 'rate_limit'. 'errors' will contain the key 'rate_limit'

Example

{"status":"rate_limit","errors":{"rate_limit":["v2/messages may only be called 5 times per second. Please wait a second and try again"]}}

Types

This section outlines the shape of the various types of entity you will encounter when using this API.

AndroidContentMode

AndroidContentMode controls the layout of content for Android notifications. It is an enum comprised of one of the following values:

default

Use the default layout behavior. See Default Android Layout

ios_style

Use the iOS Style layout. See See Android iOS Style Layout. If this mode is selected, android_stack_expanded_view must be false.

AndroidIconMode

AndroidIconMode controls what icon is selected for notifications on Android. It is an enum comprised of one of the following values:

builtin

Use the application icon.

custom

Use a custom icon.

none

Do not show an icon.

BadgeState

BadgeState controls how badges are displayed. It is an enum comprised of one of the following values:

default

Badging behavior will be inherited from the Opt-Out Category.

no

No Badge will be shown.

yes

Badge will be shown. After the player launches the game following a notification that sets the badge, all notifications in the player’s Notification Center will be cleared.

DurationUnit

DurationUnit controls how maximum_age is interpreted. It is an enum comprised of one of the following values:

minutes

maximum_age represents the number of minutes for which the reward is valid.

hours

maximum_age represents the number of hours for which the reward is valid.

days

maximum_age represents the number of days for which the reward is valid.

EmailContentMode

EmailContentMode controls how message is interpreted, when channel is email. It is an enum comprised of one of the following values:

custom

No email template will be used, the body of the email will be comprised of message, which may include HTML.

default

Teak’s default email template will be used. message will be placed above the large image.

LinkType

LinkType controls how links will behave. It is an enum comprised of one of the following values:

deeplink

A deep link into the game, using the SDK’s router.

default

Link to the game.

outofgame

A link that goes to something other than the game. E.G. A web page.

Message

Message is a container for message content across all App-to-Player channels. It is a dictionary containing the following keys:

identifier

string

The unique identifier of this Message.

opt_out_category

string

The unique identifier of the opt-out category to which this Message belongs.

channels

Map<Channel, ChannelGroup>

A dictionary whose keys are Channel strings, and whose values are ChannelGroup dictionaries.

created_at

string

The ISO8601 timestamp indicating when this Message was originally created.

updated_at

string

The ISO8601 timestamp indicating when this Message was last updated.

(Note: A '?' at the end of a type indicates that this field may be ommitted.)

MessageInstance

MessageInstance represents the configuration of a notification, for a given channel. If an A/B test is running, there may be multiple MessageInstance records for a single channel, representing the variations under test. It is a dictionary containing the following keys:

badge_state

BadgeState

Controls badge display behavior.

sets_badge

boolean

Deprecated. Superseded by badge_state.

link_type

LinkType

What kind of link this MessageInstance will use.

show_in_foreground

boolean

If true, the notification will be shown even if the game is running in the foreground.+ Note: Teak SDK version 3.1.1 or later required.

skip_game_open

boolean

Skip game open. Disables rewarding.

test_weight

integer

The relative weight of this MessageInstance in an A/B test. Only meaningful in an A/B test.

bundle_name

string?

The unique identifier of the reward bundle, if any, to give the player.

reward_expiration

RewardExpiration?

When the reward associated with the notification expires, if a reward bundle is associated with this MessageInstance.

translations

[Translation]

The notification content to use, based on player locale.

created_at

string

The ISO8601 timestamp indicating when this MessageInstance was originally created.

updated_at

string

The ISO8601 timestamp indicating when this MessageInstance was last updated.

(Note: A '?' at the end of a type indicates that this field may be ommitted.)

Channel

Channel represents the avenue by which the player receives a notification. It is an enum comprised of one of the following values:

android

The ChannelGroup represents notifications for Android.

email

The ChannelGroup represents notifications for email.

fb

The ChannelGroup represents notifications for Facebook.

ios

The ChannelGroup represents notifications for iOS / iPadOS.

web

The ChannelGroup represents notifications for Web Push.

ChannelGroup

ChannelGroup is a container for the set of MessageInstances associated with a particular channel, and controls any relevant A/B test. It is a dictionary containing the following keys:

identifier

string

The unique identifier of the Message to which this ChannelGroup belongs.

is_ab_test

boolean

Whether or not this ChannelGroup has an active A/B test. This will be true if there are multiple MessageInstances.

start_time

string?

The ISO8601 timestamp indicating when the A/B test began, if one is running.

instances

[MessageInstance]

An array of MessageInstance dictionaries. There will be exactly one record, unless there is an A/B test configured.

created_at

string

The ISO8601 timestamp indicating when this ChannelGroup was originally created.

updated_at

string

The ISO8601 timestamp indicating when this ChannelGroup was last updated.

(Note: A '?' at the end of a type indicates that this field may be ommitted.)

RewardExpiration

RewardExpiration controls how long a player has to collect a reward bundle from a notification before it expires. It is a dictionary containing the following keys:

maximum_age

integer

The amount of time after which the reward expires.

age_unit

DurationUnit

Controls how maximum_age is interpreted.

(Note: A '?' at the end of a type indicates that this field may be ommitted.)

SoundState

SoundState controls what sound is played for an iOS/iPadOS notification. It is an enum comprised of one of the following values:

system_default

The default sound will be played. This is chosen by the OS, or by the user.

parent

Use the sound from the default translation group. (This value is only allowed if the Translation is not part of the default translation group.)

silent

No sound will be played.

custom

Use the value from sound_filename.

category_default

Use the sound associated with the opt-out category of the Message.

Translation

Translation represents the content of a notification, for one or more locales. It is a dictionary containing the following keys:

loop_large_media

boolean

Whether or not to loop video content in the notification.

sound_filename

string

The filename of the sound in your application bundle that should be played when this translation is used for the notification. Only relevant to iOS/iPadOS, as opt-out category determines notification sound on Android.

sound_state

SoundState

Determines which sound will be played on iOS/iPadOS.

translation_group_name

string

The unique identifier of the translation group to which this Translation belongs.

title

string?

See anatomy of a push notification docs.

subtitle

string?

See anatomy of a push notification docs.

message

string?

See anatomy of a push notification docs.

locales

[string]?

A list of language tags for which this Translation will be used.

email_content_mode

EmailContentMode?

Whether or not to use Teak’s email template. (Only available when channel is email.)

android_content_mode

AndroidContentMode?

What notification layout to use on Android. (Only available when channel is android.)

android_icon_mode

AndroidIconMode?

What notification icon to use on Android. (Only available when channel is android.)

android_stack_expanded_view

boolean

Displays the android banner above the expanded view image when the notification is expanded. (Only available when channel is android. Must be false when android_content_mode is ios_style.)

created_at

string

The ISO8601 timestamp indicating when this Translation was originally created.

updated_at

string

The ISO8601 timestamp indicating when this Translation was last updated.

(Note: A '?' at the end of a type indicates that this field may be ommitted.)