{"_id":"5845a4a99f6fbb1b004307f3","parentDoc":null,"user":"55bf6cdcad601c2b00762d13","project":"54d3007669578e0d002730c9","__v":0,"category":{"_id":"5845a4a89f6fbb1b004307b9","version":"5845a4a89f6fbb1b004307b7","__v":0,"project":"54d3007669578e0d002730c9","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-30T06:25:25.645Z","from_sync":false,"order":1,"slug":"key-concepts","title":"Key Concepts"},"version":{"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","__v":2,"createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0","592deb23644f060f008e5aa6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"25.0.0","version":"25"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-03T07:59:52.362Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"* [Overview](#overview)\n * [Message types for different platforms](#section-message-types-for-different-platforms)\n* [Text response](#text-response)\n* [Image](#image)\n* [Card](#card)\n * [Cards in Facebook Messenger](#section-cards-in-facebook-messenger)\n * [Cards in Kik](#section-cards-in-kik)\n * [Cards in Slack](#section-cards-in-slack)\n * [Cards in Telegram](#section-cards-in-telegram)\n * [Cards in Skype](#section-cards-in-skype)\n* [Quick replies](#quick-replies)\n * [Quick replies in Facebook Messenger](#section-quick-replies-in-facebook-messenger)\n * [Quick replies in Kik](#section-quick-replies-in-kik)\n * [Quick replies in Slack](#section-quick-replies-in-slack)\n * [Quick replies in Telegram](#section-quick-replies-in-telegram)\n * [Quick replies in Skype](#section-quick-replies-in-skype)\n* [Custom payload](#custom-payload)\n * [Facebook Messenger custom payload samples](#section-facebook-messenger-custom-payload-samples)\n    + [Audio in one-click Facebook Messenger integration](#section-audio-in-one-click-facebook-messenger-integration)\n    + [Video in one-click Facebook Messenger integration](#section-video-in-one-click-facebook-messenger-integration)\n    + [Files in one-click Facebook Messenger integration](#section-files-in-one-click-facebook-messenger-integration)\n * [Kik custom payload samples](#section-kik-custom-payload-samples)\n     + [Gifs in one-click Kik integration](#section-gifs-in-one-click-kik-integration)\n     + [Videos in one-click Kik integrations](#section-videos-in-one-click-kik-integrations)\n * [Slack custom payload samples](#section-slack-custom-payload-samples)\n     + [Formatted text in one-click Slack integration](#section-formatted-text-in-one-click-slack-integration)\n * [Telegram custom payload samples](#section-telegram-custom-payload-samples)\n     + [Formatted text and hyperlinks in one-click Telegram integration](#section-formatted-text-and-hyperlinks-in-one-click-telegram-integration)\n     + [Inline Keyboard Buttons in one-click Telegram integration](#section-inline-keyboard-buttons-in-one-click-telegram-integration)\n * [Skype custom payload samples](#section-skype-custom-payload-samples)\n     + [Formatted text and hyperlinks in one-click Skype integration](#section-formatted-text-and-hyperlinks-in-one-click-skype-integration)\n     + [Skype emoticons in one-click Skype integration](#section-skype-emoticons-in-one-click-skype-integration)\n     + [Attachments in one-click Skype integration](#section-attachments-in-one-click-skype-integration)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nIn the <a href=\"https://docs.api.ai/docs/concept-intents#response\" target=\"_blank\">‘Response’ section of intents</a>, you can define your agent’s responses which will be provided by your application/bot/device when the intent is triggered.\n\nIn the ‘Response’ section, you can add tabs for some of our supported integrations. This allows you to define default or integration specific responses for these integrations. In each tab, you can add up to 10 of the same or different message types. The DEFAULT tab and the integration tabs offer different message types. The integration tabs allow you to add images, cards, quick replies in a quick and simple manner.\n\nTo add integration tabs, either enable respective integrations on the 'Integrations' page or click on the + sign next to the DEFAULT tab. To add message elements, click the ‘ADD MESSAGE CONTENT’ button. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/55d1867-ResponseBuilder_add-tab.jpg\",\n        \"ResponseBuilder_add-tab.jpg\",\n        1986,\n        1382,\n        \"#f9f2f9\"\n      ]\n    }\n  ]\n}\n[/block]\n## Message types for different platforms\n\nYour agent’s response can consist of up to 10 sequential messages if you use one of the following tabs to define the response:\n- Default\n- Facebook Messanger  \n- Slack\n- Telegram\n- Kik\n- Skype\n\nIn the the Actions on Google tab, the maximum number of messages depends on what messages you decide to add.\n\nYou can drag messages in the UI to reorder them. If you create intents via the <a href=\"https://docs.api.ai/docs/intents\" target=\"_blank\">/intents endpoint</a>, the order of messages will correspond to the \"messages\" array elements order.\n\nDepending on the platform(s) to which you are integrating your agent, you can use different type of responses:\n[block:html]\n{\n  \"html\": \"<style>\\n\\n   .cell {\\n     \\tpadding: 1em;\\n    \\n   }\\n  .cell-left {\\n    margin-left: 6px;\\n  }\\n</style>\\n\\n <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\"><strong>Type of message</strong></div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\"><strong>Currently supported platforms</strong></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Text response</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">All platforms</div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Image</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integrations for <a href=\\\"https://docs.api.ai/docs/facebook-integration\\\" target=\\\"_blank\\\">Facebook Messenger</a>, <a href=\\\"https://docs.api.ai/docs/kik-integration\\\" target=\\\"_blank\\\">Kik</a>, <a href=\\\"https://docs.api.ai/docs/slack-integration\\\" target=\\\"_blank\\\">Slack</a>, <a href=\\\"https://docs.api.ai/docs/telegram-integration\\\" target=\\\"_blank\\\">Telegram</a>, <a href=\\\"https://docs.api.ai/docs/skype-integration\\\" target=\\\"_blank\\\">Skype</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Card</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integrations for <a href=\\\"https://docs.api.ai/docs/facebook-integration\\\" target=\\\"_blank\\\">Facebook Messenger</a>, <a href=\\\"https://docs.api.ai/docs/kik-integration\\\" target=\\\"_blank\\\">Kik</a>, <a href=\\\"https://docs.api.ai/docs/slack-integration\\\" target=\\\"_blank\\\">Slack</a>, <a href=\\\"https://docs.api.ai/docs/telegram-integration\\\" target=\\\"_blank\\\">Telegram</a>, <a href=\\\"https://docs.api.ai/docs/skype-integration\\\" target=\\\"_blank\\\">Skype</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Quick replies</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integrations for <a href=\\\"https://docs.api.ai/docs/facebook-integration\\\" target=\\\"_blank\\\">Facebook Messenger</a>, <a href=\\\"https://docs.api.ai/docs/kik-integration\\\" target=\\\"_blank\\\">Kik</a>, <a href=\\\"https://docs.api.ai/docs/slack-integration\\\" target=\\\"_blank\\\">Slack</a>, <a href=\\\"https://docs.api.ai/docs/telegram-integration\\\" target=\\\"_blank\\\">Telegram</a>, <a href=\\\"https://docs.api.ai/docs/skype-integration\\\" target=\\\"_blank\\\">Skype</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Custom payload</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">- One-click integrations for <a href=\\\"https://docs.api.ai/docs/facebook-integration\\\" target=\\\"_blank\\\">Facebook Messenger</a>, <a href=\\\"https://docs.api.ai/docs/kik-integration\\\" target=\\\"_blank\\\">Kik</a>, <a href=\\\"https://docs.api.ai/docs/slack-integration\\\" target=\\\"_blank\\\">Slack</a>, <a href=\\\"https://docs.api.ai/docs/telegram-integration\\\" target=\\\"_blank\\\">Telegram</a>, <a href=\\\"https://docs.api.ai/docs/skype-integration\\\" target=\\\"_blank\\\">Skype</a>, <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a>\\n<br>- Custom integration implementations for other platforms.</div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Simple response</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Basic card</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">List</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Suggestion chips</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Carousel card</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\\n  <div class=\\\"row\\\">\\n    <div class=\\\"col-md-3 col-sm-4 col-xs-12 cell cell-left\\\">Link out suggestion</div>\\n    <div class=\\\"col-md-8 col-sm-6 col-xs-12 cell\\\">One-click integration for <a href=\\\"https://docs.api.ai/docs/actions-on-google-integration\\\" target=\\\"_blank\\\">Actions on Google</a></div>   \\n  </div>\"\n}\n[/block]\nFor more information on the response design for Actions on Google integration, read <a href=\"https://docs.api.ai/docs/response-design-for-actions-on-google\" target=\"_blank\">this documentation</a>. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Text response\"\n}\n[/block]\nYour agent can send up to 10 sequential text messages in response to a user input (assuming no other message types are defined in the intent). These feature is supported in <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a>, and <a href=\"https://docs.api.ai/docs/twilio-integration\" target=\"_blank\">Twilio</a> one-click integrations.\n\nLine breaks are currently supported for the following one-click integrations: <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, and <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a>. To add a new line in the UI, press Shift+Enter. If you <a href=\"https://docs.api.ai/docs/intents#post-intents\" target=\"_blank\">create intents via API</a>, use `\\n` in the <a href=\"https://docs.api.ai/docs/intents#intent-object\" target=\"_blank\">intent object</a>. \n\n```\n\"messages\": [        \n{\n          \t\"type\": 0,\n          \t\"speech\": \"Some text\\nNext line\"\n        \t}\n]\n```\n\nYou can reference parameter values as described <a href=\"https://docs.api.ai/docs/concept-intents#section-references-to-parameter-values\" target=\"_blank\">here</a>.\n\nText responses for Facebook Messenger integration have a 640 character limit.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Image\"\n}\n[/block]\nThe image message type lets your bots send images in one-click integrations for Facebook Messenger, Kik, Slack, and Telegram integrations.\n\nAll you need to do is to store the image so that you can provide a public URL to it in your agent.\n\nNote that platforms differ with regards to the supported formats and sizes: \n\n- Facebook Messenger: JPG, PNG, and GIC (animated GIFs are supported).\n- Kik: JPG up to 1MB size (to send animated GIFs, use video format in Custom payload)\n- Slack: GIF, JPEG, PNG, and BMP\n- Telegram: 5 MB max size\n- Skype: PNG or JPEG up to 1024x1024, up to 1MB in size. For GIFs and images up to 20MB, use attachments in Custom payload.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Card\"\n}\n[/block]\nCards consist of several elements:\n- Image\n- Card title\n- Card subtitle\n- Interactive buttons (for sending user queries or opening links)\n\nYou can combine these elements depending on the platform requirements.\n\n## Cards in Facebook Messenger\n\nCards correspond to a simplified <a href=\"https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template\" target=\"_blank\">Facebook Messenger generic template (bubble)</a>. \n\nIn one-click Facebook Messenger integration, cards can contain the same elements as a generic template except `item_url`. Also, interactive button functions are limited to opening a URL or sending a query from the user.\n\nIf you add several cards in the same intent, they are displayed in a horizontal scrollable carousel.\n\nThe title field cannot be empty. Also, either the image URL or the button title is required.\n\nButtons might be of the following types:\n- Title only (if tapped, the title text is sent as a user query)\n- Title with a URL to open\n- Title with text postback (when tapped, the text is sent as a user query)\n\nButton number is limited to 3. To add a new button, place the cursor in the button title field and press Enter.\n\nBe sure to check the `messages_postback` option in your Facebook app webhook settings.\n\nTitle, subtitle, and button title have an 80 character limit.\n\nThe image ratio is 1.91:1.\n\n## Cards in Kik\n\nSince cards are not natively supported in Kik, they are sent as separate elements: image with title, subtitle as a text message, and buttons. \n\nFor buttons, only a URL is supported as a postback – in this case, it is displayed as an image with linked URL. If you leave the postback field blank, when such a button is tapped, the button title is sent as a user query to the agent.\n\n## Cards in Slack\n\nThere are no mandatory fields for cards in Slack – any combination of elements can be used.\n\nButtons with a URL and with a text postback are supported. Buttons with a URL are displayed as hyperlinks. \n\n## Cards in Telegram\n\nEither the image URL field or the title field is mandatory.\n\nButtons with a URL and with a text postback are supported. When tapped, a button with a URL will open a web page, whereas a button with text will send the text as a user query.\n\n## Cards in Skype\n\nEither the image URL field or the title field or subtitle field is mandatory.\n\nButtons with a URL and with a text postback are supported. When tapped, a button with a URL will open a web page, whereas a button with text will send the text as a user query.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Quick Replies\"\n}\n[/block]\nQuick replies are displayed in messengers as clickable buttons with pre-defined user responses. When clicked, the button text is sent to the agent as a user query. \n\nYou can add one ‘Quick replies’ element per intent. The maximum number of replies is 10. Each reply has a 20 character limit.\n\n## Quick replies in Facebook Messenger\n\nQuick replies are supported in one-click Facebook Messenger integrations and correspond to a text version of <a href=\"https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies\" target=\"_blank\">Facebook Messenger quick replies</a>.\n\nWhen a user clicks one of the buttons, all buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation.\n\n## Quick replies in Kik\n\nQuick replies are supported in one-click Kik integrations and correspond to a text version of <a href=\"https://dev.kik.com/#/docs/messaging#keyboards\" target=\"_blank\">Suggested response keyboards in Kik</a> with a reduced number of replies and characters. \n\nIf you want to use a full version, you can do it through the [Custom payload](#custom-payload).\n\nWhen a user clicks one of the buttons, all buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation.\n\n## Quick replies in Slack\n\nQuick replies are supported in one-click Slack integrations and correspond to a text version of <a href=\"https://api.slack.com/docs/message-buttons\" target=\"_blank\">Slack interactive buttons</a>. \n\n## Quick replies in Telegram\n\nQuick replies in one-click Telegram integrations correspond to <a href=\"https://core.telegram.org/bots/api/#keyboardbutton\" target=\"_blank\">keyboard buttons in Telegram</a>.\n\nWhen a user clicks one of the buttons, the buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation.\n\n## Quick replies in Skype\n\nQuick replies in one-click Skype integrations correspond to buttons in Skype.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Custom payload\"\n}\n[/block]\nYou can send custom payloads in the JSON format provided in the platforms documentation.\n\nTo send a custom payload to one-click integrations, use the following format:\nFor Facebook Messenger:\n```\n{\n  \"facebook\": {\n  }\n}\n```\nFor Kik:\n```\n{\n  \"kik\": [{\n  }]\n}\n```\nFor Slack:\n```\n{\n  \"slack\": {\n  }\n}\n```\nFor Telegram:\n```\n{\n  \"telegram\": {\n  }\n}\n```\nFor Skype:\n```\n{\n  \"skype\": {\n  }\n}\n```\n\nYou can also send a custom payload to self-developed integrations. It won’t be processed by API.AI. You need to handle it in your business logic.\n\n## Facebook Messenger custom payload samples\n\n### Audio in one-click Facebook Messenger integration\n\nThe following example sends a playable audio link from your agent to a one-click Facebook Messenger integration:\n\n```\n{\n  \"facebook\": {\n    \"attachment\": {\n      \"type\": \"audio\",\n      \"payload\": {\n        \"url\": \"https://example.com/audio/test.mp3\"\n      }\n    }\n  }\n}\n```\nThe maximum audio file size is 10MB.\n\n### Video in one-click Facebook Messenger integration\n\nThe following example sends a playable video from your agent to a Facebook Messenger integration:\n```\n{\n  \"facebook\": {\n    \"attachment\": {\n      \"type\": \"video\",\n      \"payload\": {\n        \"url\": \"https://examples.api.ai/RichMessagesFiles/studebaker_1950.mp4\"\n      }\n    }\n  }\n}\n```\n\n### Files in one-click Facebook Messenger integration\n\nThe following example sends a file from your agent to a Facebook Messenger integration:\n```\n{\n  \"facebook\": {\n    \"attachment\": {\n      \"type\": \"file\",\n      \"payload\": {\n        \"url\": \"https://examples.api.ai/RichMessagesFiles/LoremIpsum.pdf\"\n      }\n    }\n  }\n}\n```\n\n## Kik custom payload samples\n\n### Gifs in one-click Kik integration\n\nThe following payload example sends animated gifs: \n\n```\n{\n  \"kik\": {\n    \"type\": \"video\",\n    \"videoUrl\": \"https://raw.githubusercontent.com/svet4/images/master/img/create-an-intent.gif\",\n    \"autoplay\": true\n  }\n}\n```\nFor more information, see <a href=\"https://dev.kik.com/#/docs/messaging#video\" target=\"_blank\">Kik documentation</a>.\n\n### Videos in one-click Kik integrations\n\nYour Kik bots can send playable videos. \n\nThe Kik mobile client requires that all videos are in mp4 format with h264 video and aac audio. If you provide a video with different specifications, it will be transcoded, which greatly increases the time required to send your messages. For more, please read <a href=\"https://dev.kik.com/#/docs/messaging#video\" target=\"_blank\">Kik documentation</a>.\n\nThe following example sends a playable video from your Kik bot to a Kik mobile client:\n\n```\n{\n  \"kik\": {\n    \"type\": \"video\",\n    \"videoUrl\": \"https://examples.api.ai/RichMessagesFiles/studebaker_1950.mp4\",\n    \"autoplay\": true\n  }\n}\n```\n\n## Slack custom payload samples\n\n### Formatted text in one-click Slack integration\n\nYour Slack bots can send <a href=\"https://api.slack.com/docs/message-formatting#message_formatting\" target=\"_blank\">formatted text</a>,  as the following example shows:\n\n```\n{\n  \"slack\": {\n    \"text\": \"This is an example of *bold*, _italic_, and `code`.\"\n  }\n}\n```\n\n## Telegram custom payload samples\n\n### Formatted text and hyperlinks in one-click Telegram integration\n\nYour Telegram bots can send formatted text and hyperlinks. \n\nThe following example sends formatted text with a hyperlink using the Markdown parsing mode:\n\n```\n{\n  \"telegram\": {\n    \"text\": \"You can read about *entities* [here](https://docs.api.ai/docs/concept-entities).\",\n    \"parse_mode\": \"Markdown\"\n  }\n}\n```\nSee the <a href=\"https://core.telegram.org/bots/api#formatting-options\" target=\"_blank\">Telegram documentation</a> for reference.\n\n### Inline Keyboard Buttons in one-click Telegram integration\n\nThe following example shows how you can define <a href=\"https://core.telegram.org/bots/api#inlinekeyboardmarkup\" target=\"_blank\">Inline Keyboard buttons</a> in the Custom payload element.\n\n```\n{\n  \"telegram\": {\n    \"text\": \"Pick a color\",\n    \"reply_markup\": {\n      \"inline_keyboard\": [\n        [\n          {\n            \"text\": \"Red\",\n            \"callback_data\": \"Red\"\n          }\n        ],\n        [\n          {\n            \"text\": \"Green\",\n            \"callback_data\": \"Green\"\n          }\n        ],\n        [\n          {\n            \"text\": \"Yellow\",\n            \"callback_data\": \"Yellow\"\n          }\n        ],\n        [\n          {\n            \"text\": \"Blue\",\n            \"callback_data\": \"Blue\"\n          }\n        ],\n        [\n          {\n            \"text\": \"Pink\",\n            \"callback_data\": \"Pink\"\n          }\n        ]\n      ]\n    }\n  }\n}\n```\n## Skype custom payload samples\n\n### Formatted text and hyperlinks in one-click Skype integration\n\nThe following example sends formatted text with a hyperlink using the default Markdown parsing mode:\n\n```\n{\n  \"skype\": {\n    \"text\": \"You can read about **entities** [here](https://docs.api.ai/docs/concept-entities).\"\n  }\n}\n```\n\n### Skype emoticons in one-click Skype integration\nSee the list of available <a href=\"https://support.skype.com/en/faq/FA12330/what-is-the-full-list-of-emoticons\" target=\"_blank\">Skype emoticons</a>.\n\n```\n{\n  \"skype\": {\n    \"text\": \"(heart) (penguin) (think) :)\"\n  }\n}\n```\n\n### Attachments in one-click Skype integration\n```\n{\n  \"skype\": {\n    \"attachments\": [\n      {\n        \"contentType\": \"image/png\",\n        \"contentUrl\": \"https://examples.api.ai/BobTheFlorist/bob_the_florist.png\",\n        \"name\": \"Profile-picture.png\"\n      }\n    ]\n  }\n}\n```\nFor more information on attachments, see the following <a href=\"https://docs.botframework.com/en-us/csharp/builder/sdkreference/attachments.html\" target=\"_blank\">Skype documentation</a>.","excerpt":"","slug":"rich-messages","type":"basic","title":"Rich Messages"}
* [Overview](#overview) * [Message types for different platforms](#section-message-types-for-different-platforms) * [Text response](#text-response) * [Image](#image) * [Card](#card) * [Cards in Facebook Messenger](#section-cards-in-facebook-messenger) * [Cards in Kik](#section-cards-in-kik) * [Cards in Slack](#section-cards-in-slack) * [Cards in Telegram](#section-cards-in-telegram) * [Cards in Skype](#section-cards-in-skype) * [Quick replies](#quick-replies) * [Quick replies in Facebook Messenger](#section-quick-replies-in-facebook-messenger) * [Quick replies in Kik](#section-quick-replies-in-kik) * [Quick replies in Slack](#section-quick-replies-in-slack) * [Quick replies in Telegram](#section-quick-replies-in-telegram) * [Quick replies in Skype](#section-quick-replies-in-skype) * [Custom payload](#custom-payload) * [Facebook Messenger custom payload samples](#section-facebook-messenger-custom-payload-samples) + [Audio in one-click Facebook Messenger integration](#section-audio-in-one-click-facebook-messenger-integration) + [Video in one-click Facebook Messenger integration](#section-video-in-one-click-facebook-messenger-integration) + [Files in one-click Facebook Messenger integration](#section-files-in-one-click-facebook-messenger-integration) * [Kik custom payload samples](#section-kik-custom-payload-samples) + [Gifs in one-click Kik integration](#section-gifs-in-one-click-kik-integration) + [Videos in one-click Kik integrations](#section-videos-in-one-click-kik-integrations) * [Slack custom payload samples](#section-slack-custom-payload-samples) + [Formatted text in one-click Slack integration](#section-formatted-text-in-one-click-slack-integration) * [Telegram custom payload samples](#section-telegram-custom-payload-samples) + [Formatted text and hyperlinks in one-click Telegram integration](#section-formatted-text-and-hyperlinks-in-one-click-telegram-integration) + [Inline Keyboard Buttons in one-click Telegram integration](#section-inline-keyboard-buttons-in-one-click-telegram-integration) * [Skype custom payload samples](#section-skype-custom-payload-samples) + [Formatted text and hyperlinks in one-click Skype integration](#section-formatted-text-and-hyperlinks-in-one-click-skype-integration) + [Skype emoticons in one-click Skype integration](#section-skype-emoticons-in-one-click-skype-integration) + [Attachments in one-click Skype integration](#section-attachments-in-one-click-skype-integration) [block:api-header] { "type": "basic", "title": "Overview" } [/block] In the <a href="https://docs.api.ai/docs/concept-intents#response" target="_blank">‘Response’ section of intents</a>, you can define your agent’s responses which will be provided by your application/bot/device when the intent is triggered. In the ‘Response’ section, you can add tabs for some of our supported integrations. This allows you to define default or integration specific responses for these integrations. In each tab, you can add up to 10 of the same or different message types. The DEFAULT tab and the integration tabs offer different message types. The integration tabs allow you to add images, cards, quick replies in a quick and simple manner. To add integration tabs, either enable respective integrations on the 'Integrations' page or click on the + sign next to the DEFAULT tab. To add message elements, click the ‘ADD MESSAGE CONTENT’ button. [block:image] { "images": [ { "image": [ "https://files.readme.io/55d1867-ResponseBuilder_add-tab.jpg", "ResponseBuilder_add-tab.jpg", 1986, 1382, "#f9f2f9" ] } ] } [/block] ## Message types for different platforms Your agent’s response can consist of up to 10 sequential messages if you use one of the following tabs to define the response: - Default - Facebook Messanger - Slack - Telegram - Kik - Skype In the the Actions on Google tab, the maximum number of messages depends on what messages you decide to add. You can drag messages in the UI to reorder them. If you create intents via the <a href="https://docs.api.ai/docs/intents" target="_blank">/intents endpoint</a>, the order of messages will correspond to the "messages" array elements order. Depending on the platform(s) to which you are integrating your agent, you can use different type of responses: [block:html] { "html": "<style>\n\n .cell {\n \tpadding: 1em;\n \n }\n .cell-left {\n margin-left: 6px;\n }\n</style>\n\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\"><strong>Type of message</strong></div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\"><strong>Currently supported platforms</strong></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Text response</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">All platforms</div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Image</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integrations for <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Card</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integrations for <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Quick replies</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integrations for <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Custom payload</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">- One-click integrations for <a href=\"https://docs.api.ai/docs/facebook-integration\" target=\"_blank\">Facebook Messenger</a>, <a href=\"https://docs.api.ai/docs/kik-integration\" target=\"_blank\">Kik</a>, <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack</a>, <a href=\"https://docs.api.ai/docs/telegram-integration\" target=\"_blank\">Telegram</a>, <a href=\"https://docs.api.ai/docs/skype-integration\" target=\"_blank\">Skype</a>, <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a>\n<br>- Custom integration implementations for other platforms.</div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Simple response</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Basic card</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">List</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Suggestion chips</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Carousel card</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>\n <div class=\"row\">\n <div class=\"col-md-3 col-sm-4 col-xs-12 cell cell-left\">Link out suggestion</div>\n <div class=\"col-md-8 col-sm-6 col-xs-12 cell\">One-click integration for <a href=\"https://docs.api.ai/docs/actions-on-google-integration\" target=\"_blank\">Actions on Google</a></div> \n </div>" } [/block] For more information on the response design for Actions on Google integration, read <a href="https://docs.api.ai/docs/response-design-for-actions-on-google" target="_blank">this documentation</a>. [block:api-header] { "type": "basic", "title": "Text response" } [/block] Your agent can send up to 10 sequential text messages in response to a user input (assuming no other message types are defined in the intent). These feature is supported in <a href="https://docs.api.ai/docs/facebook-integration" target="_blank">Facebook Messenger</a>, <a href="https://docs.api.ai/docs/kik-integration" target="_blank">Kik</a>, <a href="https://docs.api.ai/docs/slack-integration" target="_blank">Slack</a>, <a href="https://docs.api.ai/docs/telegram-integration" target="_blank">Telegram</a>, <a href="https://docs.api.ai/docs/skype-integration" target="_blank">Skype</a>, and <a href="https://docs.api.ai/docs/twilio-integration" target="_blank">Twilio</a> one-click integrations. Line breaks are currently supported for the following one-click integrations: <a href="https://docs.api.ai/docs/facebook-integration" target="_blank">Facebook Messenger</a>, <a href="https://docs.api.ai/docs/kik-integration" target="_blank">Kik</a>, <a href="https://docs.api.ai/docs/slack-integration" target="_blank">Slack</a>, <a href="https://docs.api.ai/docs/telegram-integration" target="_blank">Telegram</a>, and <a href="https://docs.api.ai/docs/skype-integration" target="_blank">Skype</a>. To add a new line in the UI, press Shift+Enter. If you <a href="https://docs.api.ai/docs/intents#post-intents" target="_blank">create intents via API</a>, use `\n` in the <a href="https://docs.api.ai/docs/intents#intent-object" target="_blank">intent object</a>. ``` "messages": [ { "type": 0, "speech": "Some text\nNext line" } ] ``` You can reference parameter values as described <a href="https://docs.api.ai/docs/concept-intents#section-references-to-parameter-values" target="_blank">here</a>. Text responses for Facebook Messenger integration have a 640 character limit. [block:api-header] { "type": "basic", "title": "Image" } [/block] The image message type lets your bots send images in one-click integrations for Facebook Messenger, Kik, Slack, and Telegram integrations. All you need to do is to store the image so that you can provide a public URL to it in your agent. Note that platforms differ with regards to the supported formats and sizes: - Facebook Messenger: JPG, PNG, and GIC (animated GIFs are supported). - Kik: JPG up to 1MB size (to send animated GIFs, use video format in Custom payload) - Slack: GIF, JPEG, PNG, and BMP - Telegram: 5 MB max size - Skype: PNG or JPEG up to 1024x1024, up to 1MB in size. For GIFs and images up to 20MB, use attachments in Custom payload. [block:api-header] { "type": "basic", "title": "Card" } [/block] Cards consist of several elements: - Image - Card title - Card subtitle - Interactive buttons (for sending user queries or opening links) You can combine these elements depending on the platform requirements. ## Cards in Facebook Messenger Cards correspond to a simplified <a href="https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template" target="_blank">Facebook Messenger generic template (bubble)</a>. In one-click Facebook Messenger integration, cards can contain the same elements as a generic template except `item_url`. Also, interactive button functions are limited to opening a URL or sending a query from the user. If you add several cards in the same intent, they are displayed in a horizontal scrollable carousel. The title field cannot be empty. Also, either the image URL or the button title is required. Buttons might be of the following types: - Title only (if tapped, the title text is sent as a user query) - Title with a URL to open - Title with text postback (when tapped, the text is sent as a user query) Button number is limited to 3. To add a new button, place the cursor in the button title field and press Enter. Be sure to check the `messages_postback` option in your Facebook app webhook settings. Title, subtitle, and button title have an 80 character limit. The image ratio is 1.91:1. ## Cards in Kik Since cards are not natively supported in Kik, they are sent as separate elements: image with title, subtitle as a text message, and buttons. For buttons, only a URL is supported as a postback – in this case, it is displayed as an image with linked URL. If you leave the postback field blank, when such a button is tapped, the button title is sent as a user query to the agent. ## Cards in Slack There are no mandatory fields for cards in Slack – any combination of elements can be used. Buttons with a URL and with a text postback are supported. Buttons with a URL are displayed as hyperlinks. ## Cards in Telegram Either the image URL field or the title field is mandatory. Buttons with a URL and with a text postback are supported. When tapped, a button with a URL will open a web page, whereas a button with text will send the text as a user query. ## Cards in Skype Either the image URL field or the title field or subtitle field is mandatory. Buttons with a URL and with a text postback are supported. When tapped, a button with a URL will open a web page, whereas a button with text will send the text as a user query. [block:api-header] { "type": "basic", "title": "Quick Replies" } [/block] Quick replies are displayed in messengers as clickable buttons with pre-defined user responses. When clicked, the button text is sent to the agent as a user query. You can add one ‘Quick replies’ element per intent. The maximum number of replies is 10. Each reply has a 20 character limit. ## Quick replies in Facebook Messenger Quick replies are supported in one-click Facebook Messenger integrations and correspond to a text version of <a href="https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies" target="_blank">Facebook Messenger quick replies</a>. When a user clicks one of the buttons, all buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation. ## Quick replies in Kik Quick replies are supported in one-click Kik integrations and correspond to a text version of <a href="https://dev.kik.com/#/docs/messaging#keyboards" target="_blank">Suggested response keyboards in Kik</a> with a reduced number of replies and characters. If you want to use a full version, you can do it through the [Custom payload](#custom-payload). When a user clicks one of the buttons, all buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation. ## Quick replies in Slack Quick replies are supported in one-click Slack integrations and correspond to a text version of <a href="https://api.slack.com/docs/message-buttons" target="_blank">Slack interactive buttons</a>. ## Quick replies in Telegram Quick replies in one-click Telegram integrations correspond to <a href="https://core.telegram.org/bots/api/#keyboardbutton" target="_blank">keyboard buttons in Telegram</a>. When a user clicks one of the buttons, the buttons are dismissed. This prevents the issue where users could click buttons that are attached to old messages in a conversation. ## Quick replies in Skype Quick replies in one-click Skype integrations correspond to buttons in Skype. [block:api-header] { "type": "basic", "title": "Custom payload" } [/block] You can send custom payloads in the JSON format provided in the platforms documentation. To send a custom payload to one-click integrations, use the following format: For Facebook Messenger: ``` { "facebook": { } } ``` For Kik: ``` { "kik": [{ }] } ``` For Slack: ``` { "slack": { } } ``` For Telegram: ``` { "telegram": { } } ``` For Skype: ``` { "skype": { } } ``` You can also send a custom payload to self-developed integrations. It won’t be processed by API.AI. You need to handle it in your business logic. ## Facebook Messenger custom payload samples ### Audio in one-click Facebook Messenger integration The following example sends a playable audio link from your agent to a one-click Facebook Messenger integration: ``` { "facebook": { "attachment": { "type": "audio", "payload": { "url": "https://example.com/audio/test.mp3" } } } } ``` The maximum audio file size is 10MB. ### Video in one-click Facebook Messenger integration The following example sends a playable video from your agent to a Facebook Messenger integration: ``` { "facebook": { "attachment": { "type": "video", "payload": { "url": "https://examples.api.ai/RichMessagesFiles/studebaker_1950.mp4" } } } } ``` ### Files in one-click Facebook Messenger integration The following example sends a file from your agent to a Facebook Messenger integration: ``` { "facebook": { "attachment": { "type": "file", "payload": { "url": "https://examples.api.ai/RichMessagesFiles/LoremIpsum.pdf" } } } } ``` ## Kik custom payload samples ### Gifs in one-click Kik integration The following payload example sends animated gifs: ``` { "kik": { "type": "video", "videoUrl": "https://raw.githubusercontent.com/svet4/images/master/img/create-an-intent.gif", "autoplay": true } } ``` For more information, see <a href="https://dev.kik.com/#/docs/messaging#video" target="_blank">Kik documentation</a>. ### Videos in one-click Kik integrations Your Kik bots can send playable videos. The Kik mobile client requires that all videos are in mp4 format with h264 video and aac audio. If you provide a video with different specifications, it will be transcoded, which greatly increases the time required to send your messages. For more, please read <a href="https://dev.kik.com/#/docs/messaging#video" target="_blank">Kik documentation</a>. The following example sends a playable video from your Kik bot to a Kik mobile client: ``` { "kik": { "type": "video", "videoUrl": "https://examples.api.ai/RichMessagesFiles/studebaker_1950.mp4", "autoplay": true } } ``` ## Slack custom payload samples ### Formatted text in one-click Slack integration Your Slack bots can send <a href="https://api.slack.com/docs/message-formatting#message_formatting" target="_blank">formatted text</a>, as the following example shows: ``` { "slack": { "text": "This is an example of *bold*, _italic_, and `code`." } } ``` ## Telegram custom payload samples ### Formatted text and hyperlinks in one-click Telegram integration Your Telegram bots can send formatted text and hyperlinks. The following example sends formatted text with a hyperlink using the Markdown parsing mode: ``` { "telegram": { "text": "You can read about *entities* [here](https://docs.api.ai/docs/concept-entities).", "parse_mode": "Markdown" } } ``` See the <a href="https://core.telegram.org/bots/api#formatting-options" target="_blank">Telegram documentation</a> for reference. ### Inline Keyboard Buttons in one-click Telegram integration The following example shows how you can define <a href="https://core.telegram.org/bots/api#inlinekeyboardmarkup" target="_blank">Inline Keyboard buttons</a> in the Custom payload element. ``` { "telegram": { "text": "Pick a color", "reply_markup": { "inline_keyboard": [ [ { "text": "Red", "callback_data": "Red" } ], [ { "text": "Green", "callback_data": "Green" } ], [ { "text": "Yellow", "callback_data": "Yellow" } ], [ { "text": "Blue", "callback_data": "Blue" } ], [ { "text": "Pink", "callback_data": "Pink" } ] ] } } } ``` ## Skype custom payload samples ### Formatted text and hyperlinks in one-click Skype integration The following example sends formatted text with a hyperlink using the default Markdown parsing mode: ``` { "skype": { "text": "You can read about **entities** [here](https://docs.api.ai/docs/concept-entities)." } } ``` ### Skype emoticons in one-click Skype integration See the list of available <a href="https://support.skype.com/en/faq/FA12330/what-is-the-full-list-of-emoticons" target="_blank">Skype emoticons</a>. ``` { "skype": { "text": "(heart) (penguin) (think) :)" } } ``` ### Attachments in one-click Skype integration ``` { "skype": { "attachments": [ { "contentType": "image/png", "contentUrl": "https://examples.api.ai/BobTheFlorist/bob_the_florist.png", "name": "Profile-picture.png" } ] } } ``` For more information on attachments, see the following <a href="https://docs.botframework.com/en-us/csharp/builder/sdkreference/attachments.html" target="_blank">Skype documentation</a>.