Notification > Push > API Guide
Overview of v2.0 API
Add
- Respond with detailedresultMessage. If API call fails, return faulty fields or values.
- e.g. When retrieved with a wrong message ID, include the messageId field and value to resultMessage as follows:
{
"header" : {
"resultCode" : 40401,
"resultMessage" : "Client Error. Not found. messageId<3496615188236841>",
"isSuccessful" : false
}
}
- Added v2.0 Register ToKen API and Property Statistics API.
- v2.0 Get Message API can bring data by period (from, to) and message status (messaageStatus).
Follow the ISO 8601 format (YYYY-MM-DDThh:mm:ss.SSSTZD) for 'from, to'.
For (+) of '2018-04-11T18:39:04.000+09:00', enter '2018-04-11T18:39:04.000%2B09:00' after URL is encoded.
- createdDateTime andcompletedDateTime fields added to v2.0 Get Message API.
- v2.0 Get Message Delivery/Receipt Stats API added.
- v2.0 Invalid Token API can get by PageIndex, PageSize, period (from, to), and messageIDs.
Modify
- The URI of v1.3 Feedback API has changed from '/push/v1.3/appkey/{appkey}/feedback' to '/push/v2.0/appkeys/{appkey}/invalid-tokens'.
Delete
- Messages delivered by v2.0 Send Message API are not traced down in history, while those sent by console are recorded in history.
If integration with ‘Log&Crash Search’ is added as scheduled, message delivery can be recorded at a user’s ‘Log&Crash Search’.
- Channel has been deleted from v2.0 API. Channel served as a grouper of tokens: one token was restricted to be included to only one channel.
Channel is to be replaced with Tag as of June 2017. One token can have many tags.
- Register Token API, and Channel field deleted
- 'Channel' type from target.type of Send Message API deleted
- Channel API deleted
Endpoint
API Endpoint: https://api-push.cloud.toast.com
Collect Receipt/Check Messages Endpoint: https://collector-push.cloud.toast.com
Secret Key
- Can check at the console.
- Need to configure the Header as below to call API requiring a secret key.
Header
X-Secret-Key: [a-zA-Z0-9]{8}
Go to console and click Notification > Push, then click URL & AppKey at the top right to create.
Response
Response HTTP Status Code
200 OK.
Respond with 200 OK to all API requests.
Can find detailed response results at the Header of Response Body.
{
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
resultCode, resultMessage
isSuccessful |
resultCode |
resultMessage |
true |
0 |
SUCCESS |
false |
40001 |
Client Error. Parameter is invalid. |
false |
40002 |
Client Error. Parameter is invalid format. |
false |
40003 |
Client Error. Parameter is empty or null. |
false |
40004 |
Client Error. Duplicate certificate. |
false |
40005 |
Client Error. Expired certificate. |
false |
40006 |
Client Error. Already registered. |
false |
40007 |
Client Error. Maximum limit exceeded. |
false |
40008 |
Client Error. Already completed. |
false |
40101 |
Client Error. Access is not allowed. |
false |
40102 |
Client Error. Unavailable key. |
false |
40401 |
Client Error. Not found. |
false |
50001 ~ 50501 |
Internal Error. Please report this. 'http://cloud.toast.com/support/faq'. |
false |
400 |
Client Error. Error of Client occurred at a tag API. |
false |
500 |
Internal Error. Internal error occurred at a tag API. |
Tokens
Create
Method, URL
POST /push/v2.0/appkeys/{appkey}/tokens
Content-Type: application/json;charset=UTF-8
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
Request Body
{
"oldToken": "oldToken",
"token": "token",
"isNotificationAgreement": true,
"isAdAgreement": true,
"isNightAdAgreement": true,
"pushType": "GCM",
"timezoneId": "Asia/Seoul",
"uid": "uid",
"country": "KR",
"language": "ko",
"deviceId": "X3LOdJSQdNzCCvcbiSPZTGK1M9srPU5EumRD"
}
Field |
Usage |
Description |
token |
Required, String |
Token, the maximum length is 1,600 |
oldToken |
Optional, String |
Old token, the maximum length is 1,600 |
pushType |
Required, String |
'GCM', 'APNS', 'APNS_SANDBOX', 'TENCENT', 'APNS_VOIP', 'APNS_SANDBOXVOIP', and 'ADM' |
isNotificationAgreement |
Required, Boolean |
True or false |
isAdAgreement |
Required, Boolean |
True or false |
isNightAdAgreement |
Required, Boolean |
True or false |
timezoneId |
Required, String |
Area/Name. IANA time zone database. |
country |
Required, String |
ISO 3166-1 alpha-2, ISO 3166-1 alpha-3, 3 bytes |
language |
Required, String |
ISO 639-1, ISO 639-2, iOS (language code + script code), 8 bytes |
uid |
Required, String |
User ID, no emojis allowed, no more than 64 bytes |
deviceId |
Optional, String |
Device ID, 36 bytes |
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tokens -d '{"oldToken":"oldToken","token":"token","isNotificationAgreement":true,"isAdAgreement":true,"isNightAdAgreement":true,"pushType":"GCM","timezoneId":"Asia/Seoul","uid":"uid","country":"KR","language":"ko"}'
Description
- In case a token is to be registered when there is an old token already registered, information is updated to a new token.
- As such, when an old token is replaced by a new token, set the old token for oldToken and set/register a new one for Token; it is to be updated to a new token.
- "isNotificationAgreement” means to agree receiving push messages; "isAdAgreement"for ad push messages; and "isNightAdAgreement”for night-time ad push messages.
- For instance, when you agree to receive all push messages, set all three fields as true. Or, if you decide to receive push messages only, set the "isNotificationAgreement” field only as true.
- Consent to receiving messages abides by the Act on Promotion of Information and Communications Network set by the government of Korea (from article 50-1 to 50-8).
- Delays in response may occur due to many reasons, such as bad network connection. To minimize effect on operation of mobile applications, it is recommended to set timeout short and register a token every time the application is operated.
- A token may be re-issued on many accounts, such as security issues, updates or deletion of applications. It is, therefore, recommended to register updated token at every operation, in order to upgrade the receiving rates.
- Even when a token expires due to application deletion, it is not immediately applied to GCM or APNS servers. So push messages could be successfully delivered even after an app has been deleted.
Get
Get by Token/Push Type
Method, URL
GET /push/v2.0/appkeys/{appkey}/tokens/{token}?pushType={pushType}
Content-Type: application/json;charset=UTF-8
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
pushType |
Required, String |
'GCM', 'APNS', 'APNS_SANDBOX', 'TENCENT', 'APNS_VOIP', 'APNS_SANDBOXVOIP', and 'ADM' |
Response Body
{
"token" : {
"pushType" : "GCM",
"isNotificationAgreement": true,
"isAdAgreement": true,
"isNightAdAgreement": true,
"timezoneId" : "Asia/Seoul",
"country": "KR",
"language": "ko",
"uid" : "User ID",
"token" : "Token",
"updateDateTime": "2017-08-12T01:04:18.000+09:00",
"adAgreementDateTime": "2017-08-12T01:04:19.000+09:00",
"nightAdAgreementDateTime": "2017-08-12T01:04:19.000+09:00"
},
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
updateDateTime |
-, DateTime String |
Date/time of a token update |
adAgreementDateTime |
-, DateTime String |
Date/time agreeing to receive ad push messages |
nightAdAgreementDateTime |
-, DateTime String |
Date/time agreeing to receive night-time ad push messages |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tokens/token?pushType=GCM
Get by User ID
- This API requires a secret key and should be called from a server.
Method, URL
GET /push/v2.0/appkeys/{appkey}/tokens?uid={uid}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
uid |
Required, String |
User ID to get |
Response Body
{
"tokens": [{
"pushType" : "GCM",
"isNotificationAgreement": true,
"isAdAgreement": true,
"isNightAdAgreement": true,
"timezoneId" : "Asia/Seoul",
"country": "KR",
"language": "ko",
"uid" : "User ID",
"token" : "Token",
"updateDateTime": "2017-08-12T01:04:18.000+09:00",
"adAgreementDateTime": "2017-08-12T01:04:19.000+09:00",
"nightAdAgreementDateTime": "2017-08-12T01:04:19.000+09:00"
}],
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tokens?uid=uid
Get Invalid Tokens
GET /push/v2.0/appkeys/{appkey}/invalid-tokens?pageIndex={pageIndex}&pageSize={pageSize}&from={from}&to={to}&messageId={messageId}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
pageIndex |
Optional, Number |
Default is 0 |
pageSize |
Optional, Number |
Default is 25; Max 100 |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
messageId |
Optional, Number |
Message ID with invalid token |
Request Body
N/A
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
},
"invalidTokens" : [{
"messageId" : 0,
"uid" : "uid",
"token" : "invalid-token",
"pushType" : "GCM",
"createdDateTime" : "2017-02-08T19:39:04.000+09:00"
}
]
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/invalid-tokens
Get Token Property Statistics API
GET /push/v2.0/appkeys/{appkey}/statistics/token-properties?from={from}&to={to}&tokenProperties={tokenProperties}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
tokenProperties |
Optional, String Array |
'agreement', 'country', 'language', 'timezoneId' Delimited by ',', e.g. tokenProperties=country,language |
Request Body
N/A
Response Body
{
"tokenPropertiesStatistics" : [{
"dateTime" : "2016-07-11 17:50:00.00+9:00",
"countries" : {
"KR" : 100,
"JP" : 60,
"CN" : 100
},
"languages" : {
"ko" : 90,
"ja" : 60,
"zh" : 100
},
"timezoneIds": {
"Asia/Seoul": 260
},
"agreements": {
"ON": 260
}
}, {
"dateTime" : "2016-07-11 17:51:00.00+9:00",
"countries" : {
"KR" : 100,
"JP" : 60,
"CN" : 100
},
"languages" : {
"ko" : 90,
"ja" : 60,
"zh" : 100
},
"timezoneIds": {
"Asia/Seoul": 260
},
"agreements": {
"ON": 260
}
}
],
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
dateTime |
String |
Time of data collection |
agreements |
String |
'ON'(receive all), 'NIGHT_AD_OFF' (reject night-time ad messages), 'AD_OFF' (reject ad messages), 'OFF' (reject all) |
countries.XX |
String |
ISO 3166-1 alpha-2, ISO 3166-1 alpha-3, 3 bytes |
languages.XX |
String |
ISO 639-1, ISO 639-2, iOS(language code + script code), 8 bytes |
timezoneIds.XX |
String |
Area/Name. IANA time zone database |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/statistics/token-properties
Get Register Token Statistics
GET /push/v2.0/appkeys/{appkey}/statistics/token-registrations?from={from}&to={to}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
Request Body
N/A
Response Body
{
"tokenRegistrationStatistics" : [{
"dateTime" : "2016-07-11 17:50:00.00+9:00",
"registered" : 90,
"deleted" : 20
}, {
"dateTime" : "2016-07-11 17:51:00.00+9:00",
"registered" : 45,
"deleted" : 10
}
],
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
dateTime |
String |
Date and time of data collection |
registered |
Number |
Number of registered tokens |
deleted |
Number |
Number of deleted tokens |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/statistics/token-registrations
Messages
Delivery
POST /push/v2.0/appkeys/{appkey}/messages
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"target" : {
"type" : "UID",
"to": ["uid-1", "uid-2"]
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "AD",
"contact": "1588-1588",
"removeGuide": "menu > setting",
"timeToLiveMinute": 1,
"provisionedResourceId": "id"
}
Response Body
{
"message" : {
"messageId" : 0,
"messageIdString": "0"
},
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
target.type |
Required, String |
Type of receiving targets, such as 'ALL', 'UID', and 'TAG' |
target.to |
Optional, String Array |
target.type is the UID list of recipients (no more than 10,000) or tag condition |
target.pushTypes |
Optional, String Array |
'GCM', 'APNS', 'APNS_SANDBOX', 'TENCENT', 'APNS_VOIP', 'APNS_SANDBOXVOIP', and 'ADM' |
target.countries |
Optional, String Array |
ISO 3166-1 alpha-2, ISO 3166-1 alpha-3 (up to 3 bytes) |
content |
Required, Map |
Messages to deliver to recipient (up to 8,192 bytes) |
content.default |
Required, Map |
For details, refer to ‘common message type’ below |
content.default.title |
Optional, String |
|
content.default.body |
Optional, String |
|
messageType |
Required, String |
NOTIFICATION, AD |
contact |
Optional, String |
Required if the messageType is AD. Only numbers (0-9) and hyphens are available. |
removeGuide |
Optional, String |
Required if the messageType is AD. |
timeToLiveMinute |
Optional, Number |
The unit is minute, ranged from 1 to 60. Default is 10. |
provisionedResourceId |
Optional, String |
Refers to a provisioned resource ID. Contact: support@cloud.toast.com |
Description
- When the target.type is set with UID, up to 10,000 UIDs can be configured to ‘target.to’.
- When the target.type is set with TAG, the condition can be configured with a tag ID, three conditions and 1 parenthesis “(())”.
- e.g. When delivering messages to those tagged with a man in 30s and a woman, the “target.to” can be configured man_ID, AND, 30s-ID, OR woman_ID.
- Using the “target.pushTypes” field, messages can be delivered in specific push types only; or delivered in all push types, such as GCM, APNS, APNS_SANDBOX, and TENCENT, if not defined.
- If “target.countries” is "['KR', 'JP']", messages are sent to those with “KR” or “JP” token country codes.
The “content.default” field is a must, and for more details on the “content” field, refer to [Common Message Format] below.
- To send a message with “AD” for its “messageType”, you should include “contact” and “removeGuide”. Contact number is required at the “contact” field; and, how to undone subscription is required at “removeGuide”.
- With the timeToLiveMinute field, messages that are delayed in delivery beyond TTL is automatically deemed as a failure.
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/messages -d '{"target":{"type":"UID","to":["uid"]},"content":{"default":{"title":"title","body":"body","customKey1":"It is default"},"ko":{"title":"제목","body":"내용","customKey2":"한국어 입니다."}},"messageType":"AD","contact":"1588-1588","removeGuide":"매뉴 > 설정","timeToLiveMinute":1}'
Common Messages
When “content” has messages written as below, messages are created for each push type before delivered.
Reserved Word |
Platform |
Usage |
GCM |
APNS |
TENCENT |
ADM |
title |
Android, iOS Watch, Tencent, ADM |
Optional, String |
data.title |
aps.alert.title |
title |
data.title |
body |
Android, iOS, Tencent, ADM |
Optional, String |
data.body |
aps.alert.body |
content |
data.body |
title-loc-key |
iOS |
Optional, String |
- |
aps.alert.title-loc-key |
- |
- |
title-loc-args |
iOS |
Optional, Array of Strings |
- |
aps.alert.title-loc-args |
- |
- |
action-loc-key |
iOS |
Optional, String |
- |
aps.alert.action-loc-key |
- |
- |
loc-key |
iOS |
Optional, String |
- |
aps.alert.loc-key |
- |
- |
loc-args |
iOS |
Optional, Array of String |
- |
aps.alert.loc-args |
- |
- |
launch-image |
iOS |
Optional, String |
- |
aps.alert.launch-image |
- |
- |
badge |
iOS |
Optional, Number |
- |
aps.badge |
- |
- |
sound |
Android, iOS, Tencent, ADM |
Optional, String |
data.sound |
aps.sound |
custom_content.sound |
data.sound |
content-available |
iOS |
Optional, String |
- |
aps.content-available |
- |
- |
category |
iOS |
Optional, String |
- |
aps.category |
- |
- |
mutable-content |
iOS |
Optional, String |
- |
aps.mutable-content |
- |
- |
consolidationKey |
ADM |
Optional, String |
- |
- |
- |
consolidationKey |
expiresAfter |
ADM |
Optional, Number |
- |
- |
- |
expiresAfter |
messageDeliveryReceipt |
Android, iOS, Tencent |
Unnecessary |
- |
- |
- |
- |
messageDeliveryReceiptData |
Android, iOS, Tencent |
Unnecessary |
- |
- |
- |
- |
Reserved Word, when a message is created, is set at appropriate locations for each platform. User cannot change data type or locations as they want. User-defined words can be specified in the Custom Key/Value field as below:
Word |
Platform |
Usage |
GCM |
APNS |
TENCENT |
ADM |
customKey |
Android, iOS, Tencent |
Optional, Object, Array, String, Number |
data.customKey |
customKey |
custom_content.customKey |
data.customKey |
Example of Message Delivery
- content.default at the request body of Send Message API is a must.
1. Send to All
Below is an example of sending messages to all registered targets.
Request Body
{
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "NOTIFICATION"
}
Description
- If target.type is set 'ALL', messages are sent to all tokens.
2. Send to Specific Users
Below is an example of sending messages to specific users based on their IDs.
Request Body
{
"target" : {
"type" : "UID",
"to": ["uid-01", "uid-02"]
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "NOTIFICATION"
}
Description
- Set UID for target.type and User ID for target.to, and send messages to particular users.
3. Send to Particular Countries or Push-type Users
.Below is an example of sending messages to users of particular countries or devices (like Android or iOS).
Request Body
{
"target" : {
"type" : "ALL",
"countries": ["KR", "JP"],
"pushTypes": ["GCM", "APNS"]
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "NOTIFICATION"
}
Description
- Set country code for target.countries and push type for target.pushTypes, and send messages to users who meet conditions.
4. Convert Messages per Push Type
Below is an example of conversion rule, applied for each push type for sending messages:
Request Body
{
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "title",
"body": "body",
"badge": 1,
"customKey": "value"
}
},
"messageType" : "NOTIFICATION"
}
Messages Received at GCM (Android)
{
"data": {
"title": "title",
"body": "body",
"customKey": "value"
}
}
Messages Received at APNS (iOS)
{
"aps": {
"alert": {
"title": "title",
"body": "body"
},
"badge": 1
},
"customKey": "value"
}
Messages Received at TENCENT (Android)
{
"title": "title",
"body": "body",
"custom_content": {
"customKey": "value"
}
}
Messages Received at ADM (Fire OS)
{
"data": {
"title": "title",
"body": "body",
"customKey": "value"
}
}
Description
- Messages entered at Content are converted for each push type before delivered.
- Reserved words, such as title or body, are set at specified locations when converted to messages for each push type before they're delivered.
Other user-defined fields are set at Custom Key locations of each push type.
- Reserved words defined at particular push types only, such as badge or consolidationKey, are excluded from other push types.
For instance, badge is set for APNS (iOS) messages only, but not for GCM, TENCENT or ADM.
5. Advertising Messages
Below is an example of advertising words to be added for ad messages.
Request Body
{
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "Special Event for Friday",
"body": "Now order at 50% off the price!"
}
},
"messageType" : "AD",
"contact": "1588",
"removeGuide": "Menu > Set Notifications"
}
Messages Received for ko (Korean) at GCM(Android)
{
"data": {
"title": "(AD) Special Event for Friday 1588",
"body": "Now order at 50% off the price!\n Menu > Set notifications"
}
}
Messages Received for ko (Korean) at APNS(iOS)
{
"aps": {
"alert": {
"title": "(AD) Special Event for Friday 1588",
"body": "Now order at 50% off the price!\n Menu > Set notification"
}
}
}
Messages Received for ja (Japanese) for GCM(Android)
{
"data": {
"title": "Special Event for Friday",
"body": "Now order at 50% off the price!"
}
}
Messages Received for ja (Japanese) for APNS(iOS)
{
"aps": {
"alert": {
"title": "Special Event for Friday",
"body": "Now order at 50% off the price!"
}
}
}
Description
- Set AD (Advertisement) for messsageType to send ad messages, and include contact number and how to withdraw consent to receiving ad messages for contact and removeGuide, respectively.
- When sending messages for each push type, title shall include the word, AD, and contact number, while body include withdrawal method to consent to receiving ad messages.
- AD is included to ad messages only for the users whose language code is Korean (ko, or ko-). Like the example shows, overseas users (e.g. Japanese) cannot find the word.
6. Messages in Multiple Languages
Below shows an example of sending messages in various languages.
Request Body
{
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "title",
"body": "body",
"customKey": "value"
},
"ko" : {
"title": "title",
"body": "body",
"customKey": "Set for such language codes starting with'ko' or 'ko-'."
},
"ja" : {
"title": "タイトル",
"body": "プッシュ・メッセージ"
}
},
"messageType" : "NOTIFICATION"
}
Messages Received for ko (Korean) at GCM(Android)
{
"data": {
"title": "title",
"body": "body",
"customKey": "Set for the language codes starting with'ko'or 'ko-'."
}
}
Messages Received for ko-KR (Korean) at GCM(Android)
{
"data": {
"title": "title",
"body": "body",
"customKey": "Set for the language codes starting with'ko'."
}
}
Messages Received for ja (Japanese) for GCM(Android)
{
"data": {
"title": "タイトル",
"body": "プッシュ・メッセージ",
"customKey": "value"
}
}
Messages Received for en (English) for GCM(Android)
{
"data": {
"title": "title",
"body": "body",
"customKey": "value"
}
}
Description
- Enter a message for each language code below Content and it shall be converted to the same or similar language of the token before delivery.
When there is no matching language code for the code, default message shall be delivered. For English users whose code is en, content.default is delivered.
- Conversion is applied to a closest language code even if it may not perfectly match.
Users of ko-KR (Korean) shall be delivered with content.ko, even if the request body show content.ko only.
- customKey is delivered with content.default as it is not defined in content.ja: enter common messages to content.defalt.
7. Rich Messages
When the 'richMessage' field is defined at 'content', rich messages can be delivered.
Such messages can be sent along with Common, Ad, or Multi-Language Messages.
v1.7 or higher SDKs are required.
Request Body
{
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title" : "title",
"body" : "body",
"richMessage" : {
"buttons" : [{
"name" : "Button Name",
"submitName": "Send Button Name",
"buttonType" : "REPLY | OPEN_APP | OPEN_URL | DISMISS",
"link" : "URL | ...",
"hint" : "Enter your message."
}
],
"media" : {
"sourceType" : "REMOTE | LOCAL",
"source" : "URL | LOCAL_RESOURCE",
"mediaType" : "IMAGE | GIF | VEDIO | AUDIO",
"extension" : "jpg | png",
"expandable" : true
},
"largeIcon" : {
"sourceType" : "REMOTE | LOCAL",
"source" : "URL | LOCAL_RESOURCE"
},
"group" : {
"key" : "KEY",
"description" : "Group of Notifications"
}
}
}
},
"messageType" : "NOTIFICATION"
}
Field |
Usage |
Description |
richMessage |
Optional, Object |
Required for rich messages |
richMessage.buttons |
Optional, Object Array |
Buttons added for rich messages: up to 3. |
richMessage.button.name |
Required, String |
Button name |
richMessage.button.submitName |
Optional, String |
Send button name: shows when the button type on iOS is REPLY. |
richMessage.button.buttonType |
Required, String |
Button type: REPLY, OPEN_APP, OPEN_URL, or DISMISS |
richMessage.button.link |
Required, String |
Link connected at the press of the button |
richMessage.button.hint |
Required, String |
Hint for a button |
richMessage.media |
Optional, Object |
Media added for rich messages |
richMessage.media.sourceType |
Required, String |
Media location: REMOTE or LOCAL |
richMessage.media.source |
Required, String |
Address where media is located |
richMessage.media.mediaType |
Required, String |
Media type: IMAGE, GIF, VEDIO, or AUDIO. Android supports IMAGE only. |
richMessage.media.extension |
Required, String |
Extension of media file |
richMessage.media.expandable |
Required, Boolean |
Click to expand media on Android |
richMessage.largeIcon |
Optional, Object |
Large icons added for rich messages: only on Android. |
richMessage.largeIcon.sourceType |
Required, String |
Location of large icons: REMOTE or LOCAL |
richMessage.largeIcon.source |
Required, String |
Address where media is located |
richMessage.group |
Optional, Object |
Bind many messages into a group: only on Android |
richMessage.group.key |
Required, String |
Key of a group |
richMessage.group |
Required, String |
Description of a group |
Get
List
GET /push/v2.0/appkeys/{appkey}/messages?pageIndex={pageIndex}&pageSize={pageSize}&from={from}&to={to}&deliveryType={deliveryType}&messageStatus={messageStatus}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
pageIndex |
Optional, Number |
Default is 0 |
pageSize |
Optional, Number |
Default is 25; Max 100 |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD, 2018-04-24T06:00:00.000%2B09:00) |
deliveryType |
Optional, String |
'INSTANT'(immediate delivery), 'RESERVATION'(scheduled delivery) |
messageStatus |
Optional, String |
'READY', 'PROCESSING', 'COMPLETE', 'CANCEL_NO_TARGET', 'CANCEL_INVALID_CERTIFICATE', 'CANCEL_INVALID_MESSAGE', 'CANCEL_UNSUPPORTED_MESSAGE_TYPE', 'CANCEL_UNAUTHORIZED', 'CANCEL_UNKNOWN' |
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
},
"messages" : [{
"messageId" : 0,
"messageIdString": "0",
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "AD",
"contact": "1588-1588",
"removeGuide": "menu > setting",
"timeToLiveMinute": 60,
"createdDateTime": "2017-02-13T09:30:00.000+09:00",
"completedDateTime": "2017-02-13T09:30:00.000+09:00",
"targetCount": 1000,
"sentCount": 1000,
"messageStatus": "COMPLETE",
"provisionedResourceId": "[a-zA-Z0-9]{16}"
}],
"toatalCount": 1
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/messages
Field |
Usage |
Description |
createdDateTime |
- |
Date and time of message creation (ISO 8601) |
completedDateTime |
- |
Date and time of delivery completed (ISO 8601) |
targetCount |
- |
Number of target tokens to deliver |
sentCount |
- |
Number of tokens actually delivered |
provisionedResourceId |
- |
Provisioned resource ID of a message delivered |
totalCount |
- |
Total number of filtered messages |
- “messageStatus” displays the status of a message as follows:
- READY: Request for message delivery has been registered.
- PROCESSING: Message has been created and is ready for, or on delivery.
- COMPLETE: Message delivery has been completed.
- CANCEL_NO_TARGET: Delivery has been cancelled because there is no target. Delivery may be cancelled due to the following reasons:
When there is no registered token;
When no user agreed to receive ad push messages;
When no user agreed to receive night-time ad push messages (21:00 – 08:00); and,
When there is no token available as existing ones are deleted.
- CANCEL_INVALID_CERTIFICATE: Delivery has been cancelled because the certificate is wrong. Need to check the status of certificate.
- CANCEL_INVALID_MESSAGE: Delivery has been cancelled because the format of message is incorrect.
- CANCEL_UNSUPPORTED_MESSAGE_TYPE: Delivery has been cancelled because the type of message is incorrect
- CANCEL_UNAUTHORIZED: Has failed in the process of certificate authorization. Need to check the status of certificate.
- CANCEL_UNKNOWN: Error occurred internally.
Get
GET /push/v2.0/appkeys/{appkey}/messages/{message-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
messageId |
Required, Number |
Message ID |
Request Body
N/A
Response Body
{
"message" : {
"messageId" : 0,
"messageIdString": "0",
"target" : {
"type" : "ALL"
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "AD",
"contact": "1588-1588",
"removeGuide": "menu > setting",
"timeToLiveMinute": 60,
"createdDateTime": "2017-02-13T09:30:00.000+09:00",
"completedDateTime": "2017-02-13T09:30:00.000+09:00",
"targetCount": 1000,
"messageStatus": "COMPLETE",
"provisionedResourceId": "[a-zA-Z0-9]{16}"
},
"header" : {
"isSuccessful" : true,
"resultCode": 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/messages/{messageId}
List Failed Messages
Can list messages that are failed in delivery.
However, invalid token (INVALID_TOKEN) is not deemed as a delivery failure.
GET /push/v2.0/appkeys/{appkey}/message-errors?messageId={messageId}&messageErrorType={messageErrorType}&messagErrorCause={messageErrorCause}&from={from}&to={to}&limit={limit}
HEADER
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
messageId |
Optional, Number |
Message ID |
messageErrorType |
Optional, String |
'CLIENT_ERROR', 'EXTERNAL_ERROR', 'INTERNAL_ERROR' |
messageErrorCause |
Optional, String |
'UNSUPPORTED_MESSAGE_TYPE', 'INVALID_MESSAGE', 'INVALID_CERTIFICATE', 'UNAUTHORIZED', 'EXPIRED_TIME_OUT', 'APNS_ERROR', 'GCM_ERROR', 'TENCENT_ERROR', 'AGENT_ERROR', 'ADM_ERROR' |
from |
Optional, DateTime String |
Up to the latest 30 days, or 7 days for default (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
to |
Optional, DateTime String |
Up to the latest 30 days, or 7 days for default (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
limit |
Optional, Number |
Size to list at once: default and maximum value is 1,000 |
Description
-
messageErrorType and messageErrorCause mean the followings:
- CLIENT_ERROR: Client’s wrong request
- UNSUPPORTED_MESSAGE_TYPE: Unsupported type of message
- INVALID_MESSAGE: Invalid message
- INVALID_CERTIFICATE: Expired or wrong certificate
- UNAUTHORIZED: Expired or wrong certificate
- EXTERNAL_ERROR: Error in external services related to push, such as APNS, CGM, Tencent, or ADM
- APNS_ERROR: Delivery to APNS (iOS) failed
- GCM_ERROR: Delivery to GCM (Google) failed
- TENCENT_ERROR: Delivery to Tencent failed
- ADM_ERROR: Delivery to ADM failed
- INTERNAL_ERROR: Internal error of push
- EXPIRED_TIME_OUT: Valid time expired due to delivery delay
- AGENT_ERROR: Agent Delivery failed due to internal error of Agent
-
When header.resultCode is 40010 in the Response Body, query with shorter period (from, to).
Request Body
N/A
Response Body
{
"messageErrors" : [{
"messageId" : 0,
"messageIdString" : "0",
"pushType" : "GCM",
"messageErrorType" : "ClientError",
"messageErrorCause" : "INVALID_CERTIFICATE",
"payload" : {
"data" : {
"title" : "title",
"body" : "body"
}
},
"createdDateTime" : "2017-05-18T15:47:00.000+09:00",
"tokens" : [{
"uid" : "uid-1",
"token" : "token-1"
}
]
}
],
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "Success."
}
}
{
"messageErrors" : [{
...
}],
"header" : {
"resultCode" : 40010,
"resultMessage" : "Client Error. Too much:use'from' and 'to' shorten. totalCount<10>",
"isSuccessful" : false
}
}
Field |
Usage |
Description |
messageId |
- |
ID of failed messages |
messageIdString |
- |
ID of failed messages |
pushType |
- |
'GCM', 'APNS', 'APNS_SANDBOX', 'TENCENT', 'APNS_VOIP', 'APNS_SANDBOXVOIP', 'ADM' |
payload |
- |
Messages actually delivered on a device |
tokens |
- |
UID and token of recipient to failed delivery |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/message-errors
Get Message Delivery/Receipt Statistics
Enable Message Delivery Receipt and apply v1.4 or higher SDK, so as to check the status of message delivery/receipt. Can get collected data with statistics API. Go to the [Console] > [Settings] tab to enable the function.
GET /push/v2.0/appkeys/{appkey}/statistics/message-delivery-receipts?from={from}&to={to}&event={event}&timeUnit={timeUnit}&messageId={messageId}
HEADER
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
event |
Optional, String |
'SENT', 'SENT_FAILED', 'RECEIVED', 'OPENED' |
timeUnit |
Optional, String |
'MINUTES', 'HOURS', 'DAYS' When value is not available, statistics are randomly provided, depending on the retrieved period. A day or more is displayed in Days, between 1 and 24 hours is in Hours, and less than 1 hour is in Minutes. |
messageId |
Optional, Number |
Message ID |
Request Body
N/A
Response Body
{
"messageDeliveryReceiptStatistics" : [{
"dateTime" : "2016-07-11 17:50:00.00+9:00",
"sent" : 13,
"sentFailed": 0,
"received" : 12,
"opened" : 10
}
],
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
dateTime |
Optional, DateTime String |
ISO 8601 |
sent |
Optional, Number |
Number of deliveries from a server |
sentFailed |
Optional, Number |
Number of failed delivery from a server |
received |
Optional, Number |
Number of receipt on a device |
opened |
Optional, Number |
Number of user’s click-to-open on device |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/statistics/message-delivery-receipts
Scheduled Messages
Create
Create Schedule for Delivery of Scheduled Messages
POST /push/v2.0/appkeys/{appkey}/schedules
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
Request Body
{
"type" : "EVERY_MONTH",
"fromDate" : "2016-12-30",
"toDate" : "2017-01-02",
"times" : [
"12:00",
"17:00"
],
"days" : [
1,
15
],
"daysOfWeek": [
"SUNDAY",
"MONDAY"
]
}
Field |
Usage |
Description |
type |
Required, String |
'EVERY_DAY' (daily), 'EVERY_WEEK' (weekly), 'EVERY_MONTH' (monthly) |
fromDate |
Required, Date String |
Start date of scheduled message (YYYY-MM-DD) |
toDate |
Required, Date String |
End date of scheduled message (YYYY-MM-DD) |
times |
Required, Time String |
Delivery hour/minute of scheduled message (hh:mm) |
days |
Optional, Number Array |
Set when the type is ‘EVERY_MONTH’ (1, 2, ..., 31: 1day, 2 days, ..., 31days) |
daysOfWeek |
Optional, String Array |
Set when the type is ‘EVERY_WEEK’ ('SUNDAY', 'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY') |
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
},
"schedules" : [
"2016-12-01T12:00",
"2016-12-01T17:00",
"2016-12-15T12:00",
"2016-12-15T17:00",
"2017-01-01T12:00",
"2017-01-01T17:00",
"2017-01-15T12:00",
"2017-01-15T17:00",
"2017-02-01T12:00",
"2017-02-01T17:00",
"2017-02-15T12:00",
"2017-02-15T17:00"
]
}
Field |
Usage |
Description |
schedules |
- |
Date and time (ISO 8601, e.g. YYYY-MM-DDThh:mm) |
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/schedules -d '{"type":"EVERY_MONTH","fromDate":"2016-12-30","toDate":"2017-01-02","times":["12:00","17:00"],"days":[1,15],"daysOfWeek":["SUNDAY","MONDAY"]}'
Create Scheduled Messages
POST /push/v2.0/appkeys/{appkey}/reservations
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
Request Body
{
"schedules" : [
"2016-12-30T12:40",
"2016-12-31T12:40"
],
"isLocalTime" : false,
"target" : {
"type" : "UID",
"to": ["uid-1", "uid-2"]
},
"content" : {
"default" : {
"title": "title",
"body": "body"
}
},
"messageType" : "AD",
"contact": "1588-1588",
"removeGuide": "menu > setting",
"timeToLiveMinute": 1,
"provisionedResourceId": "id"
}
Field |
Usage |
Description |
schedules |
Required, DateTime String Array |
List of delivery schedule of scheduled messages |
isLocalTime |
Required, Boolean |
Whether to be sent on the local-time basis |
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
},
"reservation" : {
"reservationId": 666810348995587,
"reservationIdString": "666810348995587"
}
}
Field |
Usage |
Description |
reservationId |
Number |
ID of scheduled message |
reservationIdString |
String |
ID string of scheduled messages |
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations -d '{"schedules":["2016-12-30T12:40","2016-12-31T12:40"],"isLocalTime":false,"target":{"type":"UID","to":["uid"]},"content":{"default":{"title":"title","body":"body"}},"messageType":"AD","contact":"1588-1588","removeGuide":"매뉴 > 설정","timeToLiveMinute":1}'
Get
List
GET /push/v2.0/appkeys/{appkey}/reservations?pageIndex={pageIndex}&pageSize={pageSize}&reservationStatus={reservationsStatus}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
pageIndex |
Optional, Number |
Default is 0 |
pageSize |
Optional, Number |
Default is 25; Max 100 |
from |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
to |
Optional, DateTime String |
Up to the latest 30 days (ISO 8601, e.g. YYYY-MM-DDThh:mm:ss.SSSTZD) |
reservationStatus |
Optional, String |
'RESERVED', 'COMPLETE' |
Request Body
N/A
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
},
"reservations" : [{
"reservationId" : 666810348995587,
"reservationIdString" : "666810348995587",
"schedules" : [{
"scheduleId" : 2455708,
"scheduleIdString" : "2455708",
"reservationId" : 666810348995587,
"reservationIdString" : "666810348995587",
"deliveryDateTime" : "2016-12-30T12:40:00.000+09:00",
"timezoneOffset" : 0,
"scheduleStatus" : "READY"
}
],
"isLocalTime" : false,
"target" : {
"type" : "UID",
"to" : [
"uid"
]
},
"content" : {
"default" : {
"title" : "default title",
"body" : "default body"
},
"ko" : {
"title" : "Korean title",
"body" : "Korean body"
}
},
"messageType" : "NOTIFICATION",
"timeToLiveMinute" : 60,
"createdDateTime" : "2016-12-30T10:34:40.000+09:00",
"updatedDateTime" : "2016-12-30T10:34:40.000+09:00",
"completedDateTime" : "2016-12-30T10:34:40.000+09:00",
"reservationStatus" : "RESERVED"
}
],
"totalCount" : 1
}
Field |
Usage |
Description |
reservationIdString |
- |
ID string of scheduled message |
createdDateTime |
- |
Date and time of scheduled message creation (ISO 8601) |
updatedDateTime |
- |
Date and time of message modification (ISO 8601) |
completedDateTime |
- |
Date and time of message delivery completed; if not completed, show the current time (ISO 8601) |
reservationStatus |
- |
'RESERVED', 'COMPLETED' |
schedules.scheduleId |
- |
Delivery schedule ID of scheduled messages |
schedules.scheduleIdString |
- |
ID String of delivery schedule of a scheduled message |
schedules.reservationIdString |
- |
ID String of a scheduled message to which message delivery schedule belongs |
schedules.deliveryDateTime |
- |
Date and time of scheduled message delivery |
schedules.timezoneOffset |
- |
Delivery time zone of scheduled message: to be set when delivered on the local-time basis |
schedules.scheduleStatus |
- |
Status of delivery schedule of scheduled messages, such as 'READY', 'SENDING', 'CANCELED', and 'DONE'READY', 'SENDING', 'CANCELED', 'DONE' |
totalCount |
- |
Number of total registered scheduled messages |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations
Get
GET /push/v2.0/appkeys/{appkey}/reservations/{reservation-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
N/A
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
},
"reservation" : {
"reservationId" : 666810348995587,
"reservationIdString" : "666810348995587",
"schedules" : [{
"scheduleId" : 2455708,
"scheduleIdString" : "2455708",
"reservationId" : 666810348995587,
"reservationIdString" : "666810348995587",
"deliveryDateTime" : "2016-12-30T12:40:00.000+09:00",
"timezoneOffset" : 0,
"scheduleStatus" : "READY"
}
],
"isLocalTime" : false,
"target" : {
"type" : "UID",
"to" : [
"uid"
]
},
"content" : {
"default" : {
"title" : "default title",
"body" : "default body"
},
"ko" : {
"title" : "Korean title",
"body" : "Korean body"
}
},
"messageType" : "NOTIFICATION",
"timeToLiveMinute" : 60,
"createdDateTime" : "2016-12-30T10:34:40.000+09:00",
"updatedDateTime" : "2016-12-30T10:34:40.000+09:00",
"completedDateTime" : "2016-12-30T10:34:40.000+09:00",
"reservationStatus" : "RESERVED"
}
}
Field |
Usage |
Description |
updatedDateTime |
DateTime String |
Date and time of schedule modification (ISO 8601) |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations/{reservationId}
List Delivered Scheduled Messages
GET /push/v2.0/appkeys/{appkey}/reservations/{reservation-id}/messages?pageIndex={pageIndex}&pageSize={pageSize}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
reservationId |
Required, Number |
ID of scheduled messages |
pageIndex |
Optional, Number |
Default is 0 |
pageSize |
Optional, Number |
Default is 25; Max 100 |
Request Body
N/A
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "success",
"isSuccessful" : true
},
"messages" : [{
"messageId" : 356125922591162,
"messageIdString" : "356125922591162",
"target" : {
"type" : "ALL",
"pushTypes" : ["GCM", "APNS", "APNS_SANDBOX", "TENCENT", "ADM"]
},
"content" : {
"default" : {
"title" : "Scheduled message for 6:55",
"body" : "API v2"
}
},
"messageType" : "NOTIFICATION",
"createdDateTime" : "2017-04-05T18:55:00.000+09:00",
"completedDateTime" : "2017-04-05T18:55:00.000+09:00",
"targetCount" : 38,
"sentCount" : 38,
"messageStatus" : "COMPLETE"
}
],
"totalCount" : 1
}
Field |
Usage |
Description |
totalCount |
- |
Total number of delivered messages |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations/{reservationId}/messages
Modify
Modify Scheduled Messages
PUT /push/v2.0/appkeys/{appkey}/reservations/{reservationId}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"schedules" : [
"2016-12-30T10:05",
"2016-12-31T12:40"
],
"target" : {
"type" : "UID",
"to" : [
"uid"
]
},
"content" : {
"default" : {
"title" : "default title",
"body" : "default body"
},
"ko" : {
"title" : "Korean title",
"body" : "Korean body"
}
},
"isLocalTime" : false,
"messageType" : "NOTIFICATION"
}
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
}
}
Example
curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations/{reservationId} -d '{"schedules":["2018-12-30T12:40","2018-12-31T12:40"],"isLocalTime":false,"target":{"type":"UID","to":["uid"]},"content":{"default":{"title":"title","body":"body"}},"messageType":"AD","contact":"1588-1588","removeGuide":"menu > setting","timeToLiveMinute":1}'
Delete
Delete Scheduled Messages
DELETE /push/v2.0/appkeys/{appkey}/reservations?reservationIds={reservationId,}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
appkey |
Required, String |
Path Variable, Appkey issued on Enable |
reservationIds |
Required, Number Array |
Delimited by ',' (e.g. reservationIds=1,2) |
Request Body
N/A
Response Body
{
"header" : {
"resultCode" : 0,
"resultMessage" : "SUCCESS",
"isSuccessful" : true
}
}
Example
curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/reservations?reservationIds={reservationId,}
Create
POST /push/v2.0/appkeys/{appkey}/tags
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"tagName" : "Thirty"
}
Field |
Usage |
Description |
tagName |
Required, String |
Tag name, the maximum length is 255 |
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"tag" : {
"tagId" : "12345678"
}
}
Field |
Usage |
Description |
tagId |
Required, String |
Created tag ID, the length of 8 |
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags -d '{"tagName":"thirty"}'
Create Additional UIDs to a Tag
- Refers to appending UIDs to a tag: by adding UIDs, tags of an UID add up.
- The maximum number of tags to an UID is 16
POST /push/v2.0/appkeys/{appkey}/tags/{tag-id}/uids
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"uids" : [
"uid-01",
"uid-02"
]
}
Field |
Usage |
Description |
uids |
Required, String Array |
UID string array, 16 to the longest; UID, 64 to the longest |
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId}/uids -d '{"uids":["uid"]}'
Set a Tag List to UID
- Refers to replacing tags of an UID: an old tag is deleted and replaced by a new tag.
POST /push/v2.0/appkeys/{appkey}/uids
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"uid" : "uid-01",
"tagIds" : [
"12345678",
"23456789"
]
}
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids -d '{"uid":"uid","tagIds":["TAG_ID"]}'
Get
GET /push/v2.0/appkeys/{appkey}/tags?tagName={tagName}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
tagName |
Optional, String |
Tag name |
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"tags" : [
{
"tagId" : "12345678",
"tagName" : "tagName",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00",
"updatedDateTime" : "2017-07-07T07:07:07.777+09:00"
}
]
}
Field |
Usage |
Description |
createdDateTime |
Required, Date Time String |
Date and time of creation (ISO 8601) |
updatedDateTime |
Required, Date Time String |
Date and time of modification (ISO 8601) |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags
Get a Tag
GET /push/v2.0/appkeys/{appkey}/tags/{tag-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"tag" : {
"tagId" : "12345678",
"tagName" : "thirty",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00",
"updatedDateTime" : "2017-07-07T07:07:07.777+09:00"
}
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId}
List UID of a Tag
- Get a list of tagged UIDs
GET /push/v2.0/appkeys/{appkey}/tags/{tag-id}/uids?offsetUid={uid}&limit={limit}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
offsetUid |
Optional, String |
Get starts next from set UID |
limit |
Optional, Number |
Number of UIDs to list |
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"uids" : [
{
"uid" : "uid-01",
"tags" : [
{
"tagId" : "tag-id-01",
"tagName" : "tag-name-01",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00",
"updatedDateTime" : "2017-07-07T07:07:07.777+09:00"
}
],
"contacts" : [
{
"contactType" : "TOKEN_GCM",
"contact" : "token",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00"
}
]
}
]
}
Field |
Usage |
Description |
contacts |
-, Object Array |
List of UID contacts and tokes |
contactType |
-, String |
Token type, 'TOKEN_GCM', 'TOKEN_APNS', 'TOKEN_APNS_SANDBOX', 'TOKEN_TENCENT', 'TOKEN_ADM' |
contact |
-, String |
Token |
createdDateTime |
Required, Date Time String |
Date and time of creation (ISO 8601) |
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId}/uids
Get UID
- Get a UID.
- When a token is registered, contact is registered
GET /push/v2.0/appkeys/{appkey}/uids/{uid}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"uid" : {
"uid" : "uid-01",
"tags" : [
{
"tagId" : "12345678",
"tagName" : "tag-name-01",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00",
"updatedDateTime" : "2017-07-07T07:07:07.777+09:00"
}
],
"contacts" : [
{
"contactType" : "TOKEN_GCM",
"contact" : "token",
"createdDateTime" : "2017-07-07T07:07:07.777+09:00"
}
]
}
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids/uid
Modify
PUT /push/v2.0/appkeys/{appkey}/tags/{tag-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
{
"tagName" : "30s"
}
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId} -d '{"tagName":"thirty three"}'
Delete
DELETE /push/v2.0/appkeys/{appkey}/tags/{tag-id}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId}
Delete UIDs
- When an UID is deleted, contact and token are deleted altogether.
DELETE /push/v2.0/appkeys/{appkey}/uids?uids={uid,}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Field |
Usage |
Description |
uids |
-, Object Array |
Delimit list of UIDs to delete by comma (,): can delete up to 16 at once. |
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids?uids=uid
Delete UIDs of a Tag
- Only the tag-UID relation is deleted.
- Contact and Token are not deleted.
DELETE /push/v2.0/appkeys/{appkey}/tags/{tagId}/uids?uids={uid,}
Content-Type: application/json;charset=UTF-8
X-Secret-Key: [a-zA-Z0-9]{8}
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-Secret-Key: SECRET_KEY" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/tags/{tagId}/uids?uids=uid
UID
Create
- Add tags to a UID with Tag ID.
- No Secret Key is required: call is available from an app.
POST /push/v2.0/appkeys/{appkey}/uids/{uid}/tag-ids
Content-Type: application/json;charset=UTF-8
Request Body
{
"tagIds": ["TAG_ID01"]
}
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X POST -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids/uid/tag-ids -d '{"tagIds":["TAG_ID"]}'
Get
Get Tag ID of UID
- Retrieve tag ID of an UID.
- No Secret Key is required: call is available from an app.
GET /push/v2.0/appkeys/{appkey}/uids/{uid}/tag-ids
Content-Type: application/json;charset=UTF-8
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
},
"tagIds": ["TAG_ID01"]
}
Example
curl -X GET -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids/uid/tag-ids
Modify
- Modify tags with a tag ID.
- No Secret Key is required: call is available from an app.
PUT /push/v2.0/appkeys/{appkey}/uids/{uid}/tag-ids
Content-Type: application/json;charset=UTF-8
Request Body
{
"tagIds": ["TAG_ID02"]
}
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Example
curl -X PUT -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids/uid/tag-ids -d '{"tagIds":["TAG_ID"]}'
- Get tag IDs of UID.
- No Secret Key is required: call is available from an app.
DELETE /push/v2.0/appkeys/{appkey}/uids/{uid}/tag-ids?tagIds={tagId,}
Content-Type: application/json;charset=UTF-8
Request Body
N/A
Response Body
{
"header" : {
"isSuccessful" : true,
"resultCode" : 0,
"resultMessage" : "SUCCESS"
}
}
Field |
Usage |
Description |
tagIds |
Required, String Array |
Query String, Tag ID to delete: delimited by comma (,) |
Example
curl -X DELETE -H "Content-Type: application/json;charset=UTF-8" https://api-push.cloud.toast.com/push/v2.0/appkeys/{appkey}/uids/uid/tag-ids?tagIds=TAG_ID_01,TAG_ID_02
- Document Updates
- (2018.06.26) Added example of message delivery
- (2018.06.26) Added pushType ADM
- (2018.05.29) Added v2.1 Get Token API
- (2018.05.29) Added Guide for API curl
- (2018.04.24) Added description of timeUnit field for v2.0 Message Delivery Receipt API
- (2018.04.24) Added description of DateTime format for v2.0 API
- (2018.03.22) Added v2.0 UID API
- (2018.02.22) Added deliveryType field for v2.0 Get Message API
- (2018.02.22) Added pushType APNS_VOIP, and APNS_SANDBOXVOIP
- (2017.11.23) Modified description of v2.0 Message Error API
- (2017.08.24) Corrected error in description of v2.0 Token, Reservation API
- (2017.07.20) Added v2.0 Tag API Reference
- (2017.07.20) Added Get Failed Message API
- (2017.04.25) Added v2.0 API Reference
- (2017.02.23) Updated List Tokens API