ブランドメッセージ API

Prev Next

基本情報

API URL

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

SENSブランドメッセージ API Swaggerへ

API Header

項目 Mandatory 説明
Content-Type Mandatory リクエスト Body Content Typeを application/jsonに指定(POST)
x-ncp-apigw-timestamp Mandatory 1970年1月1日 00:00:00 協定世界時(UTC)からの経過時間をミリ秒(Millisecond)で表したもの
API Gatewayサーバとの時間差が5分以上の場合は無効なリクエストとみなす
x-ncp-iam-access-key Mandatory ポータルまたは Sub Accountが発行した Access Key ID
x-ncp-apigw-signature-v2 Mandatory 上記例の Bodyを Access Key IDとマッピングする SecretKeyで暗号化した署名
HMAC暗号化アルゴリズムは、HmacSHA256を使用

NAVERクラウドプラットフォームの認証キーおよび Signature作成ガイドへ

メッセージ送信の基本情報

基本情報

  • SMS Failoverはまだサポートしていません (2026年1Qにサポート予定)。
  • 予約送信はまだサポートしていません (2026年1Qにサポート予定)。

リクエスト URL

POST https://sens.apigw.ntruss.com/brandmessage/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

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID

Headers

API Headerへ

リクエストボディ

メッセージの送信(自由型)、メッセージの送信(基本型)ガイドを参照

レスポンスボディ

{
    "requestId":"string",
    "requestTime":"string",
    "statusCode":"string",
    "statusName":"string",
    "messages":[
        {
            "messageId":"string",
            "countryCode":"string",
            "to":"string",
            "requestStatusCode":"string",
            "requestStatusName":"string",
            "requestStatusDesc":"string",
            "useSmsFailover":"boolean"
        }
    ]
}
項目 Mandatory Type 説明 備考
requestId Mandatory String 送信リクエスト ID
requestTime Mandatory DateTime 送信リクエスト時間 yyyy-MM-dd'T'HH:mm:ss.SSS
statusCode Mandatory String リクエスト状態コード 202 - 成功
その他 - 失敗
* HTTP Status規格に従う
statusName Mandatory String リクエスト状態名 success - 成功
processing - 処理中
reserved - 予約中
fail - 失敗
messages.messageId Mandatory String メッセージ ID
messages.countryCode Optional String 受信者の国番号 デフォルト: 82
messages.to Mandatory String 受信者番号
messages.requestStatusCode Mandatory String 送信リクエスト状態コード A000 - 成功
その他のコード - 失敗(Desc項目に失敗理由が明示される)
messages.requestStatusName Mandatory String 送信リクエスト状態名 success - 成功
fail - 失敗
messages.requestStatusDesc Mandatory String 送信リクエスト状態の内容
messages.useSmsFailover Mandatory Boolean SMS Failover使用の有無

レスポンスステータス

HTTP Status Desc
202 Accepted(送信リクエスト完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

メッセージの送信 (自由型)

  • ターゲティングコードを指定することで、メッセージ送信対象のタイプを指定できます。
    • M: 顧客の情報提供型広告の受信に同意したユーザー(カカオトーク受信同意)
    • N: 顧客の情報提供型広告の受信に同意したユーザー(カカオトーク受信同意) - チャンネル友達
    • I: 顧客の送信リクエスト対象 ∩ チャンネル友達
  • ブランドメッセージのお申し込みが完了したチャンネルに限り、ターゲティングコード M、N送信を利用できます。
  • ターゲティングコード M、Nで送信する際は、チャンネルに指定された080無料受信拒否番号を使用します。
  • ACボタンは利用できません。
  • 夜間の送信制限が適用されます (20:50 ~ 翌日08:00)。

テキスト型(TEXT)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ テキスト型(TEXT)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].content Mandatory String 最大1,300文字
改行は最大99個
messages[].buttons Optional List of Object ボタン情報 クーポン使用時は最大4個、その他は最大5個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大14文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional

画像型(IMAGE)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ 画像型(IMAGE)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].content Mandatory String 最大1,300文字
改行は最大99個
messages[].buttons Optional List of Object ボタン情報 クーポン使用時は最大4個、その他は最大5個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大14文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].image Optional Object 画像 画像のアップロードを参照
messages[].image.imageId Mandatory String 画像 ID
messages[].image.imageLink Mandatory String 画像リンク
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional

ワイド画像型(WIDE_IMAGE)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ ワイド画像型(WIDE_IMAGE)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].content Mandatory String 最大1,300文字
改行は最大99個
messages[].buttons Optional List of Object ボタン情報 最大2個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].image Optional Object 画像 画像のアップロードを参照
messages[].image.imageId Mandatory String 画像 ID
messages[].image.imageLink Mandatory String 画像リンク
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional

ワイドアイテムリスト型(WIDE_ITEM_LIST)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "headerContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "item":[
                {
                    "title":"string",
                    "imageId":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ ワイドアイテムリスト型(WIDE_ITEM_LIST)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].headerContent Mandatory String ヘッダ 最大20文字
