Send

Prev Next

Classic/VPC環境で利用できます。

チャットボットに質問を渡します。

参考

チャットボット返答のレスポンスコンポーネントは次の3つの種類のコンポーネントを提供します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド URI
POST CLOVA Chatbotビルダで作成された API Gatewayの固有の InvokeURL

リクエストヘッダ

CLOVA Chatbot Custom APIで共通して使用されるヘッダの詳細は、CLOVA Chatbot Custom APIの共通ヘッダをご参照ください。

リクエストボディ

リクエストボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
version String Optional チャットボットのバージョン
  • v1 | v2(デフォルト)
    • 入力しない場合はv1に設定
userId String Required チャットボットユーザーの固有の ID
  • 256文字以内で任意に入力
userIp String Optional ユーザー IPアドレス
timestamp Long Required 任意のタイムスタンプ(Timestamp)
bubbles Array Required 1つの Textコンポーネントのみサポート
event String Required イベントの値
  • sendに設定

bubble

bubbleの説明は次の通りです。

フィールド タイプ 必須の有無 説明
type String Required コンポーネントのタイプ
data Object Required コンポーネントの構成情報
data.description String Required コンポーネントの詳細説明

リクエスト例

リクエストのサンプルコードは次の通りです。

{
"version": "v2",
"userId": "{userId}",
"userIp": "{userIp}",
"timestamp": 12345678,
"bubbles": [ 
    {
        "type": "text",
        "data" : { 
            "description" : "コンソールから CLOVA Chatbotサービスにはどうやってアクセスしますか?" 
        } 
    } 
],
"event": "send"
}

レスポンス

レスポンス形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
version String Optional チャットボットのバージョン
  • v1 | v2
    • リクエスト時に入力しない場合、v1が返される
userId String Required チャットボットユーザーの固有の ID
  • リクエスト時に設定したuserId値と同じ
sessionId String Optional 現在のセッション ID
  • CLOVA Chatbotで管理
timestamp Long Required タイムスタンプ(ms)
bubbles Array Optional bubblesの詳細情報
  • レスポンスコンポーネントの配列
  • 各コンポーネントはチャットボットのレスポンスバブル(Bubble)と一致
scenario Object Optional シナリオ情報
  • ユーザーの質問と一致するシナリオ分析結果
  • シナリオの名前と意図(会話タイプ)を提供
scenario.name String Conditional シナリオ名
scenario.chatUtteranceSetId Long Conditional シナリオ発話タイプ ID
scenario.intent Array Conditional シナリオの意図(会話タイプ)
entities Array Optional ユーザーの質問と一致するチャットボットエンティティ(Entity)の分析結果
quickButtons Array Optional チャットボット下部に設定された固定ボタン情報
keywords Array Optional keywordsの詳細情報
  • exactMatch | contain
    • exactMatch: ユーザーの入力値とキーワードが一致
    • contain: ユーザーの入力値にキーワードが含まれる
conversation Object Optional 会話情報
conversation.scenarioName String Conditional シナリオ名
conversation.chatUtteranceSetId Long Conditional 会話発話タイプ ID
conversation.types Array Conditional 会話タイプ
normalizer String Optional ユーザーの質問と一致するシステムエンティティ(Entity)
event String Required イベントの値

bubbles

bubblesの説明は次の通りです。

フィールド タイプ 必須の有無 説明
type String Required コンポーネントのタイプ
title String Optional コンポーネントの名前
data Object Optional コンポーネントの構成情報
data.description String Conditional コンポーネントの詳細説明
data.url String Conditional URLアドレス
data.urlAlias String Conditional URLのエイリアス
data.packageId String Conditional LINE Stickerパッケージ ID
data.stickerId String Conditional LINE Stickerステッカー ID
information Array Optional informationの詳細情報
context Array Optional コンポーネントのコンテキスト情報

information

bubbles.informationの説明は次の通りです。

フィールド タイプ 必須の有無 説明
key String Conditional データキー
value String Conditional データの値

keywords

keywordsの説明は次の通りです。

フィールド タイプ 必須の有無 説明
keyword String Conditional キーワード
group String Conditional キーワードグループ
type String Conditional キーワードの種類

レスポンスステータスコード

CLOVA Chatbot Custom APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA Chatbot Custom APIの共通レスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

基本返答

