AlimTalk APIs
- Print
- PDF
AlimTalk APIs
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Basic information
API URL
https://sens.apigw.ntruss.com/alimtalk/v2
Go to SENS AlimTalk 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) - The request is considered invalid if the time difference compared to the API Gateway server is more than 5 minutes |
x-ncp-iam-access-key | Mandatory | Access Key ID issued by the portal or Sub Account |
x-ncp-apigw-signature-v2 | Mandatory | - Signature of the body in the above example encrypted with a SecretKey mapped to Access Key ID - HmacSHA256 is used as the HMAC encryption algorithm. |
Go to NAVER Cloud Platform authentication key and signature creation guide
Messages
Send messages
Sends 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
Item | 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"
}
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
plusFriendId | Mandatory | String | Name of KakaoTalk 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's country code | default: 82 |
messages.to | Mandatory | String | Recipient's number | |
messages.title | Optional | String | AlimTalk highlighted content | Only available in templates of highlighting type |
messages.content | Mandatory | String | AlimTalk message content | |
messages.headerContent | Optional | String | AlimTalk header content | - Only available in templates of item list type - Enter less than 16 bytes |
messages.itemHighlight | Optional | Object | Item highlight | Only available in templates of item list type |
messages.itemHighlight.title | Mandatory | String | Item highlight title | - Only available in templates of item list type Without images - Up to 30 characters can be entered (2 lines) - Up to 15 characters can be entered in a line With images - Up to 21 characters can be entered (2 lines) - Up to 10 characters can be entered in a line - If the length goes over 2 lines, the excess is replaced by an ellipsis. |
messages.itemHighlight.description | Mandatory | String | Item highlight description | - Only available in templates of item list type Without images - Up to 19 characters can be entered (1 line) With images - Up to 13 characters can be entered (1 line) - If the length goes over 1 line, the excess is replaced by an ellipsis. |
messages.item | Optional | Object | Item list | It can only be used in a template with the item list type. |
messages.item.list | Mandatory | Array of Object | Item list | - It can only be used in a template with the item list type. - It must be between 2 and 10. |
messages.item.list.title | Mandatory | String | Item list title | - It can only be used in a template with the item list type. - Up to 6 characters can be entered |
messages.item.list.description | Mandatory | String | Item list description | - It can only be used in a template with the item list type. - Up to 23 characters can be entered |
messages.summary | Optional | Object | Item summary information | It can only be used in a template with the item list type. |
messages.summary.title | Mandatory | String | Item summary title | - It can only be used in a template with the item list type. - Up to 6 characters can be entered |
messages.summary.description | Mandatory | String | Item summary description | - It can only be used in a template with the item list type. - Allowed characters: currency symbols (Unicode currency symbols, yuan, yen, won), currency codes (ISO 4217), number, commas, periods, spaces - Two decimal places allowed - Up to 23 characters can be entered |
messages.buttons | Optional | Array of Object | AlimTalk 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 KakaoTalk Channels where Failover is set. - Default: follows the Failover set status of KakaoTalk 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: KakaoTalk Channel name |
messages.failoverConfig.content | Optional | String | Failover SMS content | Default: AlimTalk 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 are using the Mandatory field in the request Body, blanks are not allowed. (Only in the case of addition)
- 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 an image is registered in the template, when sending a message separately, the registered image will be sent even if you do not insert the corresponding content in the request body.
- SMS Failover operates when the AlimTalk reception result code shows not successful. For codes with the prefix "B," SMS replacement cannot be sent through the Failover function.
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 | Fix button names with 채널 추가 |
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 post - ILYANG post - 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 postbox | - GS Postbox - GS postbox - CVSnet postbox | 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 the tracking page with web link (WL) buttons.
Response bodies
{
"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"
}
]
}
Item | 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 - Failed: others - Follows the HTTP Status specifications. |
statusName | Mandatory | String | Request status name | - Success: success - Being processed: processing - Being reserved: reserved - Failed: fail |
messages.messageId | Mandatory | String | Message ID | |
messages.countryCode | Optional | String | Recipient's country code | default: 82 |
messages.to | Mandatory | String | Recipient number | |
messages.content | Mandatory | String | AlimTalk message content | |
messages.requestStatusCode | Mandatory | String | Delivery request status code | - Success: A000 - Failed: other codes (reason for failure specified in the Desc category) |
messages.requestStatusName | Mandatory | String | Delivery request status name | - Success: success - Failed: 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 |
Search for message delivery request
Search for 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
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Parameters
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
requestId | Mandatory | String | Request ID | Delivery request ID |
plusFriendId | Mandatory | String | Kakao Channel | Registered Channel name |
requestStartTime | Mandatory | String | Start time of search | yyyy-MM-dd'T'HH:mm:ss |
requestEndTime | Mandatory | String | End time of search | yyyy-MM-dd'T'HH:mm:ss |
completeStartTime | Mandatory | String | Start time to complete delivery | yyyy-MM-dd'T'HH:mm:ss |
completeEndTime | Mandatory | String | End time to complete delivery | 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 received number | Numbers without hyphens (-) |
pageIndex | Optional | Integer | Page number | default: 0 |
pageSize | Optional | Integer | Page size | default: 20, max: 100 When viewing including requestId, default: 100 |
Note
- History of delivering messages can only be viewed within the last 30 days.
- Either requestId or requestStartTime + requestEndTime or completeStartTime + completeEndTime is required.
- requestStartTime + requestEndTime and completeStartTime + completeEndTime cannot be used simultaneously.
- The query range from requestStartTime to requestEndTime is limited to a maximum of 31 days.
- The query range from completeStartTime to completeEndTime is limited to a maximum of 24 hours.
- If requestId is not included in the query conditions, plusFriendId is required.
Headers
Request Body
N/A
Response bodies
{
"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",
"pageIndex": "integer",
"itemCount": "integer",
"hasMore": "boolean"
}
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
requestId | Optional | String | Delivery request ID | Only exposed when you query with requestId |
statusCode | Mandatory | String | Request status code | 202 - Success Others - Failed * Follows the HTTP Status specifications. |
statusName | Mandatory | String | Request status name | success - Success processing - Being delivered reserved - Being reserved fail - Failed |
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's country code | default: 82 |
messages.to | Mandatory | String | Recipient's number | |
messages.content | Mandatory | String | AlimTalk message content | |
messages.plusFriendId | Mandatory | String | Name of KakaoTalk 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 - Failed (reason for failure specified in the Desc category) |
messages.requestStatusName | Mandatory | String | Delivery request status name | success - Success fail - Failed |
messages.requestStatusDesc | Mandatory | String | Delivery request status content | |
messages.messageStatusCode | Mandatory | String | Delivery result status code | 0000 - Success Other codes - Failed (reason for failure specified in the Desc category) |
messages.messageStatusName | Mandatory | String | Delivery result status name | success - Success processing - Being processed * Being processed in the message delivery server after successful sending request * Fail to search messageCode, messageDesc fail - Failed |
messages.messageStatusDesc | Mandatory | String | Delivery result status description | |
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 Errors table. |
messages.failover.requestStatusName | Optional | String | SMS Failover delivery request status name | success - Success fail - Failed |
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 Errors 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 | |
pageIndex | Mandatory | Integer | Page index (starting from 0) | |
itemCount | Mandatory | Integer | The number of messages within the viewed page | |
hasMore | Mandatory | Boolean | Indicates whether there is a next page |
Note
- If requestId is not included in the query condition, requestId is not included.
Response status
HTTP Status | Desc |
---|---|
200 | OK (successfully searched) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
Search for message delivery result
Search for 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
Item | 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
N/A
Response bodies
{
"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"
}
}
Item | 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 KakaoTalk Channel ((formerly) Plus Friend ID) | |
templateCode | Mandatory | String | Template code | |
countryCode | Optional | String | Recipient's country code | default: 82 |
to | Mandatory | String | Recipient's number | |
content | Mandatory | String | AlimTalk message content | |
requestStatusCode | Mandatory | String | Delivery request status code | A000 - Success Other codes - Failed (reason for failure specified in the Desc category) |
requestStatusName | Mandatory | String | Delivery request status name | success - Success fail - Failed |
requestStatusDesc | Mandatory | String | Delivery request status content | |
messageStatusCode | Mandatory | String | Delivery result status code | 0000 - Success Other codes - Failed (reason for failure specified in the Desc category) |
messageStatusName | Mandatory | String | Delivery result status name | success - Success processing - Being processed * Being processed in the message delivery server after successful sending request * Fail to search messageCode, messageDesc fail - Failed |
messageStatusDesc | Mandatory | String | Delivery result status description | |
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 Errors table. |
messages.failover.requestStatusName | Optional | String | SMS Failover delivery request status name | success - Success fail - Failed |
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 Errors 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 | Failover setting is not valid. |
E4001 | Failover settings information is omitted. |
E4002 | Failover SMS service is not configured. |
E4003 | Failover SMS type (SMS, LMS) is not configured. |
E4004 | Failover SMS caller ID is not configured. |
E4005 | Failover SMS title is not configured. |
E4006 | Failover SMS content is not set. |
E4007 | Failover SMS recipient number is not set. |
E4008 | Failover SMS service is not available. |
E4009 | Failover SMS caller ID is not authenticated. |
E4010 | Failover SMS free 080 unsubscribing service is not available. |
E4999 | Failover settings parsing error (need to contact Customer Support) |
E5000 | Internal error (need to contact Customer Support) |
Response status
HTTP Status | Desc |
---|---|
200 | OK (successfully searched) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
Reserved message
Search for reserved message status
Search for 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
Item | 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 for the reserved delivery requests (requestId) |
Headers
Request Body
N/A
Response bodies
{
"reserveId": "string",
"reserveTimeZone": "string",
"reserveTime": "string",
"reserveStatus": "string"
}
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
reserveId | Mandatory | String | Reserved message ID | Message identifier that is returned when searching for 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 | Reserved status | - Waiting to be sent: READY - Requesting to send: PROCESSING - Delivery canceled: CANCELED - Delivery request Failed: FAIL - Successful delivery request: DONE - Delivery request Failed (timeout): STALE |
Response status
HTTP Status | Desc |
---|---|
200 | OK (successfully searched) |
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
Item | 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 for the reserved delivery requests (requestId) |
Headers
Request Body
N/A
Response bodies
N/A
Response status
HTTP Status | Desc |
---|---|
204 | No Content (successfully deleted) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
KakaoTalk Channel
Search Channel
Search KakaoTalk 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
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
serviceId | Mandatory | String | Service ID | Service ID issued when registering the project |
Parameters
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
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
N/A
Response bodies
[
{
"createTime": "string",
"updateTime": "string",
"serviceId": "string",
"channelId": "string",
"channelName": "string",
"channelStatus": "string",
"useSmsFailover": "boolean",
"failoverServiceId": "string",
"failoverTelNo": "string",
"isBlock": "boolean",
"isDormant": "boolean"
}
]
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
createTime | Mandatory | String | Created 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 | KakaoTalk Channel ID | |
channelName | Mandatory | String | KakaoTalk Channel name | |
channelStatus | Mandatory | String | KakaoTalk 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 block status | |
isDormant | Mandatory | Boolean | Whether Channel is switched to dormant 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 |
AlimTalk template
Search template
This searches AlimTalk templates registered in the KakaoTalk 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
Item | 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 detailed information of the template when using templateCode.
- Additional information, including comments, is only exposed during detailed inquiry.
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
channelId | Mandatory | String | Channel ID | Channel ID registered to KakaoTalk |
templateCode | Mandatory | String | Template code | 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
N/A
Response bodies
[
{
"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"
}
]
Item | Mandatory | Type | Description | Remarks |
---|---|---|---|---|
createTime | Mandatory | String | Created time | format: LocalDateTime |
updateTime | Optional | String | Edited time | format: LocalDateTime |
channelId | Mandatory | String | KakaoTalk 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: default type - EX: additional information type - AD: ad addition type - MI: hybrid type |
emphasizeType | Mandatory | String | Template highlighting type | - NONE: default 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 - In inspection: INSPECT - Completed: COMPLETE - Rejected: REJECT |
templateStatus | Mandatory | String | Template status | - Normal: ACTIVE - Ready: READY - Stopped: STOP |
buttons | Optional | Array of Object | AlimTalk 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 link button | See the registered template button information. |
buttons.linkPc | Optional | String | PC link button | See the registered template button information. |
buttons.schemeIos | Optional | String | iOS scheme button | See the registered template button information. |
buttons.schemeAndroid | Optional | String | Android scheme button | 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 status | |
useItemHighlightImage | Mandatory | Boolean | Item highlight image usage status | |
itemHighlight | Optional | Object | Item highlight | Only exposed when item highlight is used |
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 | Only exposed when item is used |
item.list | Optional | String | Item list | Only exposed when item list is used |
item.list.title | Optional | String | Item name | |
item.list.description | Optional | String | Item content | |
item.summary | Optional | String | Item summary information | Only exposed when item summary information is used |
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 block status | |
isDormant | Mandatory | Boolean | Whether template is switched to dormant status |
Note
- channelId is a required value, and it returns the detailed information of the template when using templateCode.
- Additional information, including comments, is only exposed during detailed inquiry.
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
AlimTalk 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 | Outgoing profile key is invalid. |
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 formatted 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 KakaoTalk Channel (check in KakaoTalk Channel operation tool.) |
1022 | DeactivatedProfile | Closed KakaoTalk Channel (check in KakaoTalk Channel operation tool.) |
1023 | DeletedProfile | Deleted KakaoTalk Channel (check in KakaoTalk Channel operation tool.) |
1024 | DeletingProfile | Deletion pending KakaoTalk Channel (check in KakaoTalk Channel operation tool.) |
1025 | SpammedProfile | Message blocked KakaoTalk Channel (check in KakaoTalk Channel operation tool.) |
1026 | UnableUseMessageType | The request was made with response_method unavailable for the msg_type. (Image AlimTalk (AI) cannot be sent in real time.) |
1030 | InvalidParameterException | Invalid parameter request |
1033 | - | Template type and message type mismatched |
2003 | FailedToSendMessageByNoFriendshipException | Message transmission Failed (if KakaoTalk Channel is not added in the test server) |
2004 | FailedToMatchTemplateException | Error when checking template match (Kakao internal error) |
2006 | FailedToMatchSerialNumberPrefixPattern | Serial number format mismatch |
3000 | UnexceptedExcetpion | An unexpected error occurred. |
3005 | AckTimeoutException | A message was sent but the read receipt was not confirmed. (success uncertain) |
3006 | FailedToSendMessageException | Message transmission 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 (text type exceeds 1000 characters, image type exceeds 400 characters.) |
3015 | TemplateNotFoundException | Template not found |
3016 | NoMatchedTemplateException | Message content does not match the template. |
3018 | NoSendAvailableException | Message could not be sent. |
3020 | SeenInfoNotFoundException | Message verification information not found |
3022 | NoSendAvailableTimeException | Outside the time available for sending messages (FriendTalk/marketing messages can be sent from 08:00 to 20:00.) |
3024 | MessageInvaildImageException | The image contained in the message cannot be sent. |
3025 | ExceedMaxVariableLengthException | Variable character limit exceeded |
3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | Consultation/bot conversion 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 in case of no images, 21 characters in case there are images) |
3035 | ExceedMaxItemHighlightDescriptionLengthException | Item highlight description length limit exceeded (19 characters without 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 template |
3039 | ExceedMaxItemSummaryDescriptionLengthException | Item summary information's description length limit exceeded (14 characters) |
3040 | InvalidItemSummaryDescriptionException | Item summary information's description includes disallowed characters. (characters other than currency sign/code, number, comma, period, and space included.) |
4000 | ResponseHistoryNotFoundException | Message delivery result not found |
4001 | UnKnownMessageStatusError | Unknown message status |
7011 | - | Serial number pattern error |
7014 | - | Message valid timeout error |
8512 | - | Recipient type not found |
8514 | - | request_id not found |
8520 | - | Merchandise type not supported 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. | Admin is checking a problem that occurred in the system. |
9999 | Admin is checking an unknown problem that occurred in the system. | Admin is checking a problem that occurred in the system. |
B000 | Prepare to relay failed | Preparation for transmission to relay company failed |
B001 | Request to relay failed | Transmission to relay company failed |
B002 | Filtering for request to relay failed | Filtered due to invalid request |
B003 | Invalid phone number format | Invalid calling number format |
B004 | Quota Exceed | Over quota |
B005 | Message processing timeout exceed | Difference between message request time and processing time exceeds acceptable range |
B400 | Invalid Request | Message format error |
B999 | Unexpected server error | Unexpected error |
Was this article helpful?