Direct Notification Scheduling

Scheduling

Endpoint

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

Request Type

POST

Content-Type

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

Rate Limiting

30 requests per second

Description: The v2/schedule endpoint allows for bulk scheduling of notifications to be delivered within 30 days. Before using this API you must configure a corresponding Local Schedule on the Teak Dashboard. Doing so gives you the full benefit of Teak’s analytics, A/B testing, and Content Management System when using local notifications.

The Name you give the Schedule is notification_identifier you should use in calls to this API. Your marketing team may already have set up some Local Schedules; be sure to ask them if they have and what names they’ve given the Local Schedules.

This endpoint is appropriate for use when users whom the notification should be sent to change frequently or when notifications need to be sent to different users at different times.

Required Parameters

Name Description

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

notification_identifier

The Name of the Schedule in the dashboard.

user_ids

Array of Game Assigned Player IDs to send the notification to. Maximum of 100 per call. If you need to schedule the notification for more users, make additional calls.

Optional Parameters

Name Description

send_time

The time in UTC at which to deliver the notification. Must be in ISO8601 format, e.g. "2018-08-23 17:00:00". Must be within 30 days from the time the call is made. If omitted, or if set to a past time, notifications will be scheduled to deliver immediately.

personalization_data

A map of Game Assigned Player IDs to a map of string key/value pairs. The key/value pairs will be available to be templated into the sent notification. See Local Notification Tags for more information.

device_ids

A map of Game Assigned Player IDs to Teak Device IDs. When provided, the notification will be targeted to the specified device for each player instead of using the prioritization set on the Schedule in the dashboard. Players included in user_ids but not in device_ids will use the dashboard prioritization. If a device ID cannot be resolved (e.g. the device does not exist or does not belong to the specified player), that player will be skipped and the error reported in the response.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status', 'ids', and 'scheduled' keys. 'status' will be 'ok'. 'ids' will contain an array of strings which are opaque ids for the deliveries scheduled. Every delivery will have a unique id. 'scheduled' will be a map of Game Assigned Player ID to the opaque delivery id for that player. If `device_ids` was provided and any device IDs could not be resolved, an 'errors' key will be present containing a 'device_ids' map of the Game Assigned Player ID to a human readable error message. Players with unresolvable device IDs will not have deliveries scheduled.
Example
{"status":"ok", "ids":["12904919075210912"], "scheduled":{"player_1":"12904919075210912"}}

Partial Device ID Failure

When device_ids is provided and some device IDs cannot be resolved, the response will still return a 200 status. Successfully targeted players will be scheduled normally. Unresolvable players will be skipped and reported in the errors.device_ids map.

{
  "status": "ok",
  "ids": ["12904919075210912"],
  "scheduled": {
    "player_1": "12904919075210912"
  },
  "errors": {
    "device_ids": {
      "player_2": "could not resolve device 'bad-device-id'"
    }
  }
}

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

Validation Error

Status Code

422

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 failed to meet requirements, and the values will be an array of human readable messages for failed validations.
Example
{"status":"error","errors":{"notification_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/schedule may only be called 30 times per second. Please wait a second and try again"]}}

Cancelling/Unscheduling

Endpoint

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

Request Type

POST

Content-Type

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

Rate Limiting

30 requests per second

Description: The v2/unschedule endpoint allows for bulk cancelling or unscheduling of notifications scheduled for delivery using the v2/schedule API.

The Name you give the Schedule is notification_identifier you should use in calls to this API. Your marketing team may already have set up some Local Schedules; be sure to ask them if they have and what names they’ve given the Local Schedules.

Required Parameters

Name Description

game_id

Your Teak App ID

secret_key

Your Teak Server Secret

Identifying Notifications to Cancel

You must provide either the ids parameter or the user_ids and notification_identifier parameters. If you provide the ids parameter you can cancel scheduled sends for multiple Local Schedules in a single call. Additionally the ids parameter can be used to cancel up to 1,000 sends at a time, while the user_ids and notification_identifier parameter combination is limited to 100 sends at a time.

Name Description

notification_identifier

The Name of the Schedule in the dashboard.

user_ids

Array of Game Assigned Player IDs to cancel the notification for. Maximum of 100 per call. If you need to cancel the notification for more users, make additional calls.

ids

Array of ids returned from previous calls to v2/schedule. Maximum of 1,000 per call.

Success Response

Status Code

200

Response Body

JSON dictionary with 'status' and 'ids' keys. 'status' will be 'ok'. 'ids' will contain an array of strings which are opaque ids for the deliveries cancelled. Every delivery will have a unique id.
Example
{"status":"ok", "ids":["12904919075210912"]}

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

Validation Error

Status Code

422

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 failed to meet requirements, and the values will be an array of human readable messages for failed validations.
Example
{"status":"error","errors":{"notification_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/unschedule may only be called 30 times per second. Please wait a second and try again"]}}