PUSH API Reference
  • PDF

PUSH API Reference

  • PDF

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

Basic info

API URL

https://sens.apigw.ntruss.com/push/v2

Go to SENS Push API Swagger

API Header

Item Mandatory Description
Content-Type Mandatory Specifies the request body content type as application/json (POST)
x-ncp-apigw-timestamp Mandatory This is the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
If the time difference compared to the API Gateway server is more than 5 minutes, then the request is considered invalid.
x-ncp-iam-access-key Mandatory This is the access key ID issued by the portal or Sub Account
x-ncp-apigw-signature-v2 Mandatory This is the signature that encrypted the body of the example above as SecretKey, which is mapped with the access key ID
HmacSHA256 is used as the HMAC encryption algorithm

Go to Guide for how to generate NAVER Cloud Platform authentication key and signature


Device

Register device tokens

This registers a device token and binds it to a user.

Request URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project

Headers

Go to API header

Request body

{
    "userId":"string",
    "country":"string",
    "language":"string",
    "timezone":"integer",
    "channelName":"string",
    "deviceType":"(GCM|APNS)",
    "deviceToken":"string",
    "isNotificationAgreement":"boolean",
    "isAdAgreement":"boolean",
    "isNightAdAgreement":"boolean"
}
Item Mandatory Type Description Note
userId Madantory String User ID ID identifying the user. Up to 128 characters
country Optional String Country code Device country setting (Default: KR)
* ISO-3166-1 alpha-2
* Uppercase letters only
language Optional String Language code Device language setting (Default: en)
* ISO-639-1
* Lowercase only
timezone Optional Integer Time zone Difference from UTC by seconds (Default: 32400)
* Example: 28800 (UTC+8)
channelName Optional String Channel name to be registered Enter the registered channel name to add to the channel
deviceType Mandatory String Device type GCM - Android
APNS - iOS
deviceToken Mandatory String Device token
isNotificationAgreement Mandatory Boolean Push notification message subscription status In case of false, no messages will be received
isAdAgreement Mandatory Boolean Ad message subscription status In case of false, no ad messages will be received
(messageType: AD)
isNightAdAgreement Mandatory Boolean Night ad message subscription status In case of false, no night ad messages will be received
(messageType: AD)
(Nighttime - 21:00 - 08:00)

Response body

None

Response statuses

HTTP Status Desc
201 Created (Successfully registered)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Search device tokens

This searches the registered device/user.

Request URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
userId Mandatory String User ID User ID bound when a device token is registered

Headers

Go to API header

Request body

None

Response body

{
    "userId":"string",
    "country":"string",
    "language":"string",
    "timezone":"integer",
    "channelName":"string",
    "notificationAgreement":"boolean",
    "adAgreement":"boolean",
    "nightAdAgreement":"boolean",
    "notificationAgreementTime":"datetime",
    "adAgreementTime":"datetime",
    "nightAdAgreementTime":"datetime",
    "createTime":"datetime",
    "updateTime":"datetime",
    "devices":[
        {
            "deviceType":"(GCM|APNS)",
            "deviceToken":"string"
        }
    ]
}
Item Mandatory Type Description Note
userId Madantory String User ID
country Madantory String Country code Device country setting (Default: KR)
* ISO-3166-1 alpha-2
* Uppercase letters only
language Madantory String Language code Device language setting (Default: en)
* ISO-639-1
* Lowercase only
As an exception, zh-Hant / zh-Hans can be used (case sensitive)
timezone Madantory Integer Time zone Difference from UTC by seconds (Default: 32400)
* Example: 28800 (UTC+8)
channelName Optional String Name of the registered channel
notificationAgreement Mandatory Boolean Push notification message subscription status In case of false, no messages will be received
adAgreement Mandatory Boolean Ad message subscription status In case of false, no ad messages will be received
(messageType: AD)
nightAdAgreement Mandatory Boolean Night ad message subscription status In case of false, no night ad messages will be received
(messageType: ADA)
(Nighttime - 21:00 - 08:00)
notificationAgreementTime Mandatory DateTime Date and time when the user consented to receive push notification messages The most recent time
adAgreementTime Mandatory DateTime Date and time when the user consented to receive ad messages The most recent time
nightAdAgreementTime Mandatory DateTime Date and time when the user consented to receive night ad messages The most recent time
createTime Mandatory DateTime Token registration time
updateTime Mandatory DateTime Token edit time
devices.deviceType Mandatory String Device type GCM - Android
APNS - iOS
devices.deviceToken Mandatory String Device token