messages[].buttons Optional List of Object ボタン情報 最大2個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].item Mandatory Object
messages[].item.list Mandatory List of Object ワイドリスト 最小3個、最大4個
messages[].item.list[].title Mandatory String アイテムのタイトル 1番目のアイテム
- Optional
- 最大25文字
- 改行は最大1個
2~4番目のアイテム
- 最大30文字
- 改行は最大1個
messages[].item.list[].imageId Mandatory String 画像 ID 1番目のアイテム
- メインワイドアイテムリスト画像
2~4番目のアイテム
- サブワイドアイテムリスト画像
messages[].item.list[].linkMobile Mandatory String モバイルウェブリンク 最大1,000文字
messages[].item.list[].linPc Optional String PCウェブリンク 最大1,000文字
messages[].item.list[].schemeAndroid Optional String Androidアプリリンク 最大1,000文字
messages[].item.list[].schemeIos Optional String iOSアプリリンク 最大1,000文字

コマース型(COMMERCE)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "additionalContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "image":{
                "imageId":"string",
                "imageLink":"string"
            },
            "commerce": {
                "title":"string",
                "regularPrice":"integer",
                "discountPrice":"integer",
                "discountRate":"integer",
                "discountFixed":"integer"
            },
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ コマース型(COMMERCE)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].additionalContent Optional String 付加情報 最大34文字
改行は最大1個
messages[].buttons Mandatory List of Object ボタン情報 最小1個、最大2個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].image Optional Object 画像 画像のアップロードを参照
messages[].image.imageId Mandatory String 画像 ID
messages[].image.imageLink Mandatory String 画像リンク
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].commerce Mandatory Object コマース情報
messages[].commerce.title Mandatory String 商品のタイトル 最大30文字
messages[].commerce.regularPrice Mandatory Integer 商品の通常価格 0 ~ 99,999,999
messages[].commerce.discountPrice Optional Integer 商品の割引価格 0 ~ 99,999,999
messages[].commerce.discountRate Optional Integer 商品割引率 0 ~ 100
割引価格使用時、定額割引価格または商品割引率のいずれか一方は Mandatory
messages[].commerce.discountFixed Optional Integer 商品の定額割引価格 0 ~ 999,999
割引価格使用時、定額割引価格または商品割引率のいずれか一方は Mandatory

カルーセルコマース型(CAROUSEL_COMMERCE)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "carousel": {
                "head": {
                    "headerContent":"string",
                    "content":"string",
                    "imageId":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                },
                "list": [
                    {
                        "additionalContent":"string",
                        "image":{
                            "imageId":"string",
                            "imageLink":"string"
                        },
                        "buttons":[
                            {
                                "type":"string",
                                "name":"string",
                                "linkMobile":"string",
                                "linkPc":"string",
                                "schemeAndroid":"string",
                                "schemeIos":"string",
                                "bizFormId":"string"
                            }
                        ],
                        "coupon": {
                            "title":"string",
                            "description":"string",
                            "linkMobile":"string",
                            "linkPc":"string",
                            "schemeAndroid":"string",
                            "schemeIos":"string"
                        },
                        "commerce": {
                            "title":"string",
                            "regularPrice":"integer",
                            "discountPrice":"integer",
                            "discountRate":"integer",
                            "discountFixed":"integer"
                        }
                    }
                ],
                "tail": {
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ カルーセルコマース型(CAROUSEL_COMMERCE)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].carousel Mandatory Object カルーセル情報
messages[].carousel.head Optional Object カルーセルイントロ情報
messages[].carousel.head.headerContent Mandatory String ヘッダ 最大20文字
messages[].carousel.head.content Mandatory String 内容 最大50文字
messages[].carousel.head.imageId Mandatory String 画像 ID CAROUSEL_COMMERCEタイプ画像のみ使用可能
カルーセルリスト画像と同じ比率にすること
messages[].carousel.head.linkMobile Optional String モバイルウェブリンク 最大1,000文字
schemeAndroidまたは schemeIos使用時、Mandatory
messages[].carousel.head.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].carousel.head.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
messages[].carousel.head.schemeIos Optional String iOSアプリリンク 最大1,000文字
messages[].carousel.list Mandatory List of Object カルーセルリスト カルーセルイントロ(head)を使用する場合、最小1個、最大5個
それ以外は最小2個、最大6個
messages[].carousel.list[].additionalContent Mandatory String カルーセルリストアイテムの付加情報 最大34文字
messages[].carousel.list[].image Mandatory Object カルーセルリストアイテム画像情報 画像のアップロードを参照
messages[].carousel.list[].image.imageId Mandatory String 画像 ID
messages[].carousel.list[].image.imageLink Mandatory String 画像リンク 最大1,000文字
messages[].carousel.list[].buttons Mandatory List of Object ボタン情報 最小1個、最大2個
messages[].carousel.list[].buttons[].type Mandatory String ボタン Type
messages[].carousel.list[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].carousel.list[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].carousel.list[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].bizFormId Optional String
messages[].carousel.list[].coupon Optional Object クーポン情報
messages[].carousel.list[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].carousel.list[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].carousel.list[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].carousel.list[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].carousel.list[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].carousel.list[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].carousel.list[].commerce Mandatory Object コマース情報
messages[].carousel.list[].commerce.title Mandatory String 商品のタイトル 最大30文字
messages[].carousel.list[].commerce.regularPrice Mandatory Integer 商品の通常価格 0 ~ 99,999,999
messages[].carousel.list[].commerce.discountPrice Optional Integer 商品の割引価格 0 ~ 99,999,999
messages[].carousel.list[].commerce.discountRate Optional Integer 商品割引率 0 ~ 100
割引価格使用時、定額割引価格または商品割引率のいずれか一方は Mandatory
messages[].carousel.list[].commerce.discountFixed Optional Integer 商品の定額割引価格 0 ~ 999,999
割引価格使用時、定額割引価格または商品割引率のいずれか一方は Mandatory
messages[].carousel.tail Optional Object カルーセルのもっと見る情報
messages[].carousel.tail.linkMobile Mandatory String モバイルウェブリンク 最大1,000文字
messages[].carousel.tail.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].carousel.tail.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
messages[].carousel.tail.schemeIos Optional String iOSアプリリンク 最大1,000文字