基本返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664169457884,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer",
        "url": "https://ncloud.com", // optional : URL
        "urlAlias": "https://ncloud.com" // optional : URL
      },
      "information": [
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929383, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929383, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

画像返答

画像返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664170469355,
  "bubbles": [
    {
      "type": "carousel",
      "data": {
        "cards": [
          {
            "type": "template",
            "data": {
              "cover": {
                "type": "image",
                "data": {
                  "imageUrl": "https://clovachatbot.ncloud.com/i48103278ci6f6-9f51-4d08-a947-1c8acc992629",
                  "imagePosition": "top",
                  "action": {
                    "type": "link",
                    "data": {
                      "url": "https://ncloud.com"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929385, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929385, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

画像+テキスト返答

画像+テキスト返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664170681849,
  "bubbles": [
    {
      "type": "carousel",
      "data": {
        "cards": [
          {
            "type": "template",
            "data": {
              "cover": {
                "type": "image",
                "title": "image title",
                "data": {
                  "imageUrl": "https://clovachatbot.ncloud.com/i48103278ci6f6-9f51-4d08-a947-1c8acc992629",
                  "description": "image description"
                }
              },
              "contentTable": [
                [
                  {
                    "rowSpan": 1,
                    "colSpan": 1,
                    "data": {
                      "type": "button",
                      "title": "display button1 name",
                      "data": {
                        "type": "basic",
                        "action": {
                          "type": "link",
                          "data": {
                            "url": "https://ncloud.com"
                          }
                        }
                      }
                    }
                  }
                ],
                [
                  {
                    "rowSpan": 1,
                    "colSpan": 1,
                    "data": {
                      "type": "button",
                      "title": "display button2 name",
                      "data": {
                        "type": "basic",
                        "action": {
                          "type": "link",
                          "data": {
                            "url": "https://fin-ncloud.com"
                          }
                        }
                      }
                    }
                  }
                ]
              ]
            },
            "information": [
              {
                "key": "carousel",
                "value": "1"
              },
              {
                "key": "chatType",
                "value": "IMAGECARD"
              },
              {
                "key": "imageOnly",
                "value": "false"
              },
              {
                "key": "chatType",
                "value": "IMAGECARD"
              },
              {
                "key": "score",
                "value": "1.0"
              },
              {
                "key": "scenarioName",
                "value": "Conversation Name"
              },
              {
                "key": "matchingType",
                "value": "exactMatch"
              },
              {
                "key": "domainCode",
                "value": "Domain Code"
              }
            ],
            "context": []
          }
        ]
      }
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929386, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929386, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

マルチリンク返答

マルチリンク返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171090887,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name",
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "link",
                    "data": {
                      "url": "https://ncloud.com"
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "chatType",
          "value": "MULTILINKS"
        },
        {
          "key": "chatType",
          "value": "MULTILINKS"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929384, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929384, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

フォーム V1(選択肢型)返答

フォーム V1(選択肢型)返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171277095,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name", // ボタン名を表示する場合、この値を使用(Use this value if you want the button name to be displayed.)
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "postback",
                    "data": {
                      "postback": "Button Name",
                      "postbackFull": "_T_Button Name" // ボタンが実行されるようにする場合、この値を使用(Use this value if you want a button action.)
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        },
        {
          "key": "serviceLinkedToForm",
          "value": ""
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929388, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929388, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

フォーム V2(選択肢型)返答

フォーム V2(選択肢型)返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664171884718,
  "bubbles": [
    {
      "type": "template",
      "data": {
        "cover": {
          "type": "text",
          "data": {
            "description": "Chatbot Answer"
          }
        },
        "contentTable": [
          [
            {
              "rowSpan": 1,
              "colSpan": 1,
              "data": {
                "type": "button",
                "title": "Button Name",
                "data": {
                  "type": "basic",
                  "action": {
                    "type": "postback",
                    "data": {
                      "postback": "UnexpiredForm\u241e47952\u241e0",
                      "displayText": "Button Name", // ボタン名を表示する場合、この値を使用(Use this value if you want the button name to be displayed.)
                      "postbackFull": "_T_UnexpiredForm\u241e47952\u241e0" // ボタンが実行されるようにする場合、この値を使用(Use this value if you want a button action.)
                    }
                  }
                }
              }
            }
          ]
        ]
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929389, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929389, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

フォーム V1(Quick reply)返答

フォーム V1(Quick reply)返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664172269192,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        },
        {
          "key": "serviceLinkedToForm",
          "value": ""
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929390, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "quickButtons": [
    {
      "type": "button",
      "title": "Button Name",
      "data": {
        "type": "basic",
        "action": {
          "type": "postback",
          "data": {
            "postback": "Button Name",
            "postbackFull": "_T_Button Name" // ボタンが実行されるようにする場合、この値を使用(Use this value if you want a button action.)
          }
        }
      }
    }
  ],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929390, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

フォーム V2(Quick reply)返答

フォーム V2(Quick reply)返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1664172948306,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "imageOnly",
          "value": "false"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "chatType",
          "value": "SINGLEFORM"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929393, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "quickButtons": [
    {
      "type": "button",
      "title": "Button Name",
      "data": {
        "type": "basic",
        "action": {
          "type": "postback",
          "data": {
            "postback": "UnexpiredForm\u241e47954\u241e0",
            "displayText": "Button Name", // ボタン名を表示する場合、この値を使用(Use this value if you want the button name to be displayed.)
            "postbackFull": "_T_UnexpiredForm\u241e47954\u241e0" // ボタンが実行されるようにする場合、この値を使用(Use this value if you want a button action.)
          }
        }
      }
    }
  ],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929393, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

フォーム記入型返答

フォーム記入型返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1665038738758,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": "Chatbot Answer"
      },
      "information": [
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "chatType",
          "value": "TEXT"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        },
        {
          "key": "formStart",
          "value": "true"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929394, // 会話の発話 ID(Conversation ID)
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929394, // 会話の発話 ID(Conversation ID)
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

返答なしの返答

返答なしの返答の場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "timestamp": 1665972966091,
  "bubbles": [
    {
      "type": "text",
      "data": {
        "description": ""
      },
      "information": [
        {
          "key": "chatType",
          "value": "NOANSWER"
        },
        {
          "key": "chatType",
          "value": "NOANSWER"
        },
        {
          "key": "score",
          "value": "1.0"
        },
        {
          "key": "scenarioName",
          "value": "Conversation Name"
        },
        {
          "key": "endOfBubble",
          "value": "endOfBubble"
        },
        {
          "key": "matchingType",
          "value": "exactMatch"
        },
        {
          "key": "domainCode",
          "value": "Domain Code"
        }
      ],
      "context": []
    }
  ],
  "scenario": {
    "name": "Conversation Name",
    "chatUtteranceSetId": 4929395,
    "intent": []
  },
  "entities": [],
  "keywords": [],
  "conversation": {
    "scenarioName": "Conversation Name",
    "chatUtteranceSetId": 4929395,
    "types": []
  },
  "normalizer": "null",
  "event": "send"
}

LINE Flex

LINE Flexの場合のレスポンスのサンプルコードは次の通りです。

{
  "version": "v2",
  "userId": "{userId}",
  "sessionId": "{sessionId}",
  "timestamp": 12345678,
  "bubbles": [
    {
      "type": "flex",
      "title": "this is a flex message",
      "data" : {
        "type": "bubble",
        "hero": {
          "type": "image",
          "url": "https://scdn.line-apps.com/n/channel_devcenter/img/fx/01_1_cafe.png",
          "size": "full",
          "aspectRatio": "20:13",
          "aspectMode": "cover",
        },
        "body": {
          "type": "box",
          "layout": "vertical",
          "contents": [
            {
              "type": "text",
              "text": "Brown Cafe",
              "weight": "bold",
              "size": "xl"
            }
          ]
        },
        "footer": {
          "type": "box",
          "layout": "vertical",
          "spacing": "sm",
          "contents": [
            {
              "type": "button",
              "style": "link",
              "height": "sm",
              "action": {
                "type": "uri",
                "label": "CALL",
                "uri": "https://linecorp.com"
              }
            },
            {
              "type": "spacer",
              "size": "sm"
            }
          ],
          "flex": 0
        }
      }
    }
  ],
  "event": "send"
}

LINE Sticker

LINE Stickerの場合のレスポンスのサンプルコードは次の通りです。

{
  "type": "line_sticker",
  "data": {
    "packageId": "446",
    "stickerId": "1988"
  },
  "information": [
    {
      "key": "chatType",
      "value": "STICKER"
    },
    {
      "key": "chatType",
      "value": "STICKER"
    },
    {
      "key": "tagInfo",
      "value": "platformExactMatch=line"
    },
    {
      "key": "score",
      "value": "1.0"
    },
    {
      "key": "scenarioName",
      "value": "Conversation Name"
    },
    {
      "key": "endOfBubble",
      "value": "endOfBubble"
    },
    {
      "key": "matchingType",
      "value": "exactMatch"
    },
    {
      "key": "domainCode",
      "value": "Domain Code"
    }
  ],
  "context": [],
  "event": "send"
}