Response statuses

HTTP Status Desc
200 OK (Successfully searched)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Delete device tokens

This deletes all the devices bound to a user (userId). The user is also deleted.

Request URL

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
userId Mandatory String User ID User ID bound when a device token is registered

Headers

Go to API header

Request body

None

Response body

None

Response statuses

HTTP Status Desc
204 No Content (Successfully deleted)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Channel

Create channel

This creates a channel.

Request URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
channelName Mandatory String Channel name Name of the channel to be created

Headers

Go to API header

Request body

{
    "channelName":"string",
    "channelDesc":"string"
}
Item Mandatory Type Description Note
channelName Mandatory String Channel name Name of the channel to be created
channelDesc Optional String Channel description Description of the channel to be created

Response body

None

Response statuses

HTTP Status Desc
201 Created (Successfully added)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict (Duplicate channel name)
500 Internal Server Error

Edit channel

This edits the channel.

Request URL

PUT https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project

Headers

Go to API header

Request body

[
    {
        "channelName":"string",
        "channelDesc":"string"
    }
]
Item Mandatory Type Description Note
channelName Mandatory String Channel name Up to 1000 requests available per request (List)
The description corresponding to the channel name is updated.
Name of the channel to be edited
channelDesc Optional String Channel description Description of the edited channel

Response body

[
    {
        "channelName": "string",
        "channelDesc": "string",
        "createTime": "localDateTime",
        "updateTime": "localDateTime"
    }
]
Item Mandatory Type Description Note
channelName Mandatory String Channel name Name of the channel to be created
channelDesc Optional String Channel description Description of the edited channel
createTime Mandatory String Creation time format: LocalDateTime
updateTime Optional String Editing time format: LocalDateTime

Response statuses

HTTP Status Desc
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Request
500 Internal Server Error

Search channel

This searches channels.

Request URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project

Parameters

Item Mandatory Type Description Note
channelName Optional String Channel name like searched results are returned
Name of the created channel
pageSize Optional Integer Page size default: 100
Only numbers between 0 and 100 can be entered
pageIndex Optional Integer Page index default: 0

Headers

Go to API header

Request body

None

Response body

[
    {
        "channelName": "string",
        "channelDesc": "string",
        "createTime": "localDateTime",
        "updateTime": "localDateTime"
    }
]
Item Mandatory Type Description Note
channelName Mandatory String Channel name Name of the created channel
channelDesc Optional String Channel description Description of the created channel
createTime Mandatory String Creation time format: LocalDateTime
updateTime Optional String Editing time format: LocalDateTime

Response statuses

HTTP Status Desc
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Request
500 Internal Server Error

Delete channel

This deletes a channel.

Request URL

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project

Headers

Go to API header

Request body

[
    {
        "channelName":"string"
    }
]
Item Mandatory Type Description Note
channelName Mandatory String Channel name Up to 1000 requests available per request (List)
Name of the deleted channel

Response body

None

Response statuses

HTTP Status Desc
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Request
500 Internal Server Error

Add users to channel

This adds a user to the channel.

Request URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels/{channelName}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
channelName Mandatory String Channel name Name of the channel to add a user
userId Mandatory String User ID User ID bound when a device token is registered

Headers