カルーセルフィード型(CAROUSEL_FEED)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "carousel": {
                "list": [
                    {
                        "headerContent":"string",
                        "message":"string",
                        "image":{
                            "imageId":"string",
                            "imageLink":"string"
                        },
                        "buttons":[
                            {
                                "type":"string",
                                "name":"string",
                                "linkMobile":"string",
                                "linkPc":"string",
                                "schemeAndroid":"string",
                                "schemeIos":"string",
                                "bizFormId":"string"
                            }
                        ],
                        "coupon": {
                            "title":"string",
                            "description":"string",
                            "linkMobile":"string",
                            "linkPc":"string",
                            "schemeAndroid":"string",
                            "schemeIos":"string"
                        }
                    }
                ],
                "tail": {
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeAndroid":"string",
                    "schemeIos":"string"
                }
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ カルーセルフィード型(CAROUSEL_FEED)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].carousel Mandatory Object カルーセル情報
messages[].carousel.list Mandatory List of Object カルーセルリスト 最小2個、最大6個
messages[].carousel.list[].headerContent Mandatory String カルーセルリストアイテムのタイトル 最大20文字
messages[].carousel.list[].message Mandatory String カルーセルリストアイテムのメッセージ 最大180文字
messages[].carousel.list[].image Mandatory Object カルーセルリストアイテム画像情報 画像のアップロードを参照
messages[].carousel.list[].image.imageId Mandatory String 画像 ID
messages[].carousel.list[].image.imageLink Mandatory String 画像リンク 最大1,000文字
messages[].carousel.list[].buttons Mandatory List of Object ボタン情報 最小1個、最大2個
messages[].carousel.list[].buttons[].type Mandatory String ボタン Type
messages[].carousel.list[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].carousel.list[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].carousel.list[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].carousel.list[].buttons[].bizFormId Optional String
messages[].carousel.list[].coupon Optional Object クーポン情報
messages[].carousel.list[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].carousel.list[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].carousel.list[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].carousel.list[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].carousel.list[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].carousel.list[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].carousel.tail Optional Object カルーセルのもっと見る情報
messages[].carousel.tail.linkMobile Mandatory String モバイルウェブリンク 最大1,000文字
messages[].carousel.tail.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].carousel.tail.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
messages[].carousel.tail.schemeIos Optional String iOSアプリリンク 最大1,000文字

