Basic information
API URL
https://sens.apigw.ntruss.com/alimtalk/v2
Go to SENS Alim Talk API Swagger
API Header
| Category | Mandatory | Description |
|---|---|---|
| Content-Type | Mandatory | Specify 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. - Request is considered invalid if the timestamp differs from the current time by more than 5 minutes. |
| 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 | - Signature that encrypts the body of the example above with secret key mapped to the access key ID - Use the HMAC-SHA256 encryption algorithm. |
Go to the creation guide of NAVER Cloud Platform authentication key and signature
Message
Send message
Send a message.
Request URL
POST https://sens.apigw.ntruss.com/alimtalk/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
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Headers
Request body
{
"plusFriendId":"string",
"templateCode":"string",
"messages":[
{
"countryCode":"string",
"to":"string",
"title":"string",
"content":"string",
"headerContent":"string",
"itemHighlight":{
"title":"string",
"description":"string"
},
"item":{
"list":[
{
"title":"string",
"description":"string"
}
],
"summary":{
"title":"string",
"description":"string"
}
},
"buttons":[
{
"type":"string",
"name":"string",
"linkMobile":"string",
"linkPc":"string",
"schemeIos":"string",
"schemeAndroid":"string"
}
],
"useSmsFailover": "boolean",
"failoverConfig": {
"type": "string",
"from": "string",
"subject": "string",
"content": "string"
}
}
],
"reserveTime": "yyyy-MM-dd HH:mm",
"reserveTimeZone": "string"
}
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| plusFriendId | Mandatory | String | Name of Kakao Talk Channel ((formerly) Plus Friend ID) | |
| templateCode | Mandatory | String | Template code | |
| messages | Mandatory | Object | Message information | - See items below (messages.XXX). - Up to 100 |
| messages.countryCode | Optional | String | Recipient country code | Default: 82 |
| messages.to | Mandatory | String | Recipient number | |
| messages.title | Optional | String | Alim Talk highlighted content | It can only be used in a highlighting type template. |
| messages.content | Mandatory | String | Alim Talk message content | |
| messages.headerContent | Optional | String | Alim Talk header content | - It can only be used in an item list type template. - Less than 16 bytes can be entered. |
| messages.itemHighlight | Optional | Object | Item highlight | It can only be used in an item list type template. |
| messages.itemHighlight.title | Mandatory | String | Item highlight title | - It can only be used in an item list type template. When there's no image - Up to 30 characters can be entered (2 lines). - Up to 15 characters per line can be entered. When there are images - Up to 21 characters can be entered (2 lines). - Up to 10 characters per line can be entered. - If the length goes over 2 lines, then the excess is represented by an ellipsis. |
| messages.itemHighlight.description | Mandatory | String | Item highlight description | - It can only be used in an item list type template. When there's no image - Up to 19 characters per line can be entered. When there are images - Up to 13 characters per line can be entered - If the length goes over one line, then the excess is represented by an ellipsis |
| messages.item | Optional | Object | Item list | It can only be used in an item list type template. |
| messages.messages.item.list | Mandatory | Array of Object | Item list | - It can only be used in an item list type template. - It must be between 2 and 10. |
| messages.item.list.title | Mandatory | String | Item list title | - It can only be used in an item list type template. - Up to 6 characters in length can be entered. |
| messages.item.list.description | Mandatory | String | Item list description | - It can only be used in an item list type template. - Up to 23 characters in length can be entered. |
| messages.summary | Optional | Object | Item summary information | It can only be used in an item list type template. |
| messages.summary.title | Mandatory | String | Item summary title | - It can only be used in an item list type template. - Up to 6 characters in length can be entered. |
| messages.summary.description | Mandatory | String | Item summary description | - It can only be used in an item list type template. - Allowed characters: currency symbols (unicode currency symbols, yuan, yen, won), currency codes (ISO 4217), number, commas, decimal points, spaces - Up to two decimal places allowed. - Up to 23 characters in length can be entered. |
| messages.buttons | Optional | Array of Object | Alim Talk message button | See the following template button information. |
| messages.buttons.type | Mandatory | String | Button type | See the following template button information. |
| messages.buttons.name | Mandatory | String | Button name | See the following template button information. |
| messages.useSmsFailover | Optional | Boolean | SMS failover use status | - Available only on Kakao Talk Channels where failover is configured - Default: Follow the failover settings of Kakao Talk Channel. |
| messages.failoverConfig | Optional | Object | Failover settings | See the items below. |
| messages.failoverConfig.type | Optional | String | Failover SMS message type | - SMS or LMS - Default: automatically applied according to the content length (SMS if 90 bytes or less, LMS if it exceeds 90 bytes) |
| messages.failoverConfig.from | Optional | String | Failover SMS caller ID | - Default: caller ID selected when setting up failover - Failover does not work when using an unauthorized caller ID. |
| messages.failoverConfig.subject | Optional | String | Failover SMS title | - Used when operating in LMS type - Default: Kakao Talk Channel name |
| messages.failoverConfig.content | Optional | String | Failover SMS content | Default: Alim Talk message content (excluding button) |
| 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 date and time (default: Asia/Seoul) - List of supported time zones * Use the TZ database name value. |
Caution
- If you use mandatory fields in the request body, no spaces are allowed (only applicable when adding).
- The content and buttons must be entered according to the registered and approved template specifications.
- If the message you want to send does not meet the template specifications, then your request to send the message will fail.
Note
- If the template has images registered, then the registered images will be sent even if you don't insert it in the content in the request body when sending a message separately.
- SMS failover works if the Alim Talk reception result code is not successful, and SMS alternative delivery through the failover feature is not performed for codes with the prefix B.
You can check the Web console manual (formerly, user manual) for a guide on template registration and inspection. Go to Template Registration Guide
Template button information
| Type | Name | Mandatory item |
|---|---|---|
| DS | Track package | |
| WL | Web link | linkMobile, linkPc (URL starting with http:// or https://) |
| AL | App link | schemeIos, schemeAndroid |
| BK | Bot keyword | |
| MD | Send message | |
| AC | Add channel | The button name is fixed as Add channel. |
List of supported couriers
| Courier | Courier name | Invoice number |
|---|---|---|
| ePOST Korea | Korea Post | 13-digit number, or 6-digit number + 7-digit number (separator is "-" or "_") |
| Logen | Logen | 11-digit number, or 3-digit number + 4-digit number + 4-digit number (separator is "-" or "_") |
| ILYANG Logis | - ILYANG Logis - ILYANG - ILYANG Logis |
9 to 11-digit number |
| FedEX | - FedEx - FedEx - fedex |
12-digit number |
| HANJIN TRANSPORTATION | HANJIN TRANSPORTATION | 10-digit number or 12-digit number |
| KYOUNGDONG EXPRESS | KYOUNGDONG EXPRESS | 9 to 16-digit number, or 4-digit number + 3-digit number + 6-digit number (separator is "-") |
| HAPDONG EXPRESS | HAPDONG EXPRESS | 9 to 16-digit number |
| LOTTE GLOBAL LOGISTICS | - LOTTE GLOBAL LOGISTICS - LOTTE LOGISTICS - HYUNDAI EXPRESS - Hyundai Logistics |
12-digit number or 4-digit number + 4-digit number + 4-digit number (separator is "-") |
| Nonghyup Logis | Nonghyup Logis | 12-digit number |
| HONAM LOGISTICS | HONAM LOGISTICS | 10-digit number |
| CHUNIL PARCEL | CHUNIL PARCEL | 11-digit number |
| DAESIN PARCEL SERVICES | DAESIN PARCEL SERVICES | 13-digit number |
| KUNYONG EXPRESS | KUNYONG EXPRESS | 10-digit number |
| CUpost | - CUpost - CU post |
10-digit number, 12-digit number, or 4-digit number + 4-digit number + 4-digit number (separator is "-" or "_") |
| CVSnet convenience store logistics | - GS postbox - GS convenience store logistics - CVSnet convenience store logistics |
10-digit number, 12-digit number, or 4-digit number + 4-digit number + 4-digit number (separator is "-" or "_") |
| Handex | Handex | 10-digit number or 14-digit number |
| TNT Express | - TNTExpress - TNT Express - TNT Express |
8 to 9-digit number |
| USPS | USPS | 10-digit number, 22-digit number, or 2 uppercase English letters + 9-digit number + 2 uppercase English letters (no separator) |
| EMS | EMS | 2 uppercase English letters + 9-digit number + 2 uppercase English letters (no separator) |
| DHL | DHL | 10-digit number |
| GOODSTOLUCK | GOODSTOLUCK | 4-digit number + 4-digit number + 4-digit number (separator is "-") |
- Buttons are not automatically added for unsupported couriers.
- You can use web link (WL) buttons to link to the tracking page.
Response body
{
"requestId":"string",
"requestTime":"string",
"statusCode":"string",
"statusName":"string",
"messages":[
{
"messageId":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"useSmsFailover":"boolean"
}
]
}
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| requestId | Mandatory | String | Delivery request ID | |
| requestTime | Mandatory | DateTime | Delivery request time | yyyy-MM-dd'T'HH:mm:ss.SSS |
| statusCode | Mandatory | String | Request status code | - Success: 202 - Failure: the rest - It follows the HTTP status specification. |
| statusName | Mandatory | String | Request status name | - Success: success - Being processed: processing - Being reserved: reserved - Failure: fail |
| messages.messageId | Mandatory | String | Message ID | |
| messages.countryCode | Optional | String | Recipient country code | Default: 82 |
| messages.to | Mandatory | String | Recipient number | |
| messages.content | Mandatory | String | Alim Talk message content | |
| messages.requestStatusCode | Mandatory | String | Delivery request status code | - Success: A000 - Failure: other codes (reason for failure specified in the Desc category) |
| messages.requestStatusName | Mandatory | String | Delivery request status name | - Success: success - Failure: fail |
| messages.requestStatusDesc | Mandatory | String | Delivery request status content | |
| messages.useSmsFailover | Mandatory | Boolean | SMS failover use status |
Response status
| HTTP Status | Desc |
|---|---|
| 202 | Accepted (delivery request completed) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Get message delivery request
Get the message delivery request.
Request URL
GET https://sens.apigw.ntruss.com/alimtalk/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
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Parameters
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| requestId | Mandatory | String | Request ID | Delivery request ID |
| plusFriendId | Mandatory | String | Kakao channel | Name of the registered channel |
| requestStartTime | Mandatory | String | Query start time | yyyy-MM-dd'T'HH:mm:ss |
| requestEndTime | Mandatory | String | Query end time | yyyy-MM-dd'T'HH:mm:ss |
| completeStartTime | Mandatory | String | Delivery completion start time | yyyy-MM-dd'T'HH:mm:ss |
| completeEndTime | Mandatory | String | Delivery completion end time | yyyy-MM-dd'T'HH:mm:ss |
| messageId | Optional | String | Message ID | |
| requestStatusName | Optional | String | Request status | success, fail |
| messageStatusName | Optional | String | Request status | success, processing, fail |
| templateCode | Optional | String | Template code | Registered template code |
| to | Optional | String | Message recipient number | Number excluding hyphens (-) |
| nextToken | Optional | String | Next page token | See the content of the following note. |
| pageSize | Optional | Integer | Page size | Default: 20, Max: 100 When querying including requestId, default: 100 |
Note
- You can only see the history of messages sent within the last 30 days.
- One of the following must be specified: requestId, requestStartTime + requestEndTime, or completeStartTime + completeEndTime.
- requestStartTime + requestEndTime and completeStartTime + completeEndTime can't be used at the same time.
- The query range of requestStartTime to requestEndTime is limited to a maximum of 31 days.
- The query range of completeStartTime to completeEndTime is limited to a maximum of 24 hours.
- If the query condition does not include a requestId, plusFriendId is required.
- nextToken
- It is valid only if a
nextTokenresponse was received in the previous request, indicating that the results of the next page can be requested. If there are additional results, you can set thenextTokenvalue from the previous response to this parameter to query the results for the next page.
- It is valid only if a
Headers
Request body
None
Response body
{
"requestId": "string",
"statusCode": "string",
"statusName": "string",
"messages": [
{
"requestTime": "string",
"messageId": "string",
"countryCode": "string",
"to": "string",
"content": "string",
"plusFriendId": "string",
"templateCode": "string",
"completeTime": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string",
"useSmsFailover": "boolean",
"failover": {
"smsServiceId": "string",
"requestId": "string",
"messageId": "string",
"requestStatusCode": "string",
"requestStatusName": "string",
"requestStatusDesc": "string",
"messageStatus": "string",
"messageStatusCode": "string",
"messageStatusName": "string",
"messageStatusDesc": "string"
}
}
],
"pageSize": "integer",
"nextToken": "string",
"itemCount": "integer",
"hasMore": "boolean"
}
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| requestId | Optional | String | Delivery request ID | Displayed only when queried by requestId |
| statusCode | Mandatory | String | Request status code | 202 - Success Others - Failure * It follows the HTTP status specification. |
| statusName | Mandatory | String | Request status name | success - Success processing - Being delivered reserved - Being reserved fail - Failure |
| messages.requestTime | Mandatory | DateTime | Delivery request time | yyyy-MM-dd'T'HH:mm:ss.SSS |
| messages.messageId | Mandatory | String | Message ID | |
| messages.countryCode | Optional | String | Recipient country code | Default: 82 |
| messages.to | Mandatory | String | Recipient number | |
| messages.content | Mandatory | String | Alim Talk message content | |
| messages.plusFriendId | Mandatory | String | Name of Kakao Talk Channel ((formerly) Plus Friend ID) | |
| messages.templateCode | Mandatory | String | Template code | |
| messages.completeTime | Optional | DateTime | Delivery reporting (processing completion) time | yyyy-MM-dd'T'HH:mm:ss |
| messages.requestStatusCode | Mandatory | String | Delivery request status code | A000 - Success Other codes - Failure (reason for failure specified in the Desc category) |
| messages.requestStatusName | Mandatory | String | Delivery request status name | success - Success fail - Failure |
| messages.requestStatusDesc | Mandatory | String | Delivery request status content | |
| messages.messageStatusCode | Mandatory | String | Delivery result status code | 0000 - Success Other codes - Failure (reason for failure specified in the Desc category) |
| messages.messageStatusName | Mandatory | String | Delivery result status name | success - Success processing - Being processed * Undergoing processing in the message delivery server after successful sending request * messageCode and messageDesc are not searched. fail - Failure |
| messages.messageStatusDesc | Mandatory | String | Delivery result status content | |
| messages.useSmsFailover | Mandatory | Boolean | SMS failover use status | |
| messages.failover | Optional | Object | SMS Failover | |
| messages.failover.smsServiceId | Optional | String | SMS failover service ID | |
| messages.failover.requestId | Optional | String | SMS failover delivery request ID | |
| messages.failover.messageId | Optional | String | SMS failover delivery message ID | |
| messages.failover.requestStatusCode | Optional | String | SMS failover delivery request status code | See the Error code table. |
| messages.failover.requestStatusName | Optional | String | SMS failover delivery request status name | success - Success fail - Failure |
| messages.failover.requestStatusDesc | Optional | String | SMS failover delivery request status content | |
| messages.failover.messageStatus | Optional | String | SMS failover delivery request status | READY: ready PROCESSING: being processed COMPLETED: processing completed |
| messages.failover.messageStatusCode | Optional | String | SMS failover delivery device received status result code | See the Error code table. |
| messages.failover.messageStatusName | Optional | String | SMS failover delivery device received result name | |
| messages.failover.messageStatusDesc | Optional | String | SMS failover delivery device received content | |
| pageSize | Mandatory | Integer | Page size | |
| nextToken | Optional | String | Next page token | See the content of the following note. |
| itemCount | Mandatory | Integer | Number of messages in the pages retrieved | |
| hasMore | Mandatory | Boolean | It indicates whether there is a next page. |
Note
- If the query condition does not include a requestId, then requestId is not included.
- nextToken
- The
nextTokenis included in the response only if the next page of the queried result exists. You can set the value ofnextTokento the Get request API parameter to query the next page of results.
- The
Response status
| HTTP Status | Desc |
|---|---|
| 200 | OK (search completed) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Get message delivery result
Get the message delivery result.
Request URL
GET https://sens.apigw.ntruss.com/alimtalk/v2/services/{serviceId}/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
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
| messageId | Mandatory | String | Message ID | Message identifier that is returned when the message is sent |
Headers
Request body
None
Response body
{
"messageId":"string",
"requestId":"string",
"requestTime":"string",
"completeTime":"string",
"plusFriendId":"string",
"templateCode":"string",
"countryCode":"string",
"to":"string",
"content":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string",
"useSmsFailover":"boolean",
"failover": {
"smsServiceId":"string",
"requestId":"string",
"requestStatusCode":"string",
"requestStatusName":"string",
"requestStatusDesc":"string",
"messageId":"string",
"messageStatus":"string",
"messageStatusCode":"string",
"messageStatusName":"string",
"messageStatusDesc":"string"
}
}
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| messageId | Mandatory | String | Message ID | |
| requestId | Mandatory | String | Delivery request ID | |
| requestTime | Mandatory | DateTime | Delivery request time | yyyy-MM-dd'T'HH:mm:ss.SSS |
| completeTime | Optional | DateTime | Delivery reporting (processing completion) time | yyyy-MM-dd'T'HH:mm:ss |
| plusFriendId | Mandatory | String | Name of Kakao Talk Channel ((formerly) Plus Friend ID) | |
| templateCode | Mandatory | String | Template code | |
| countryCode | Optional | String | Recipient country code | Default: 82 |
| to | Mandatory | String | Recipient number | |
| content | Mandatory | String | Alim Talk message content | |
| requestStatusCode | Mandatory | String | Delivery request status code | A000 - Success Other codes - Failure (reason for failure specified in the Desc category) |
| requestStatusName | Mandatory | String | Delivery request status name | success - Success fail - Failure |
| requestStatusDesc | Mandatory | String | Delivery request status content | |
| messageStatusCode | Mandatory | String | Delivery result status code | 0000 - Success Other codes - Failure (reason for failure specified in the Desc category) |
| messageStatusName | Mandatory | String | Delivery result status name | success - Success processing - Being processed * Undergoing processing in the message delivery server after successful sending request * messageCode and messageDesc are not searched. fail - Failure |
| messageStatusDesc | Mandatory | String | Delivery result status content | |
| messages.useSmsFailover | Mandatory | Boolean | SMS failover use status | |
| messages.failover | Optional | Object | SMS failover use status | |
| messages.failover.smsServiceId | Optional | String | SMS failover service ID | |
| messages.failover.requestId | Optional | String | SMS failover delivery request ID | |
| messages.failover.requestStatusCode | Optional | String | SMS failover delivery request status code | See the Error code table. |
| messages.failover.requestStatusName | Optional | String | SMS failover delivery request status name | success - Success fail - Failure |
| messages.failover.requestStatusDesc | Optional | String | SMS failover delivery request status content | |
| messages.failover.messageId | Optional | String | SMS failover delivery message ID | |
| messages.failover.messageStatus | Optional | String | SMS failover delivery request status | READY: ready PROCESSING: being processed COMPLETED: processing completed |
| messages.failover.messageStatusCode | Optional | String | SMS failover delivery device received status result code | See the Error code table. |
| messages.failover.messageStatusName | Optional | String | SMS failover delivery device received result name | |
| messages.failover.messageStatusDesc | Optional | String | SMS failover delivery device received content |
Failover request status code
| requestStatusCode | Desc |
|---|---|
| 0 | Succeeded |
| E4000 | The failover settings are not valid. |
| E4001 | The failover settings information is omitted. |
| E4002 | The failover SMS service is not configured. |
| E4003 | The failover SMS type (SMS, LMS) is not configured. |
| E4004 | The failover SMS caller ID is not configured. |
| E4005 | The failover SMS title is not configured. |
| E4006 | The failover SMS content is not configured. |
| E4007 | The failover SMS recipient number is not configured. |
| E4008 | The failover SMS service is not available. |
| E4009 | The failover SMS caller ID is not authenticated. |
| E4010 | The failover SMS free 080 unsubscribing service is not available. |
| E4999 | Failover settings parsing error (required to contact Support) |
| E5000 | Internal error (required to contact Support) |
Response status
| HTTP Status | Desc |
|---|---|
| 200 | OK (search completed) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Reserved message
Get reserved message status
Get the reservation status of message delivery.
GET https://sens.apigw.ntruss.com/alimtalk/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
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| 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
Request body
None
Response body
{
"reserveId": "string",
"reserveTimeZone": "string",
"reserveTime": "string",
"reserveStatus": "string"
}
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| 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 date and time (default: Asia/Seoul) - List of supported time zones * Use the TZ database name value. |
| reserveStatus | Mandatory | String | Reservation status | - Waiting to be sent: READY - Requesting to send: PROCESSING - Delivery canceled: CANCELED - Delivery request failure: FAIL - Delivery request successful: DONE - Delivery request failure (timeout): STALE |
Response status
| HTTP Status | Desc |
|---|---|
| 200 | OK (search completed) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Cancel reserved message
Cancel the reserved message delivery.
DELETE https://sens.apigw.ntruss.com/alimtalk/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
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| 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
Request body
None
Response body
None
Response status
| HTTP Status | Desc |
|---|---|
| 204 | No Content (deletion completed) |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Kakao Talk Channel
Get channel
Get Kakao Talk Channels.
GET https://sens.apigw.ntruss.com/alimtalk/v2/services/{serviceId}/channels
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Headers
Request body
None
Response body
[
{
"createTime": "string",
"updateTime": "string",
"serviceId": "string",
"channelId": "string",
"channelName": "string",
"channelStatus": "string",
"useSmsFailover": "boolean",
"failoverServiceId": "string",
"failoverTelNo": "string",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| createTime | Mandatory | String | Creation time | format: LocalDateTime |
| updateTime | Optional | String | Edited time | format: LocalDateTime |
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
| channelId | Mandatory | String | Kakao Talk Channel ID | |
| channelName | Mandatory | String | Kakao Talk Channel name | |
| channelStatus | Mandatory | String | Kakao Talk Channel status | - Normal: ACTIVE - Deleted: DELETED - Being deleted permanently: DELETING_PERMANENTLY - Deleted permanently: PERMANENTLY_DELETED - Blocked: BLOCKED - Deletion pending: PENDING_DELETE |
| useSmsFailover | Mandatory | Boolean | Use status of alternative SMS delivery | |
| failoverServiceId | Optional | String | Failover SMS service ID | |
| failoverTelNo | Optional | String | Failover caller ID | |
| isBlock | Mandatory | Boolean | Channel blocking status | |
| isDormant | Mandatory | Boolean | Channel dormancy status |
Response status
| HTTP Status | Desc |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Alim Talk template
Get template
Get Alim Talk templates registered in the Kakao Talk Channel.
GET https://sens.apigw.ntruss.com/alimtalk/v2/services/{serviceId}/templates?channelId=
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}
Path Variables
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Parameters
- channelId is a required value, and it returns the details of the template when using templateCode.
- Additional information including comments is only displayed for detailed searches.
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| channelId | Mandatory | String | Channel ID | Channel ID registered to Kakao Talk |
| templateCode | Optional | String | Template code | The detailed search is returned when searched using templateCode.Registered template code |
| templateName | Optional | String | Template name | like search results are returned. |
| pageSize | Optional | Integer | Page size | Default: 100 (Only numbers between 1 and 100 can be entered.) |
| pageIndex | Optional | Integer | Page index | Default: 0 |
Headers
Request body
None
Response body
[
{
"createTime": "string",
"updateTime": "string",
"channelId": "string",
"templateCode": "string",
"templateName": "string",
"categoryCode": "string",
"categoryName": "string",
"messageType" : "string",
"emphasizeType" : "string",
"content": "string",
"adContent": "string",
"extraContent": "string",
"title": "string",
"additionalTitle": "string",
"comments": [
{
"commentId": "string",
"content": "string",
"status": "string",
"createTime": "string",
"attachment": [
{
"fileName": "string",
"fileUrl": "string"
}
]
}
],
"templateInspectionStatus": "string",
"templateStatus": "string",
"buttons":[
{
"order":"integer",
"type":"string",
"name":"string",
"linkMobile":"string",
"linkPc":"string",
"schemeIos":"string",
"schemeAndroid":"string"
}
],
"imageName": "string",
"imageUrl": "string",
"headerContent": "string",
"itemHighlight": {
"title": "string",
"description": "string",
"imageUrl": "string"
},
"item": {
"list": [
{
"title": "string",
"description": "string"
}
],
"summary": {
"title": "string",
"description": "string"
}
},
"securityFlag": "boolean",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
| Category | Mandatory | Type | Description | Remarks |
|---|---|---|---|---|
| createTime | Mandatory | String | Creation time | format: LocalDateTime |
| updateTime | Optional | String | Edited time | format: LocalDateTime |
| channelId | Mandatory | String | Kakao Talk Channel ID | |
| templateCode | Mandatory | String | Template code | |
| templateName | Mandatory | String | Template name | |
| categoryCode | Mandatory | String | Template category code | |
| categoryName | Mandatory | String | Template category name | |
| messageType | Mandatory | String | Template message type | - BA: Basic type - EX: Additional information type - AD: Ad addition type - MI: Mixed type |
| emphasizeType | Mandatory | String | Template emphasis type | - NONE: Basic type - TEXT: Highlighting type - IMAGE: Image type - ITEM_LIST: Item list type |
| content | Mandatory | String | Template content | |
| adContent | Optional | String | Ad message | |
| extraContent | Optional | String | Additional Information | |
| title | Optional | String | Highlighting type title | |
| additionalTitle | Optional | String | Highlighting type additional title | |
| comments.commentId | Mandatory | String | Inspection ID | |
| comments.content | Mandatory | String | Inspection content | |
| comments.status | Mandatory | String | Inspection status | - Inspection completed: APR - Inspection rejected: REJ |
| comments.create | Mandatory | String | Inspection time | |
| comments.attachment | Optional | Object | Inspection inquiry attachment | |
| comments.attachment.fileName | Mandatory | String | File name | |
| comments.attachment.fileUrl | Mandatory | String | File URL | |
| templateInspectionStatus | Mandatory | String | Template inspection status | - Accept: ACCEPT - Register: REGISTER - Inspection in progress: INSPECT - Completed: COMPLETE - Rejected: REJECT |
| templateStatus | Mandatory | String | Template status | - Normal: ACTIVE - Ready: READY - Stopped: STOP |
| buttons | Optional | Array of Object | Alim Talk message button | See the parent template button information. |
| buttons.order | Mandatory | Integer | Button order | Button registration order |
| buttons.type | Mandatory | String | Button type | See the parent template button information. |
| buttons.name | Mandatory | String | Button name | See the parent template button information. |
| buttons.linkMobile | Optional | String | Mobile button link | See the registered template button information. |
| buttons.linkPc | Optional | String | PC button link | See the registered template button information. |
| buttons.schemeIos | Optional | String | iOS button scheme | See the registered template button information. |
| buttons.schemeAndroid | Optional | String | Android button scheme | See the registered template button information. |
| title | Optional | String | Highlighting type title | |
| additionalTitle | Optional | String | Highlighting type additional title | |
| useImage | Mandatory | Boolean | Image usage status | |
| imageName | Optional | String | Image name | |
| imageUrl | Optional | String | Image URL | |
| useHeaderContent | Mandatory | Boolean | Header usage status | |
| headerContent | Optional | String | Header content | |
| useItemHighlight | Mandatory | Boolean | Item highlight usage status | |
| useItemHighlightImage | Mandatory | Boolean | Item highlight image usage status | |
| itemHighlight | Optional | Object | Item highlight | Displayed only when using item highlight |
| itemHighlight.title | Optional | String | Item highlight title | |
| itemHighlight.description | Optional | String | Item highlight content | |
| itemHighlight.imageUrl | Optional | String | Item highlight image URL | |
| item | Optional | Object | Item | Displayed only when using item |
| item.list | Optional | String | Item list | Displayed only when using item list |
| item.list.title | Optional | String | Item name | |
| item.list.description | Optional | String | Item content | |
| item.summary | Optional | String | Item summary information | Displayed only when using item summary information |
| item.summary.title | Optional | String | Item summary information name | |
| item.summary.description | Optional | String | Item summary information content | |
| securityFlag | Mandatory | Boolean | Security setting status | |
| isBlock | Mandatory | Boolean | Template blocking status | |
| isDormant | Mandatory | Boolean | Template dormancy status |
Note
- channelId is a required value, and it returns the details of the template when using templateCode.
- Additional information including comments is only displayed for detailed searches.
Response status
| HTTP Status | Desc |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Errors
Alim Talk reception result code
| Status | Error text | Desc |
|---|---|---|
| 0000 | - | Normal delivery |
| 1001 | NoJsonBody | Request body is not in JSON format. |
| 1002 | InvalidHubPartnerKey | Invalid partner key |
| 1003 | InvalidSenderKey | Invalid outgoing profile key |
| 1004 | NoValueJsonElement | Name not found in request body (JSON) |
| 1005 | SenderNotFound | Outgoing profile not found |
| 1006 | DeletedSender | Deleted outgoing profile |
| 1007 | StoppedSender | Blocked outgoing profile |
| 1011 | ContractNotFound | Contract information not found |
| 1012 | InvalidUserKeyException | Invalid format of user key request |
| 1013 | InvalidAppLink | Invalid app connection |
| 1014 | InvalidBizNum | Invalid business registration number |
| 1015 | TalkUserIdNotFonud | Invalid app user id request |
| 1016 | BizNumNotEqual | Mismatched business registration number |
| 1020 | InvalidReceiveUserException | No valid user identifier value |
| 1021 | BlockedProfile | Blocked Kakao Talk Channel (check from the Kakao Talk Channel operation tool) |
| 1022 | DeactivatedProfile | Closed Kakao Talk Channel (check from the Kakao Talk Channel operation tool) |
| 1023 | DeletedProfile | Deleted Kakao Talk Channel (check from the Kakao Talk Channel operation tool) |
| 1024 | DeletingProfile | Deletion-pending Kakao Talk Channel (check from the Kakao Talk Channel operation tool) |
| 1025 | SpammedProfile | Message-blocked Kakao Talk Channel (check from the Kakao Talk Channel operation tool) |
| 1026 | UnableUseMessageType | The request was made with response_method unavailable for the msg_type. (image Alim Talk (AI) can't be sent in real time) |
| 1027 | - | Message delivery failure due to channel message restriction status |
| 1030 | InvalidParameterException | Invalid parameter request |
| 1033 | - | Template type and message type mismatch |
| 2000 | FailedToCheckFriendshipException | Error when checking the friend relationship with the Talk Channel (system error) |
| 2003 | FailedToSendMessageByNoFriendshipException | Message delivery failure (if Kakao Talk Channel is not added in the test server) |
| 2004 | FailedToMatchTemplateException | Error when checking template match (internal Kakao error) |
| 2005 | FailedToReadImageException | Error reading image meta information from Kakao |
| 2006 | FailedToMatchSerialNumberPrefixPattern | Serial number format mismatch |
| 3000 | UnexceptedExcetpion | Occurrence of an unexpected error |
| 3005 | AckTimeoutException | A message was sent, but the read receipt was not confirmed (success uncertain) |
| 3006 | FailedToSendMessageException | Message delivery failed due to Kakao's internal system error. |
| 3008 | InvalidPhoneNumberException | Phone number error |
| 3010 | JsonParsseExcetpion | JSON parsing error |
| 3011 | MessageNotFoundException | Message does not exist. |
| 3012 | SerialNumberDuplicatedException | Message serial number is duplicated. (A unique value must be assigned for the message serial number.) |
| 3013 | MessageEmptyException | Blank message |
| 3014 | MessageLengthOverLimitException | Message length limit error (exceeding 1000 characters for text type, 400 characters for image type) |
| 3015 | TemplateNotFoundException | Template not found |
| 3016 | NoMatchedTemplateException | Message content does not match the template. |
| 3018 | NoSendAvailableException | Message could not be sent. |
| 3019 | MessageNoUserException | Not a Talk user |
| 3020 | MessageUserBlockedAlimTalkException | Alim Talk blocked |
| 3021 | MessageNotSupportedKakaotalkException | Minimum support version for Talk not met |
| 3022 | NoSendAvailableTimeException | Outside the time available for sending messages (Friend Talk/marketing messages can be sent from 08:00 to 20:00.) |
| 3023 | MessageInvalidVideoException | Unable to send the video embedded in the message (the video address or thumbnail image address is incorrect or the thumbnail image does not meet the specifications) |
| 3024 | MessageInvaildImageException | The image contained in the message can't be sent. |
| 3025 | ExceedMaxVariableLengthException | Variable character limit exceeded |
| 3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | Inquiry/bot switching button extra, event character limit exceeded |
| 3027 | NoMatchedTemplateButtonException | Button content does not match the template. |
| 3028 | NoMatchedTemplateTitleException | Message highlighting title does not match the template. |
| 3029 | ExceedMaxTitleLengthException | Message highlighting title length limit exceeded (50 characters) |
| - | ||
| 3030 | NoMatchedTemplateWithMessageTypeException | Message type does not match the template highlight type. |
| 3031 | NoMatchedTemplateHeaderException | Header does not match the template. |
| 3032 | ExceedMaxHeaderLengthException | Header length limit exceeded (16 characters) |
| 3033 | NoMatchedTemplateItemHighlightException | Item highlight does not match the template. |
| 3034 | ExceedMaxItemHighlightTitleLengthException | Item highlight title length limit exceeded (30 characters with no images, 21 characters with images) |
| 3035 | ExceedMaxItemHighlightDescriptionLengthException | Item highlight description length limit exceeded (19 characters with no images, 14 characters with images) |
| 3036 | NoMatchedTemplateItemListException | Item list does not match the template. |
| 3037 | ExceedMaxItemDescriptionLengthException | Item's description length limit exceeded in the item list (23 characters) |
| 3038 | NoMatchedTemplateItemSummaryException | Item summary information does not match the template |
| 3039 | ExceedMaxItemSummaryDescriptionLengthException | Item summary information's description length limit exceeded (14 characters) |
| 3040 | InvalidItemSummaryDescriptionException | Item summary information's description includes characters that are not allowed (inclusion of characters other than currency symbol/code, number, comma, period, and space) |
| 3041 | MessageInvalidWideItemListLengthException | Wide item list count minimum, maximum mismatch |
| 3042 | NoMatchedTemplateRepresentLinkException | Representative link does not match template |
| 3046 | ExceedMaxAdditionalContentLengthException | Additional information maximum length limit error |
| 3047 | ExceedMaxCommerceTitleLengthException | Commerce information, product name maximum length limit error |
| 3050 | MessageNotSupportedUnsubscribeException | Opt-out specifications (N type) not supported |
| 3051 | InvalidateCarouselItemMinException or InvalidateCarouselItemMaxException | Carousel item list count minimum, maximum mismatch |
| 3052 | CarouselMessageLengthOverLimitException | Carousel item message length exceeded |
| 3056 | WideItemListTitleLengthOverLimitException | Wide item list title length limit error |
| 3058 | CarouselHeaderLengthOverLimitException | Carousel header length limit error |
| 3059 | MessageNotSupportedCouponException | Coupon specifications not supported |
| 4000 | ResponseHistoryNotFoundException | Message delivery result not found |
| 4001 | UnKnownMessageStatusError | Unknown message status |
| 7011 | - | Serial number pattern error |
| 7014 | - | Message validity timeout error |
| 8512 | - | Recipient type not found |
| 8514 | - | request_id not found |
| 8520 | - | Unsupported product type error |
| 8521 | - | Message type not supported error |
| 8522 | - | Test type not supported error |
| 8523 | - | Response method not supported error |
| 8530 | - | Recipient list size error |
| 8999 | - | Internal server error |
| 9998 | The service is not currently provided. | The admin is checking a problem that occurred in the system. |
| 9999 | The admin is checking an unknown problem that occurred in the system. | The admin is checking a problem that occurred in the system. |
| B000 | Prepare to relay failed | Failure of preliminary work for forwarding to the relay company |
| B001 | Request to relay failed | Relay company delivery failure |
| B002 | Filtering for request to relay failed | Filtered due to invalid request |
| B003 | Invalid phone number format | Invalid caller ID format |
| B004 | Quota Exceed | Quota exceeded |
| B005 | Message processing timeout exceed | The difference between the message request time and processing time is outside the allowable range |
| B400 | Invalid Request | Message format error |
| B999 | Unexpected server error | Unexpected error |