Go to API header

Request body

None

Response body

None

Response statuses

HTTP Status Desc
201 Created (Successfully added)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Delete users from channel

This deletes a user from the channel.

Request URL

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/channels/{channelName}/users/{userId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
channelName Mandatory String Channel name Name of the channel to delete a user
userId Mandatory String User ID User ID bound when a device token is registered

Headers

Go to API header

Request body

None

Response body

None

Response statuses

HTTP Status Desc
204 No Content (Successfully deleted)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Message

Send message

This sends a message.

Request URL

POST https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/messages

Content-Type: application/json; charset=utf-8
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project

Headers

Go to API header

Request body

{
    "messageType":"(AD | NOTIF)",
    "target":{
        "type":"(ALL | CHANNEL | USER)",
        "deviceType":"(GCM | APNS)",
        "to":[
            "string",
            "string"
        ],
        "country": [
            "string",
            "string"
        ]
    },
    "message":{
        "default":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        },
        "gcm":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        },
        "apns":{
            "content":"string",
            "custom":{
                "customKey1":"customValue1",
                "customKey2":"customValue2"
            },
            "option":{

            },
            "i18n":{
                "default":{
                    "content":"string"
                },
                "[language]":{
                    "content":"string"
                }
            }
        }
    },
    "reserveTime": "yyyy-MM-dd HH:mm",
    "reserveTimeZone": "string",
    "scheduleCode": "string"
}
Item Mandatory Type Description Note
messageType Optional String Message type NOTIF - Notification message
AD - Ad message
(default: NOTIF)
target.type Mandatory String Recipient type ALL - All devices registered to the service
CHANNEL - All devices registered to the channel
USER - All devices bound to the user
target.deviceType Optional String Recipient's device type GCM - Android
APNS - iOS
(All devices if it's null)
target.to Optional Array of String Recipient identifier ALL - No need to input
CHANNEL - Channel name
USER - User ID
target.country Optional Array of String Recipient country code Recipient device's country code
* ISO-3166-1 alpha-2
* Uppercase letters only
message Mandatory Object Common message to send Refer to the following common message specification for the message size
message.i18n Optional Object Object for processing multilingual message by device language Refer to the following multilingual message specification for the message size
reserveTime Optional String Reserved date and time Reserved date and time for message delivery (yyyy-MM-dd HH:mm)
reserveTimeZone Optional String Time zone of reserved date and time Time zone of reserved time and date (Default: Asia/Seoul)
* List of supported time zones
* Use the TZ database name value
scheduleCode Optional String Schedule code Schedule code to be registered

* Both GCM and FCM are supported for message delivery to Android devices, and NAVER Cloud Platform SENS uses the GCM type.

Common message

  • The message item of the message delivery requestBody is the specification for common messages.
  • It can be distinguished as message.default.XXX, message.gcm.XXX, and message.apns.XXX, message.default is required.
  • If you only create a default message, then the same message is sent to all push types. If you also create gcm and apns messages, then you can send separate messages for each push type.
  • The application priority is gcm = apns > default.
  • If a message is composed in message as in the following table, the messages for each push type are created and sent.
Message subsection Mandatory Type GCM APNS
content Optional String data.content alert or alert.body
custom Optional Object Specify as data.KEY Designate as the KEY of the same level as aps
option Optional Object Refer to the available options for each push type below
i18n Optional Object

Multilingual message

  • This is a specification for processing multilingual messages according to the language set in the device.
  • It can be classified as message.default.XXX and message.[language].XXX, and language follows the ISO-639-1 standard. Only lowercase letters can be used, but as an exception, zh-Hant and zh-Hans are available for simplified/traditional Chinese support.
    • ISO-639-1
    • Lowercase letters only
    • zh-Hant and zh-Hans are available (case sensitive)
  • language is the language code standard set during device registration.
  • The application priority is that it precedence overs message.content.
i18n subsection Mandatory Type GCM APNS
content Mandatory String data.content alert or alert.body

Available options for each push type

Response body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string"
}
Item Mandatory Type Description Note
requestId Mandatory String Request ID
requestTime Mandatory DateTime Request time
statusCode Mandatory String Request status code See the following response code
statusName Mandatory String Request status name success - Success
reserved - Being reserved
scheduled - Being scheduled
fail - Fail