プレミアム動画型(PREMIUM_VIDEO)の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "isAdult":"boolean",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "content":"string",
            "headerContent":"string",
            "buttons":[
                {
                    "type":"string",
                    "name":"string",
                    "linkMobile":"string",
                    "linkPc":"string",
                    "schemeIos":"string",
                    "schemeAndroid":"string",
                    "bizFormId":"string"
                }
            ],
            "coupon": {
                "title":"string",
                "description":"string",
                "linkMobile":"string",
                "linkPc":"string",
                "schemeAndroid":"string",
                "schemeIos":"string"
            },
            "video": {
                "thumbnailId":"string",
                "videoUrl":"string"
            }
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ プレミアム動画型(PREMIUM_VIDEO)
isAdult Optional Boolean 対象年齢 成人: true
全年齢: false (default)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].content Optional String 最大1,300文字
改行は最大99個
messages[].headerContent Optional String ヘッダ 最大20文字
messages[].buttons Optional List of Object ボタン情報 最大1個
messages[].buttons[].type Mandatory String ボタン Type
messages[].buttons[].name Mandatory String ボタン名 最大8文字
messages[].buttons[].linkMobile Optional String モバイルウェブリンク WLタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].linkPc Optional String PCウェブリンク WLタイプの場合、Optional
最大1,000文字
messages[].buttons[].schemeAndroid Optional String Androidアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].buttons[].schemeIos Optional String iOSアプリリンク ALタイプの場合、Mandatory
最大1,000文字
messages[].coupon Optional Object クーポン情報
messages[].coupon.title Mandatory String クーポンのタイトル 5つの形式のみ使用可能
- 以下の数字ウォンの割引クーポン{1 ~ 100の数字}%割引クーポン
- 送料割引クーポン
- 文字以内無料クーポン{7文字以内} UPクーポン
messages[].coupon.description Mandatory String クーポンの詳細説明 最大18文字
messages[].coupon.linkMobile Optional String モバイルウェブリンク 最大1,000文字
linkMobileフィールドを使用する場合、残りのフィールドは Optional
messages[].coupon.linkPc Optional String PCウェブリンク 最大1,000文字
messages[].coupon.schemeAndroid Optional String Androidアプリリンク 最大1,000文字
schemeAndroidフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].coupon.schemeIos Optional String iOSアプリリンク 最大1,000文字
schemeIosフィールドにチャンネルクーポン URL(形式: alimtalk=coupon://)を使用する場合、残りのフィールドは Optional
messages[].video Mandatory Object 動画情報
messages[].video.thumbnailId Mandatory String 動画サムネイル用画像 ID 最大500文字
messages[].video.videoUrl Mandatory String カカオ TV動画 URL 最大500文字
カカオ TVにアップロードされた動画のみ使用可能

ボタン情報

Type Name Mandatory 備考
WL ウェブリンク linkMobile http://または https://で始まる URL
AL アプリリンク linkMobile、schemeIos、schemeAndroidのうち2個
BF ビジネスフォーム bizFormId ボタン名(name)には5つの形式のみ使用可能
- トークでアンケート
- トークで応募
- トークで予約
TEXT、IMAGEテンプレートの場合は最初のボタン、それ以外は最後のボタンとしてのみ使用可能
ACボタンと併用する場合、ACの順序が優先される (AC -> BFまたは BF -> AC)
最大1個のみ使用可能
AC チャンネルの追加
BK ボットキーワード
MD メッセージの伝達
BC 相談トークに切り替え 相談トークを利用するチャンネルのみ使用可能
BT チャットボットに切り替え カカオオープンビルダーのチャットボットを利用するチャンネルのみ使用可能

メッセージの送信 (基本型)

  • テンプレートを使用した送信です。
  • ターゲティングコードを指定することで、メッセージ送信対象のタイプを指定できます。
    • M: 顧客の情報提供型広告の受信に同意したユーザー(カカオトーク受信同意)
    • N: 顧客の情報提供型広告の受信に同意したユーザー(カカオトーク受信同意) - チャンネル友達
    • I: 顧客の送信リクエスト対象 ∩ チャンネル友達
  • ブランドメッセージのお申し込みが完了したチャンネルに限り、ターゲティングコード M、N送信を利用できます。
  • ターゲティングコード M、Nで送信する際は、チャンネルに指定された080無料受信拒否番号を使用します。
  • BC、BTボタンは利用できません。
  • 夜間の送信制限が適用されます (20:50 ~ 翌日08:00)。

基本型の送信

リクエストボディ

{
    "plusFriendId":"string",
    "messageType":"string",
    "templateCode":"string",
    "targeting":"string",
    "messages":[
        {
            "countryCode":"string",
            "to":"string",
            "templateParameters": "object"
        }
    ]
}
項目 Mandatory Type 説明 備考
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ テキスト型(TEXT)
画像型(IMAGE)
ワイド画像型(WIDE_IMAGE)
ワイドアイテムリスト型(WIDE_ITEM_LIST)
カルーセルフィード型(CAROUSEL_FEED)
カルーセルコマース型(CAROUSEL_COMMERCE)
コマース型(COMMERCE)
プレミアム動画型(PREMIUM_VIDEO)
templateCode Mandatory String テンプレートコード
targeting Optional String ターゲティングタイプ M
N
I (defaut)
messages Mandatory List of Object メッセージ情報 以下の項目を参照(messages.XXX)
最大100個
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].to Mandatory String 受信者番号
messages[].templateParameters Optional Object テンプレートパラメータ テンプレートに置換変数を含める場合、Mandatory

メッセージの照会

送信リクエストの照会

メッセージの送信リクエストを照会します。

リクエスト URL

GET https://sens.apigw.ntruss.com/brandmessage/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

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID

Parameters

項目 Mandatory Type 説明 備考
requestId Mandatory String リクエスト ID 送信リクエスト ID
plusFriendId Mandatory String カカオチャンネル 登録されたチャンネル名
messageType Optional String メッセージタイプ テキスト型(TEXT)
画像型(IMAGE)
ワイド画像型(WIDE_IMAGE)
ワイドアイテムリスト型(WIDE_ITEM_LIST)
カルーセルフィード型(CAROUSEL_FEED)
カルーセルコマース型(CAROUSEL_COMMERCE)
コマース型(COMMERCE)
プレミアム動画型(PREMIUM_VIDEO)
templateCode Optional String テンプレートコード
requestStartTime Mandatory String 照会時間の開始時刻 yyyy-MM-dd'T'HH:mm:ss
requestEndTime Mandatory String 照会時間の終了時刻 yyyy-MM-dd'T'HH:mm:ss
completeStartTime Mandatory String 送信完了の開始時間 yyyy-MM-dd'T'HH:mm:ss
completeEndTime Mandatory String 送信完了の終了時間 yyyy-MM-dd'T'HH:mm:ss
messageId Optional String メッセージ ID
requestStatusName Optional String リクエスト状態 success, fail
messageStatusName Optional String リクエスト状態 success, processing, fail
to Optional String メッセージ受信番号 ハイフン「-」を除く番号
nextToken Optional String 次のページのトークン 下記参照
pageSize Optional Integer ページサイズ デフォルト: 20, 最大: 100
requestIdを含めて照会する場合、デフォルト: 100
参考
  • メッセージの送信履歴は直近30日以内の履歴のみ照会できます。
  • requestId、requestStartTime + requestEndTime、completeStartTime + completeEndTimeのうち少なくとも1つは必須です。
  • requestStartTime + requestEndTimeと completeStartTime + completeEndTimeは同時には使用できません。
  • requestStartTime ~ requestEndTimeの照会範囲は最大31日に制限されます。
  • completeStartTime ~ completeEndTimeの照会範囲は最大24時間に制限されます。
  • 照会条件に requestIdが含まれていない場合、plusFriendIdは必須です。
  • nextToken
    • 前のリクエストでnextTokenレスポンスを受け取った場合にのみ有効で、次のページの結果をリクエストできることを示します。追加結果がある場合、前のレスポンスのnextTokenの値をこの Parameterに設定すると、次のページの結果を照会できます。

