Classic/VPC環境で利用できます。
通知トークメッセージの送信結果を照会します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| GET | /alimtalk/v2/services/{serviceId}/messages/{messageId} |
リクエストヘッダ
Simple & Easy Notification Service APIで共通して使用されるヘッダの詳細は、Simple & Easy Notification Serviceのリクエストヘッダをご参照ください。
リクエストパスパラメータ
リクエストパスパラメータの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
serviceId |
String | Required | Biz Messageサービス ID
|
messageId |
String | Required | メッセージ ID |
リクエスト例
リクエストのサンプルコードは次の通りです。
curl --location --request GET 'https://sens.apigw.ntruss.com/alimtalk/v2/services/ncp:kkobizmsg:kr:27*********6:sens/messages/aa724ca6-****-****-****-66dfc1a700e7' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
requestId |
String | Required | リクエスト ID |
messageId |
String | Required | メッセージ ID |
requestTime |
String | Required | リクエスト日時
|
completeTime |
String | Optional | 完了日時
|
plusFriendId |
String | Required | チャンネル ID |
templateCode |
String | Required | テンプレートコード |
countryCode |
String | Optional | 国コード |
to |
String | Required | 受信番号 |
content |
String | Required | メッセージの内容 |
requestStatusCode |
String | Required | リクエストの状態コード
|
requestStatusName |
String | Required | リクエスト状態
|
requestStatusDesc |
String | Required | リクエスト状態の説明 |
messageStatusCode |
String | Optional | 受信状態コード
|
messageStatusName |
String | Optional | 受信状態
|
messageStatusDesc |
String | Optional | 受信状態の説明 |
useSmsFailover |
Boolean | Required | SMS代替送信を使用するか
|
failover |
Object | Optional | SMS代替送信情報
|
failover.smsServiceId |
String | Optional | 代替送信に使用された SMSサービス ID |
failover.requestId |
String | Optional | 代替送信リクエスト ID |
failover.messageId |
String | Optional | 代替送信メッセージ ID |
failover.requestStatusCode |
String | Optional | SMS代替送信リクエストの状態コード |
failover.requestStatusName |
String | Optional | 代替送信のリクエスト状態
|
failover.requestStatusDesc |
String | Optional | 代替送信リクエスト状態の説明 |
failover.messageStatus |
String | Optional | 代替送信メッセージの状態
|
failover.messageStatusCode |
String | Optional | 代替送信メッセージの受信状態コード
|
failover.messageStatusName |
String | Optional | 代替送信メッセージの受信状態 |
failover.messageStatusDesc |
String | Optional | 代替送信メッセージ受信状態の説明 |
レスポンスステータスコード
Simple & Easy Notification Service APIで共通して使用されるレスポンスステータスコードの詳細は、Simple & Easy Notification Serviceのレスポンスステータスコードをご参照ください。
レスポンス例
レスポンスのサンプルコードは次の通りです。
{
"requestId": "RBAA-*************-****-********-zgrtzVEW",
"messageId": "aa724ca6-****-****-****-66dfc1a700e7",
"requestTime": "2025-11-25T15:39:20.899",
"completeTime": "2025-11-25T15:39:21",
"plusFriendId": "@******",
"templateCode": "temp001",
"countryCode": "82",
"to": "010********",
"content": "ホンギルドン様、\nご依頼の[PO394857]翻訳文書を本日18:00にメールでお送りする予定です。\n\nメール送信後、お知らせいたします。\n今しばらくお待ちください。",
"requestStatusCode": "A000",
"requestStatusName": "success",
"requestStatusDesc": "成功",
"messageStatusCode": "0000",
"messageStatusName": "success",
"messageStatusDesc": "正常に送信",
"useSmsFailover": true
}
受信結果コード
通知トーク/ブランドメッセージの受信結果コードは次の通りです。
参考
SMS代替送信機能は、Biz Message受信結果コードに基づいて成功しなかった場合に動作し、「B」接頭辞が付いたコードの場合は動作しません。
| コード | メッセージ | 説明 |
|---|---|---|
| 0000 | - | 正常に送信 |
| 1001 | NoJsonBody | リクエストボディが JSON形式ではない |
| 1002 | InvalidHubPartnerKey | パートナーキーが有効ではない |
| 1003 | InvalidSenderKey | 送信プロファイルキーが有効ではない |
| 1004 | NoValueJsonElement | リクエストボディ(JSON)で nameが見つからない |
| 1005 | SenderNotFound | 送信プロファイルが見つからない |
| 1006 | DeletedSender | 削除された送信プロファイル |
| 1007 | StoppedSender | ブロック状態の送信プロファイル |
| 1011 | ContractNotFound | 契約情報が見つからない |
| 1012 | InvalidUserKeyException | 正しくない形式のユーザーキーリクエスト |
| 1013 | InvalidAppLink | 無効なアプリリンク |
| 1014 | InvalidBizNum | 無効な事業者番号 |
| 1015 | TalkUserIdNotFonud | 無効なアプリユーザー IDリクエスト |
| 1016 | BizNumNotEqual | 事業者登録番号が一致しない |
| 1020 | InvalidReceiveUserException | ユーザー識別値がすべて無効 |
| 1021 | BlockedProfile | カカオトークチャンネルがブロックされている(カカオトークチャンネル運用ツールで確認) |
| 1022 | DeactivatedProfile | カカオトークチャンネルが停止状態(カカオトークチャンネル運用ツールで確認) |
| 1023 | DeletedProfile | カカオトークチャンネルが削除される(カカオトークチャンネル運用ツールで確認) |
| 1024 | DeletingProfile | カカオトークチャンネルが削除待ち(カカオトークチャンネル運用ツールで確認) |
| 1025 | SpammedProfile | カカオトークチャンネルがメッセージブロック状態(カカオトークチャンネル運用ツールで確認) |
| 1026 | UnableUseMessageType | msg_typeで使用できないメソッドでリクエスト(画像通知トーク(AI)はリアルタイムで送信不可) |
| 1027 | - | チャンネルメッセージ制裁状態によるメッセージ送信失敗 |
| 1030 | InvalidParameterException | 正しくないパラメータリクエスト |
| 1033 | - | テンプレートタイプとメッセージタイプが一致しない |
| 2000 | FailedToCheckFriendshipException | トークチャンネルとの友達関係確認時のエラー(システムエラー) |
| 2003 | FailedToSendMessageByNoFriendshipException | メッセージの送信失敗 (テストサーバでカカオトークチャンネルを追加していない場合) |
| 2004 | FailedToMatchTemplateException | テンプレートと一致してるかどうかを確認中にエラー発生 (カカオトークの内部エラー) |
| 2005 | FailedToReadImageException | カカオから画像のメタ情報を読み込み中にエラー |
| 2006 | FailedToMatchSerialNumberPrefixPattern | シリアル番号形式の不一致 |
| 3000 | UnexceptedExcetpion | 予期せぬエラーの発生 |
| 3005 | AckTimeoutException | メッセージを送信したが、受信が確認できてない(成否が不明) |
| 3006 | FailedToSendMessageException | カカオトーク内部システムエラーによるメッセージ送信失敗 |
| 3008 | InvalidPhoneNumberException | 電話番号エラー |
| 3010 | JsonParseException | JSONパースエラー |
| 3011 | MessageNotFoundException | メッセージが存在しない |
| 3012 | SerialNumberDuplicatedException | メッセージのシリアル番号が重複している(メッセージのシリアル番号は固有の値でなければならない) |
| 3013 | MessageEmptyException | 空のメッセージ |
| 3014 | MessageLengthOverLimitException | メッセージの長さ制限エラー(テキストタイプ1,000文字を超過、画像タイプ400文字を超過) |
| 3015 | TemplateNotFoundException | テンプレートが見つからない |
| 3016 | NoMatchedTemplateException | メッセージ内容がテンプレートと一致しない |
| 3018 | NoSendAvailableException | メッセージを送信できない |
| 3019 | MessageNoUserException | トークのユーザーではない |
| 3020 | MessageUserBlockedAlimTalkException | 通知トークブロック |
| 3021 | MessageNotSupportedKakaotalkException | トークの最低バージョンをサポートしない |
| 3022 | NoSendAvailableTimeException | メッセージが送信可能な時間ではない(友達トーク/マーケティングメッセージは8時~20時まで送信可能) |
| 3023 | MessageInvalidVideoException | メッセージに含まれているビデオを送信できない(ビデオのアドレスまたはサムネイル画像アドレスが正しくないか、サムネイル画像が規格に合わない) |
| 3024 | MessageInvalidImageException | メッセージに含まれた画像を送信できない |
| 3025 | ExceedMaxVariableLengthException | 変数の文字数制限を超過 |
| 3026 | Button chat_extra(event)-InvalidExtra(EventName)Exception '([A-Za-z0-9_]{1,50})' | 相談/ボット切り替えボタン extra、event文字数の制限を超過 |
| 3027 | NoMatchedTemplateButtonException | ボタンの内容がテンプレートと一致しない |
| 3028 | NoMatchedTemplateTitleException | メッセージの強調表記件名がテンプレートと一致しない |
| 3029 | ExceedMaxTitleLengthException | メッセージの強調表記件名の長さが制限を超過(50文字) |
| 3030 | NoMatchedTemplateWithMessageTypeException | メッセージタイプとテンプレートの強調タイプが一致しない |
| 3031 | NoMatchedTemplateHeaderException | ヘッダがテンプレートと一致しない |
| 3032 | ExceedMaxHeaderLengthException | ヘッダの長さ制限を超過(16文字) |
| 3033 | NoMatchedTemplateItemHighlightException | アイテムハイライトがテンプレートと一致しない |
| 3034 | ExceedMaxItemHighlightTitleLengthException | アイテムハイライト件名の長さが制限を超過 (画像がない場合は30文字、画像がある場合は21文字) |
| 3035 | ExceedMaxItemHighlightDescriptionLengthException | アイテムハイライト説明の長さが制限を超過 (画像がない場合は19文字、画像がある場合は14文字) |
| 3036 | NoMatchedTemplateItemListException | アイテムリストがテンプレートと一致しない |
| 3037 | ExceedMaxItemDescriptionLengthException | アイテムリストのアイテム説明の長さが制限を超過 (23文字) |
| 3038 | NoMatchedTemplateItemSummaryException | アイテムのサマリー情報がテンプレートと一致しない |
| 3039 | ExceedMaxItemSummaryDescriptionLengthException | アイテムサマリー情報の長さが制限を超過 (14文字) |
| 3040 | InvalidItemSummaryDescriptionException | アイテムのサマリー情報が無効な文字を含む (通貨記号/コード、数字、コンマ、小数点、スペース以外の文字を含む) |
| 3041 | MessageInvalidWideItemListLengthException | ワイドアイテムリスト数の最小値と最大値が一致しない |
| 3042 | NoMatchedTemplateRepresentLinkException | 代表リンクがテンプレートと一致しない |
| 3046 | ExceedMaxAdditionalContentLengthException | 付加情報の最大長さ制限エラー |
| 3047 | ExceedMaxCommerceTitleLengthException | コマース情報、商品名の最大長さ制限エラー |
| 3050 | MessageNotSupportedUnsubscribeException | 受信同意拒否スペック(Nタイプ)をサポートしない |
| 3051 | InvalidateCarouselItemMinException or InvalidateCarouselItemMaxException | カルーセルアイテムリスト数の最小値と最大値が一致しない |
| 3052 | CarouselMessageLengthOverLimitException | カルーセルアイテムメッセージが長さ制限を超過 |
| 3056 | WideItemListTitleLengthOverLimitException | ワイドアイテムリストタイトルの長さ制限エラー |
| 3058 | CarouselHeaderLengthOverLimitException | カルーセルヘッダの長さ制限エラー |
| 3059 | MessageNotSupportedCouponException | クーポンのスペックをサポートしない |
| 4000 | ResponseHistoryNotFoundException | メッセージ送信結果が見つからない |
| 4001 | UnKnownMessageStatusError | 不明なメッセージ状態 |
| 7011 | - | シリアル番号パターンのエラー |
| 7014 | - | メッセージ有効時間オーバーのエラー |
| 8512 | - | 受信者タイプが見つからない |
| 8514 | - | request_idが見つからない |
| 8520 | - | サポートしない商品タイプエラー |
| 8521 | - | サポートしないメッセージタイプエラー |
| 8522 | - | サポートしないテキストタイプエラー |
| 8523 | - | サポートしない response methodエラー |
| 8530 | - | 受信者リストサイズエラー |
| 8999 | - | 内部サーバエラー |
| 9998 | 現在サービスを提供していません。 | システムにトラブルが発生し、担当者が確認中 |
| 9999 | システムに原因不明のトラブルが発生し、担当者が確認中 | システムにトラブルが発生し、担当者が確認中 |
| B000 | Prepare to relay failed | 中継会社への送信のための事前作業に失敗 |
| B001 | Request to relay failed | 中継会社への送信失敗 |
| B002 | Filtering for request to relay failed | 無効なリクエストによりフィルタリングされる |
| B003 | Invalid phone number format | 無効な送信番号形式 |
| B004 | Quota Exceed | クォーター超過 |
| B005 | Message processing timeout exceed | メッセージのリクエスト時間と処理時間の差が許容範囲外である |
| B400 | Invalid Request | メッセージ形式エラー |
| B999 | Unexpected server error | 予期せぬエラー |
SMS代替送信リクエストの状態コード
Biz Messageの送信に失敗した場合、SMSによる代替送信をリクエストした際に返される状態コードです。
参考
SMS代替送信機能は、Biz Message受信結果コードに基づいて成功しなかった場合に動作し、「B」接頭辞が付いたコードの場合は動作しません。
| コード | 説明 |
|---|---|
| 0 | 成功 |
| E4000 | 無効な SMS代替送信設定 |
| E4001 | SMS代替送信設定情報が欠落している |
| E4002 | SMS代替送信サービスが設定されていない |
| E4003 | SMS代替送信タイプ(SMS、LMS)が設定されていない |
| E4004 | SMS代替送信の送信番号が設定されていない |
| E4005 | SMS代替送信のメッセージ件名が設定されていない |
| E4006 | SMS代替送信のメッセージ内容が設定されていない |
| E4007 | SMS代替送信のメッセージ受信番号が設定されていない |
| E4008 | SMS代替送信サービスが使用可能な状態ではない |
| E4009 | SMS代替送信の送信番号が認証されていない |
| E4010 | SMS代替送信の080無料受信拒否サービスが使用可能な状態ではない |
| E4999 | SMS代替送信設定のパースエラー(サポートに要相談) |
| E5000 | 内部エラー(サポートセンターに要相談) |