Response statuses

HTTP Status Desc
202 Accepted (Successfully requested)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Search message delivery results

This searches the message delivery results.

Request URL

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/messages/{requestId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
requestId Mandatory String Message request ID Message identifier that is returned when sending the message

Headers

Go to API header

Request body

None

Response body

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string",
    "messageStatusCode":"string",
    "messageStatusName":"string",
    "completeTime":"string",
    "targetCount":"integer",
    "sentCount":"integer",
    "messageType":"string",
    "target":{
        ...
    },
    "message":{
        ...
    }
}
Item Mandatory Type Description Note
requestId Mandatory String Request ID
requestTime Mandatory DateTime Request time
statusCode Mandatory String Request status code 202 - Success
Others - Fail
statusName Mandatory String Request status name success - Success
fail - Fail
messageStatusCode Mandatory String Delivery status code 200 - Success
Others - Fail
messageStatusName Mandatory String Name of the delivery status success - Success
processing - Being processed
fail - Fail
completeTime Mandatory DateTime Delivery completion time
targetCount Mandatory Integer No. of requested devices
sentCount Mandatory Integer No. of successfully delivered devices
messageType Mandatory String Message type NOTIF - Notification message
AD - Ad message
target Mandatory Object Information of requested target
message Mandatory Object Information of requested message

Response statuses

HTTP Status Desc
200 OK (Successfully searched)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Reserved message

Search reserved message status

This searches the Reservation status of message delivery.

GET https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/reservations/{reserveId}/reserve-status

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
reserveId Mandatory String Reserved message ID Message identifier that is returned when searching the reserved delivery requests (requestId)

Headers

Go to API header

Request body

None

Response body

{
  "reserveId": "string",
  "reserveTimeZone": "string",
  "reserveTime": "string",
  "reserveStatus": "string"
}
Item Mandatory Type Description Note
reserveId Mandatory String Reserved message ID Message identifier that is returned when searching the reserved delivery requests (requestId)
reserveTime Mandatory String Reserved date and time Reserved date and time for message delivery (yyyy-MM-dd HH:mm)
reserveTimeZone Mandatory String Time zone of reserved date and time Time zone of reserved time and date (Default: Asia/Seoul)
* List of supported time zones
* Use the TZ database name value
reserveStatus Mandatory String Reservation status READY - Waiting to be sent
PROCESSING - Requesting to send
CANCELED - Delivery canceled
FAIL - Delivery request failure
DONE - Successful delivery request
STALE - Delivery request failure (timeout)

Cancel reserved message

This cancels the reserved message delivery.

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/reservations/{reserveId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
reserveId Mandatory String Reserved message ID Message identifier that is returned when searching the reserved delivery requests (requestId)

Headers

Go to API header

Request body

None

Response body

None

Response statuses

HTTP Status Desc
204 No Content (Successfully deleted)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Scheduled message

Cancel scheduled message

This cancels the message delivery schedule.

DELETE https://sens.apigw.ntruss.com/push/v2/services/{serviceId}/schedules/{scheduleCode}/messages/{messageId}

x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

Item Mandatory Type Description Note
serviceId Mandatory String Service ID Service ID issued when registering the project
scheduleCode Mandatory String Schedule code The code used for schedule registration
messageId Mandatory String Reserved message ID Message identifier that is returned when searching the scheduled delivery requests (requestId)

Headers

Go to API header

Request body

None

Response body

None

Response statuses

HTTP Status Desc
204 No Content (Successfully deleted)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.