Headers

API Headerへ

リクエストボディ

なし

レスポンスボディ

{
    "requestId": "string", 
    "statusCode": "string",
    "statusName": "string",
    "messages": [
        {
            "requestTime": "string",
            "messageId": "string",
            "messageType": "string",
            "targeting": "string",
            "countryCode": "string",
            "to": "string",
            "content": "string",
            "plusFriendId": "string",
            "completeTime": "string",
            "requestStatusCode": "string",
            "requestStatusName": "string",
            "requestStatusDesc": "string",
            "messageStatusCode": "string",
            "messageStatusName": "string",
            "messageStatusDesc": "string",
            "isAdult": "boolean",
            "useSmsFailover": "boolean"
        }
    ],
    "pageSize": "integer",
    "pageIndex": "integer",
    "itemCount": "integer",
    "hasMore": "boolean"
}
項目 Mandatory Type 説明 備考
requestId Optional String 送信リクエスト ID requestIdで照会する場合にのみ表示
statusCode Mandatory String リクエスト状態コード 202 - 成功
その他 - 失敗
* HTTP Status規格に従う
statusName Mandatory String リクエスト状態名 success - 成功
processing - 送信中
reserved - 予約中
fail - 失敗
messages[].requestTime Mandatory DateTime 送信リクエスト時間 yyyy-MM-dd'T'HH:mm:ss.SSS
messages[].messageId Mandatory String メッセージ ID
messages[].countryCode Optional String 受信者の国番号 デフォルト: 82
messages[].messageType Mandatory String メッセージタイプ テキスト型(TEXT)
画像型(IMAGE)
ワイド画像型(WIDE_IMAGE)
ワイドアイテムリスト型(WIDE_ITEM_LIST)
カルーセルフィード型(CAROUSEL_FEED)
カルーセルコマース型(CAROUSEL_COMMERCE)
コマース型(COMMERCE)
プレミアム動画型(PREMIUM_VIDEO)
messages[].targeting Mandatory String ターゲティングタイプ
messages[].to Mandatory String 受信者番号
messages[].content Mandatory String メッセージの内容
messages[].plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messages[].completeTime Optional DateTime 送信レポート(処理完了)時間 yyyy-MM-dd'T'HH:mm:ss
messages[].requestStatusCode Mandatory String 送信リクエスト状態コード A000 - 成功
その他のコード - 失敗(Desc項目に失敗理由が明示される)
messages[].requestStatusName Mandatory String 送信リクエスト状態名 success - 成功
fail - 失敗
messages[].requestStatusDesc Mandatory String 送信リクエスト状態の内容
messages[].messageStatusCode Mandatory String 送信結果状態コード 0000 - 成功
その他のコード - 失敗(Desc項目に失敗理由が明示される)
messages[].messageStatusName Mandatory String 送信結果状態名 success - 成功
processing - 処理中
    * 送信リクエスト成功後、メッセージ送信サーバで処理中の状態
    * messageCode、messageDescが照会されていない
fail - 失敗
messages[].messageStatusDesc Mandatory String 送信結果状態の内容
messages[].isAdult Mandatory Boolean 全年齢かどうか 成人: true
全年齢: false
messages[].useSmsFailover Mandatory Boolean SMS Failover使用の有無
pageSize Mandatory Integer ページサイズ
nextToken Optional String 次のページのトークン
itemCount Mandatory Integer 照会結果ページ内のメッセージ数
hasMore Mandatory Boolean 次のページの存在有無

レスポンスステータス

