Push Subscription Management

In Teak a player’s push subscription status is not connected to their per device opt-in/out state. That is, if a player denies push notifications from the platform specific push notification permission prompt, their subscription status reported by this API will still be opt_in. This API applies across all of a player’s mobile devices, and the subscription status may be changed even if the player has no mobile devices.

The subscription status set by this API applies to both locally scheduled notifications and dashboard managed schedules.

Reading

Endpoint

https://api.gocarrot.com/v2/push/subscription_status

Request Type

GET

Rate Limiting

300 requests per second

Description: The GET v2/push/subscription_status endpoint retrieves the current push subscription status for a game assigned player id.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are retrieving push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'state', 'reachable', and 'categories' keys.

status

'ok'

channel

'push'

user_id

The game assigned player id of the player opt out status was retrieved for.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving push notifications through set preferences.
'opt_in' indicates that the player has not opted out of receiving push notifications.

reachable

true if the player has any registered mobile devices, otherwise false.

categories

A map of Opt Out Category identifiers to one of 'opt_out or 'opt_in'.
'opt_out' indidicates that the player has opted out of receiving push notifications for that category through set preferences.
'opt_in' indicates that the player has not opted out of receiving push notifications for that category.

Example

 
{"status":"ok", "channel":"push", "user_id":"example_user", "state":"opt_in", "reachable": false, "categories": {"sales": "opt_in", "events": "opt_out"}}

Error Responses

Player Not Found

Status Code

404

Response Body

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

Example

 
{"status":"error","errors":{"user_id":["No player with id foo"]}}

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/push/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Updating

Endpoint

https://api.gocarrot.com/v2/push/subscription_status

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/push/subscription_status endpoint updates the push subscription status for a given player.

The state will apply to all of a player’s mobile devices. However please be aware that if the user has chosen to opt out of push notifications in their device settings or by denying the push notifications from the platform specific push notification permission prompt, this API cannot be used to cause a player to receive push notifications on that device.

It is not necessary for the player to have any mobile devices to make this call.

Required Parameters

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are updating push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

state

One of 'opt_out' or 'opt_in'

opt_out

Mobile notifications should be sent to this player.

opt_in

Mobile notifications may be sent to this player.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'previous_state', 'state', 'reachable', and 'categories' keys.

status

'ok'

channel

'push'

user_id

The game assigned player id of the player opt out status was retrieved for.

previous_state

The previously set mobile notification subscription state for this player.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving push notifications through set preferences.
'opt_in' indicates that the player has not opted out of receiving push notifications.

reachable

true if the player has any registered mobile devices, otherwise false.

categories

A map of Opt Out Category identifiers to one of 'opt_out or 'opt_in'.
'opt_out' indidicates that the player has opted out of receiving push notifications for that category through set preferences.
'opt_in' indicates that the player has not opted out of receiving push notifications for that category.

Example

 
{"status":"ok", "channel":"push", "user_id":"example_user", "previous_state": "opt_out", state":"opt_in", "reachable": false, "categories": {"sales": "opt_in", "events": "opt_out"}}

Error Responses

Unknown State

Status Code

404

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":{"state":["Unknown state opted_in"]}}

Player Not Found

Status Code

404

Response Body

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

Example

 
{"status":"error","errors":{"user_id":["No player with id foo"]}}

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/push/subscription_status may only be called 300 times per second. Please wait a second and try again"]}}

Category Update

Endpoint

https://api.gocarrot.com/v2/push/subscription_status/:category_identifier

Request Type

POST

Content-Type

application/json or application/x-www-form-urlencoded

Rate Limiting

300 requests per second

Description: The POST v2/push/subscription_status/:category_identifier endpoint updates the push subscription status for a given player and Opt Out Category.

The state will apply to all of a player’s mobile devices. However please be aware that if the user has chosen to opt out of push notifications in their device settings or by denying the push notifications from the platform specific push notification permission prompt, this API cannot be used to cause a player to receive push notifications on that device.

It is not necessary for the player to have any mobile devices to make this call.

Required Parameters

category_identifier

Note that this is a path parameter. The identifier of the opt out category the player’s push subscription status is being updated for.

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

user_id

The Game Assigned Player ID of the player you are updating push subscription status for. This must match the value provided by the game client’s Teak SDK integration.

state

One of 'opt_out' or 'opt_in'

opt_out

Mobile notifications should be sent to this player.

opt_in

Mobile notifications may be sent to this player.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'channel', 'user_id', 'previous_state', 'state', 'reachable', and 'category' keys.

status

'ok'

channel

'push'

user_id

The game assigned player id of the player opt out status was retrieved for.

previous_state

The previously set mobile notification subscription state for this player and Opt Out Category.

state

One of 'opt_out' or 'opt_in'.
'opt_out' indicates that the player has opted out of receiving push notifications through set preferences for this Opt Out Category.
'opt_in' indicates that the player has not opted out of receiving push notifications for this Opt Out Category.

reachable

true if the player has any registered mobile devices, otherwise false.

category

The identifier of the Opt Out Category that the push subscription status was updated for.

Example

 
{"status":"ok", "channel":"push", "user_id":"example_user", "previous_state": "opt_out", state":"opt_in", "reachable": false, "category": "sales"}

Error Responses

Unknown State

Status Code

404

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":{"state":["Unknown state opted_in"]}}

Player Not Found

Status Code

404

Response Body

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

Example

 
{"status":"error","errors":{"user_id":["No player with id foo"]}}

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/push/subscription_status/:category_identifier may only be called 300 times per second. Please wait a second and try again"]}}