HTTP Status Desc
200 OK(照会完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

送信結果の照会

メッセージの送信結果を照会します。

リクエスト URL

GET https://sens.apigw.ntruss.com/brandmessage/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

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID
messageId Mandatory String メッセージ ID メッセージ送信時に返されるメッセージ識別子

Headers

API Headerへ

リクエストボディ

なし

レスポンスボディ

{
    "messageId":"string",
    "requestId":"string",
    "requestTime":"string",
    "completeTime":"string",
    "plusFriendId":"string",
    "messageType": "string",
    "targeting": "string",
    "countryCode":"string",
    "to":"string",
    "requestStatusCode":"string",
    "requestStatusName":"string",
    "requestStatusDesc":"string",
    "messageStatusCode":"string",
    "messageStatusName":"string",
    "messageStatusDesc":"string",
    "isAdult":"boolean",
    "useSmsFailover":"boolean",
    "content":"string",
	"headerContent":"string",
	"additionalContent":"string",
	"buttons":[
		{
			"type":"string",
			"name":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeIos":"string",
			"schemeAndroid":"string",
			"bizFormId":"string"
		}
	],
	"image":{
		"imageId":"string",
		"imageLink":"string"
	},
	"item":[
		{
			"title":"string",
			"imageId":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		}
	],
	"carousel": {
		"head": {
			"headerContent":"string",
			"content":"string",
			"imageId":"string",
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		},
		"list": [
			{
				"headerContent":"string",
				"message":"string",
				"additionalContent":"string",
				"image":{
					"imageId":"string",
					"imageLink":"string"
				},
				"buttons":[
					{
						"type":"string",
						"name":"string",
						"linkMobile":"string",
						"linkPc":"string",
						"schemeAndroid":"string",
						"schemeIos":"string",
						"bizFormId":"string"
					}
				],
				"coupon": {
					"title":"string",
					"description":"string",
					"linkMobile":"string",
					"linkPc":"string",
					"schemeAndroid":"string",
					"schemeIos":"string"
				},
				"commerce": {
					"title":"string",
					"regularPrice":"integer",
					"discountPrice":"integer",
					"discountRate":"integer",
					"discountFixed":"integer"
				}
			}
		],
		"tail": {
			"linkMobile":"string",
			"linkPc":"string",
			"schemeAndroid":"string",
			"schemeIos":"string"
		}
	},
	"commerce": {
		"title":"string",
		"regularPrice":"integer",
		"discountPrice":"integer",
		"discountRate":"integer",
		"discountFixed":"integer"
	},
	"coupon": {
		"title":"string",
		"description":"string",
		"linkMobile":"string",
		"linkPc":"string",
		"schemeAndroid":"string",
		"schemeIos":"string"
	},
	"video": {
		"thumbnailId":"string",
		"videoUrl":"string"
	},
	"useSmsFailover": "boolean"
}
項目 Mandatory Type 説明 備考
messageId Mandatory String メッセージ ID
requestId Mandatory String 送信リクエスト ID
requestTime Mandatory DateTime 送信リクエスト時間 yyyy-MM-dd'T'HH:mm:ss.SSS
completeTime Optional DateTime 送信レポート(処理完了)時間 yyyy-MM-dd'T'HH:mm:ss
plusFriendId Mandatory String カカオトークチャンネル名((旧)プラス友達 ID)
messageType Mandatory String メッセージタイプ テキスト型(TEXT)
画像型(IMAGE)
ワイド画像型(WIDE_IMAGE)
ワイドアイテムリスト型(WIDE_ITEM_LIST)
カルーセルフィード型(CAROUSEL_FEED)
カルーセルコマース型(CAROUSEL_COMMERCE)
コマース型(COMMERCE)
プレミアム動画型(PREMIUM_VIDEO)
targeting Mandatory String ターゲティングコード M, N, I
templateCode Mandatory String テンプレートコード
countryCode Optional String 受信者の国番号 デフォルト: 82
to Mandatory String 受信者番号
requestStatusCode Mandatory String 送信リクエスト状態コード A000 - 成功
その他のコード - 失敗(Desc項目に失敗理由が明示される)
requestStatusName Mandatory String 送信リクエスト状態名 success - 成功
fail - 失敗
requestStatusDesc Mandatory String 送信リクエスト状態の内容
messageStatusCode Mandatory String 送信結果状態コード 0000 - 成功
その他のコード - 失敗(Desc項目に失敗理由が明示される)
messageStatusName Mandatory String 送信結果状態名 success - 成功
processing - 処理中
    * 送信リクエスト成功後、メッセージ送信サーバで処理中の状態
    * messageCode、messageDescが照会されていない
fail - 失敗
messageStatusDesc Mandatory String 送信結果状態の内容
isAdult Mandatory Boolean 全年齢かどうか
content Optional String
headerContent Optional String ヘッダ
additionalContent Optional String 付加情報
buttons Optional List of Object ボタン ボタン情報を参照
buttons[].type Mandatory String ボタン Type
buttons[].name Mandatory String ボタン名
buttons[].linkMobile Optional String モバイルウェブリンク
buttons[].linkPc Optional String PCウェブリンク
buttons[].schemeAndroid Optional String Androidアプリリンク
buttons[].schemeIos Optional String iOSアプリリンク
image Optional Object 画像
image.imageId Mandatory String 画像 ID
image.imageLink Optional String 画像リンク
coupon Optional Object クーポン情報
coupon.title Mandatory String クーポンのタイトル
coupon.description Mandatory String クーポンの詳細説明 最大18文字
coupon.linkMobile Optional String モバイルウェブリンク
coupon.linkPc Optional String PCウェブリンク
coupon.schemeAndroid Optional String Androidアプリリンク
coupon.schemeIos Optional String iOSアプリリンク
video Optional Object 動画情報
video.thumbnailId Mandatory String 動画サムネイル用画像 ID
video.videoUrl Mandatory String カカオ TV動画 URL
item Optional Object
item.list Mandatory List of Object ワイドリスト
item.list[].title Optional String アイテムのタイトル
item.list[].imageId Mandatory String 画像 ID
item.list[].linkMobile Mandatory String モバイルウェブリンク
item.list[].linPc Optional String PCウェブリンク
item.list[].schemeAndroid Optional String Androidアプリリンク
item.list[].schemeIos Optional String iOSアプリリンク
carousel Optional Object カルーセル情報
carousel.head Optional Object カルーセルイントロ情報
carousel.head.headerContent Mandatory String ヘッダ
carousel.head.content Mandatory String 内容
carousel.head.imageId Mandatory String 画像 ID
carousel.head.linkMobile Optional String モバイルウェブリンク
carousel.head.linkPc Optional String PCウェブリンク
carousel.head.schemeAndroid Optional String Androidアプリリンク
carousel.head.schemeIos Optional String iOSアプリリンク
carousel.list Mandatory List of Object カルーセルリスト
carousel.list[].headerContent Optional String カルーセルリストアイテムのタイトル
carousel.list[].message Mandatory String カルーセルリストアイテムのメッセージ
carousel.list[].additionalContent Optional String カルーセルリストアイテムの付加情報
carousel.list[].image Mandatory Object カルーセルリストアイテム画像情報
carousel.list[].image.imageId Mandatory String 画像 ID
carousel.list[].image.imageLink Optional String 画像リンク
carousel.list[].buttons Mandatory List of Object ボタン情報
carousel.list[].buttons[].type Mandatory String ボタン Type
carousel.list[].buttons[].name Mandatory String ボタン名
carousel.list[].buttons[].linkMobile Optional String モバイルウェブリンク
carousel.list[].buttons[].linkPc Optional String PCウェブリンク
carousel.list[].buttons[].schemeAndroid Optional String Androidアプリリンク
carousel.list[].buttons[].schemeIos Optional String iOSアプリリンク
carousel.list[].buttons[].bizFormId Optional String
carousel.list[].coupon Optional Object クーポン情報
carousel.list[].coupon.title Mandatory String クーポンのタイトル
carousel.list[].coupon.description Mandatory String クーポンの詳細説明
carousel.list[].coupon.linkMobile Optional String モバイルウェブリンク
carousel.list[].coupon.linkPc Optional String PCウェブリンク
carousel.list[].coupon.schemeAndroid Optional String Androidアプリリンク
carousel.list[].coupon.schemeIos Optional String iOSアプリリンク
carousel.list[].commerce Optional Object コマース情報
carousel.list[].commerce.title Mandatory String 商品のタイトル
carousel.list[].commerce.regularPrice Mandatory Integer 商品の通常価格
carousel.list[].commerce.discountPrice Optional Integer 商品の割引価格
carousel.list[].commerce.discountRate Optional Integer 商品割引率
carousel.list[].commerce.discountFixed Optional Integer 商品の定額割引価格
carousel.tail Optional Object カルーセルのもっと見る情報
carousel.tail.linkMobile Mandatory String モバイルウェブリンク
carousel.tail.linkPc Optional String PCウェブリンク
carousel.tail.schemeAndroid Optional String Androidアプリリンク
carousel.tail.schemeIos Optional String iOSアプリリンク
commerce Optional Object コマース情報
commerce.title Mandatory String 商品のタイトル
commerce.regularPrice Mandatory Integer 商品の通常価格
commerce.discountPrice Optional Integer 商品の割引価格
commerce.discountRate Optional Integer 商品割引率
commerce.discountFixed Optional Integer 商品の定額割引価格
useSmsFailover Mandatory Boolean SMS Failover使用の有無

レスポンスステータス

HTTP Status Desc
200 OK(照会完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

画像

イメージのアップロード

ブランドメッセージの送信に使用する画像をアップロードします。

リクエスト URL

POST https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images

Content-Type: multipart/form-data; boundary=a29b1180-70f5-42f7-afbe-0d68a15f2370
x-ncp-apigw-timestamp: {Timestamp}
x-ncp-iam-access-key: {Sub Account Access Key}
x-ncp-apigw-signature-v2: {API Gateway Signature}

Path Variables

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID

Headers

API Headerへ

リクエストパラメータ

項目 Mandatory Type 説明 備考
imageType Mandatory String 画像タイプ情報を参照
imageFile Mandatory File 画像ファイル

レスポンスボディ

{
    "imageId":"string",
    "imageType":"string",
    "imageName":"string",
    "imageUrl":"string",
    "createTime":"string"
}
項目 Mandatory Type 説明 備考
imageId Mandatory Strng 画像 ID
imageType Mandatory String 画像タイプ情報を参照
imageName Mandatory String 画像ファイル名
imageUrl Mandatory String 画像 URL
createTime Mandatory DateTime 画像をアップロードした日時

レスポンスステータス

HTTP Status Desc
200 OK (アップロード完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

イメージリストの照会

アップロードされた画像リストを照会します。

リクエスト URL

GET https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images

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

Path Variables

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID

Headers

API Headerへ

Parameters

項目 Mandatory Type 説明 備考
pageIndex Optional Integer ページインデックス デフォルト: 0
pageSize Optional Integer ページサイズ デフォルト: 20 (1~100以内の数字のみ入力可能)

リクエストボディ

なし

レスポンスボディ

{
  "items": [
    {
      "imageId":"string",
      "imageType":"string",
      "imageName":"string",
      "imageUrl":"string",
      "createTime":"string"
    }
  ],
  "pageIndex": "integer",
  "pageSize": "integer",
  "itemCount": "integer",
  "hasPrevious": "boolean",
  "hasNext": "boolean",
  "totalCount": "integer"
}
項目 Mandatory Type 説明 備考
items Mandatory List of Object
items[].imageId Mandatory Strng 画像 ID
items[].imageType Mandatory String 画像タイプ情報を参照
items[].imageName Mandatory String 画像ファイル名
items[].imageUrl Mandatory String 画像 URL
items[].createTime Mandatory DateTime 画像をアップロードした日時
pageIndex Mandatory Integer ページインデックス
pageSize Mandatory Integer ページサイズ
itemCount Mandatory Integer 照会結果のアイテム数
hasPrevious Mandatory Boolean 以前のページの存在有無
hasNext Mandatory Boolean 次のページの存在有無
totalCount Mandatory Integer 総数

レスポンスステータス

HTTP Status Desc
200 OK (照会完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

画像の個別照会

アップロードされた画像を個別照会します。

リクエスト URL

GET https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images/{imageId}

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

Path Variables

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID
imageId Mandatory String 画像 ID アップロードされた画像 ID

Headers

API Headerへ

リクエストボディ

なし

レスポンスボディ

{
    "imageId":"string",
    "imageType":"string",
    "imageName":"string",
    "imageUrl":"string",
    "createTime":"string"
}

レスポンスステータス

HTTP Status Desc
200 OK (照会完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

イメージの削除

アップロードされた画像を削除します。

リクエスト URL

DELETE https://sens.apigw.ntruss.com/brandmessage/v2/services/{serviceId}/images/{imageId}

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

Path Variables

項目 Mandatory Type 説明 備考
serviceId Mandatory String サービス ID プロジェクト登録時に発行されたサービス ID
imageId Mandatory String 画像 ID アップロードされた画像 ID

Headers

API Headerへ

リクエストボディ

なし

レスポンスボディ

なし

レスポンスステータス

HTTP Status Desc
204 No Content(削除完了)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

画像タイプ情報

項目 説明 備考
BASIC TEXT、COMMERCE、PREMIUM_VIDEO画像 推奨サイズ: 800 x 400px(横500px以上)
アスペクト比(width / height): 0.5 ~ 1.333
jpg、png
最大5MB
WIDE WIDE_IMAGE画像 推奨サイズ: 800 x 600px(横500px以上)
アスペクト比(width / height): 0.5 ~ 1.0
jpg、png
最大5MB
WIDE_ITEM_LIST_MAIN WIDE_ITEM_LISTの1番目のアイテム画像 横 500px以上
アスペクト比(width / height): 0.5
jpg、png
最大5MB
WIDE_ITEM_LIST_SUB WIDE_ITEM_LISTの2番目以降のアイテム画像 横 500px以上
アスペクト比(width / height): 1.0
jpg、png
最大5MB
CAROUSEL_FEED CAROUSEL_FEED画像 推奨サイズ: 800 x 600pxまたは800 x 400px(横 500px以上)
アスペクト比(width / height) 0.5 ~ 1.333
jpg、png
最大5MB
CAROUSEL_COMMERCE CAROUSEL_COMMERCE画像 推奨サイズ: 800 x 600pxまたは800 x 400px(横 500px以上)
アスペクト比(width / height) 0.5 ~ 1.333 (全アスペクト比は同一)
jpg、png
最大5MB

エラーコード

BizMessageの受信結果コード

Status Error text Desc
0000 - 正常に送信
1001 NoJsonBody Request Bodyが JSON形式ではない
1002 InvalidHubPartnerKey パートナーキーが有効ではない
1003 InvalidSenderKey 送信プロファイルキーが有効ではない
1004 NoValueJsonElement Request BODY(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で使用できない response_methodでリクエスト(画像通知トーク(AI)はリアルタイムで送信不可)
1027 - チャンネルメッセージ制裁状態によるメッセージ送信失敗
1030 InvalidParameterException 正しくないパラメータリクエスト
1033 - テンプレートタイプとメッセージタイプが一致しない
2000 FailedToCheckFriendshipException トークチャンネルとの友達関係確認時のエラー(システムエラー)
2003 FailedToSendMessageByNoFriendshipException メッセージの送信失敗 (テストサーバでカカオトークチャンネルを追加していない場合)
2004 FailedToMatchTemplateException テンプレートと一致してるかどうかを確認中にエラー発生 (カカオトークの内部エラー)
2005 FailedToReadImageException カカオから画像のメタ情報を読み込み中にエラー
2006 FailedToMatchSerialNumberPrefixPattern シリアル番号形式の不一致
3000 UnexceptedExcetpion 予期せぬエラーの発生
3005 AckTimeoutException メッセージを送信したが、受信が確認できてない(成否が不明)
3006 FailedToSendMessageException カカオトーク内部システムエラーによるメッセージ送信失敗
3008 InvalidPhoneNumberException 電話番号エラー
3010 JsonParsseExcetpion JSONパースエラー
3011 MessageNotFoundException メッセージが存在しない
3012 SerialNumberDuplicatedException メッセージのシリアル番号が重複している(メッセージのシリアル番号は固有の値でなければならない)
3013 MessageEmptyException 空のメッセージ
3014 MessageLengthOverLimitException メッセージの長さ制限エラー(テキストタイプ1000文字をオーバー、画像タイプ400文字をオーバー)
3015 TemplateNotFoundException テンプレートが見つからない
3016 NoMatchedTemplateException メッセージ内容がテンプレートと一致しない
3018 NoSendAvailableException メッセージを送信できない
3019 MessageNoUserException トークのユーザーではない
3020 MessageUserBlockedAlimTalkException 通知トークブロック
3021 MessageNotSupportedKakaotalkException トークの最低バージョンをサポートしない
3022 NoSendAvailableTimeException メッセージが送信可能な時間ではない(友達トーク/マーケティングメッセージは08時~20時まで送信可能)
3023 MessageInvalidVideoException メッセージに含まれるビデオを送信できない(ビデオのアドレスまたはサムネイル画像アドレスが正しくないか、サムネイル画像が規格に合わない)
3024 MessageInvaildImageException メッセージに含まれた画像を送信できない
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文字)
3031 - テキストタイプの不一致
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 予期せぬエラー