{"__v":0,"_id":"5845a4aa9f6fbb1b00430841","category":{"version":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","_id":"5845a4a89f6fbb1b004307bf","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-26T17:19:04.989Z","from_sync":false,"order":7,"slug":"guidelines","title":"Guidelines"},"parentDoc":null,"project":"54d3007669578e0d002730c9","user":"55bf6cdcad601c2b00762d13","version":{"__v":1,"_id":"5845a4a89f6fbb1b004307b7","project":"54d3007669578e0d002730c9","createdAt":"2016-12-05T17:32:24.708Z","releaseDate":"2016-12-05T17:32:24.708Z","categories":["5845a4a89f6fbb1b004307b8","5845a4a89f6fbb1b004307b9","5845a4a89f6fbb1b004307ba","5845a4a89f6fbb1b004307bb","5845a4a89f6fbb1b004307bc","5845a4a89f6fbb1b004307bd","5845a4a89f6fbb1b004307be","5845a4a89f6fbb1b004307bf","5845a4a89f6fbb1b004307c0"],"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-04-24T21:49:44.260Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"* [Overview](#overview)\n* [Sending Formatted Data from the Web Service](#sending-formatted-data-from-the-web-service)\n* [Deploying the Web Service](#deploying-the-web-service)\n* [Creating an Agent and Enabling Webhook](#creating-an-agent-and-enabling-webhook)\n* [Creating and Testing Your Slack Bot](#creating-and-testing-your-slack-bot)\n* [Making Your Bot Public](#making-your-bot-public)\n* [Related Topics](#related-topics)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThis example shows how to create a weather Slack bot using <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">API.AI Slack Integration</a> in a combination with a <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">webhook</a> for the Yahoo Weather API service.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"A separate webhook example for the Yahoo Weather API service can be found  <a href=\\\"https://docs.api.ai/docs/webhook#webhook-example\\\" target=\\\"_blank\\\">here</a>.\"\n}\n[/block]\nOur Slack bot will be able to respond weather related questions in such a beautiful format:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cecPzNXR32JtN552spxP_slack-bot-response-sample.png\",\n        \"slack-bot-response-sample.png\",\n        \"1756\",\n        \"480\",\n        \"#318e8b\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sending Formatted Data from the Web Service\"\n}\n[/block]\nIn order to send formatted data from the web service, we need to define the message format in the `“data”` field in the  <a href=\"https://docs.api.ai/docs/webhook#section-format-of-response-from-the-service\" target=\"_blank\">response from the service</a>.\n\nThe Slack bot message format is described in the following Slack documentation:\n\n- <a href=\"https://api.slack.com/docs/attachments\" target=\"_blank\">https://api.slack.com/docs/attachments</a>\n\n- <a href=\"https://api.slack.com/docs/formatting#formatting_and_attachments \" target=\"_blank\">https://api.slack.com/docs/formatting#formatting_and_attachments</a>\n\nFor Slack bots, in the `“data”` field in the response from the service, the message format should be defined as the value for the `“slack”` field:\n```\n\"data\": {\"slack\": {<slack_message>}}\n```\n\nIn our example, the message format is already defined and looks like this:\n\n    slack_message = {\n        \"text\": speech,\n        \"attachments\": [\n            {\n                \"title\": channel.get('title'),\n                \"title_link\": channel.get('link'),\n                \"color\": \"#36a64f\",\n\n                \"fields\": [\n                    {\n                        \"title\": \"Condition\",\n                        \"value\": \"Temp \" + condition.get('temp') +\n                                 \" \" + units.get('temperature'),\n                        \"short\": \"false\"\n                    },\n                    {\n                        \"title\": \"Wind\",\n                        \"value\": \"Speed: \" + channel.get('wind').get('speed') +\n                                 \", direction: \" + channel.get('wind').get('direction'),\n                        \"short\": \"true\"\n                    },\n                    {\n                        \"title\": \"Atmosphere\",\n                        \"value\": \"Humidity \" + channel.get('atmosphere').get('humidity') +\n                                 \" pressure \" + channel.get('atmosphere').get('pressure'),\n                        \"short\": \"true\"\n                    }\n                ],\n\n                \"thumb_url\": \"http://l.yimg.com/a/i/us/we/52/\" + condition.get('code') + \".gif\"\n            }\n        ]\n    }\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Deploying the Web Service\"\n}\n[/block]\nLog in or sign up to <a href=\"https://www.heroku.com/\" target=\"_blank\">Heroku</a>.\n\nGo to <a href=\"https://github.com/xVir/apiai-slack-richformatting\" target=\"_blank\">https://github.com/xVir/apiai-slack-richformatting</a> and click 'Deploy to Heroku' button.\n\nHeroku website will open, and you’ll be asked to fill in the app name. Insert the app name (in our example, it’s “yahoo-weather”, but you can choose your own name) and click 'Deploy for Free' button.\n\nWait until 'Your app was successfully deployed.' appears.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating an Agent and Enabling Webhook\"\n}\n[/block]\n<a href=\"https://console.api.ai/api-client/#/newAgent\" target=\"_blank\">Create an API.AI agent</a> and enable webhook: \n- Click on Fulfillment in the left side menu\n- Turn Webhook on\n- Insert the link `https://[App Name].herokuapp.com/webhook` into the ‘URL’ field\n- Click ‘Save’.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/zZCFN2CTRa36XTRIrbV0_slak_webhook-enable_webhook.png\",\n        \"slak_webhook-enable_webhook.png\",\n        \"2050\",\n        \"1256\",\n        \"#2d9adf\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\nCreate an <a href=\"https://docs.api.ai/docs/concept-intents\" target=\"_blank\">intent</a> that will match weather requests. The intent should have the `geo-city` parameter. The action should be defined as `yahooWeatherForecast`.\n\nMake sure the ‘Enable webhook for this intent’ option in the ‘Speech Response’ section is checked.\n\nIn the ‘Speech Response’ field, define the response that will appear in case of <a href=\"https://docs.api.ai/docs/webhook#section-errors\" target=\"_blank\">web service errors</a>.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/gI7BWqYFR0a0lPHnZ5Mf_intent-weather.png\",\n        \"intent-weather.png\",\n        \"1999\",\n        \"1387\",\n        \"#228d50\",\n        \"\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating and Testing Your Slack Bot\"\n}\n[/block]\nСlick ‘Integrations’ from the left side menu and turn Slack integration on.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cJ6SqbISNSxQVUoQxk4i_Slack-integration-enable.png\",\n        \"Slack-integration-enable.png\",\n        \"2078\",\n        \"986\",\n        \"#2d9be0\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nTo define the way people can interact with your bot, tick the relevant checkboxes in the ‘Message Types’ section.\n\n* **Direct message.** The bot will receive a direct message from a user.\n* **Direct mention.** The bot will answer when mentioned at the beginning of a message.\n* **Mention**. The bot will answer when mentioned in any part of a message.\n* **Ambient**. The bot will monitor any message in a channel.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ULX8YWsWTNk9M5DZYx3z_Slack-message-type.png\",\n        \"Slack-message-type.png\",\n        \"2220\",\n        \"800\",\n        \"#143b5b\",\n        \"\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\nBefore publishing your agent as a Slack bot or App, you can run it in test mode. To do this, connect it to your Slack account by clicking 'Test in Slack' and then signing in with your team account. The API.AI Bot will appear in your Slack team members list.\n\nTo stop the test, click the ‘Shutdown test bot’ button.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Making Your Bot Public\"\n}\n[/block]\nTo make your bot public, follow the instructions <a href=\"https://docs.api.ai/docs/slack-integration#making-your-bot-public\" target=\"_blank\">here</a>.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Related Topics\"\n}\n[/block]\n- <a href=\"https://docs.api.ai/docs/webhook\" target=\"_blank\">Webhook Integration</a>\n- <a href=\"https://docs.api.ai/docs/slack-integration\" target=\"_blank\">Slack Integration</a>","excerpt":"","slug":"slack-webhook-integration-guideline","type":"basic","title":"Slack + Webhook Integration Example"}

Slack + Webhook Integration Example


* [Overview](#overview) * [Sending Formatted Data from the Web Service](#sending-formatted-data-from-the-web-service) * [Deploying the Web Service](#deploying-the-web-service) * [Creating an Agent and Enabling Webhook](#creating-an-agent-and-enabling-webhook) * [Creating and Testing Your Slack Bot](#creating-and-testing-your-slack-bot) * [Making Your Bot Public](#making-your-bot-public) * [Related Topics](#related-topics) [block:api-header] { "type": "basic", "title": "Overview" } [/block] This example shows how to create a weather Slack bot using <a href="https://docs.api.ai/docs/slack-integration" target="_blank">API.AI Slack Integration</a> in a combination with a <a href="https://docs.api.ai/docs/webhook" target="_blank">webhook</a> for the Yahoo Weather API service. [block:callout] { "type": "info", "body": "A separate webhook example for the Yahoo Weather API service can be found <a href=\"https://docs.api.ai/docs/webhook#webhook-example\" target=\"_blank\">here</a>." } [/block] Our Slack bot will be able to respond weather related questions in such a beautiful format: [block:image] { "images": [ { "image": [ "https://files.readme.io/cecPzNXR32JtN552spxP_slack-bot-response-sample.png", "slack-bot-response-sample.png", "1756", "480", "#318e8b", "" ], "sizing": "full" } ] } [/block] [block:api-header] { "type": "basic", "title": "Sending Formatted Data from the Web Service" } [/block] In order to send formatted data from the web service, we need to define the message format in the `“data”` field in the <a href="https://docs.api.ai/docs/webhook#section-format-of-response-from-the-service" target="_blank">response from the service</a>. The Slack bot message format is described in the following Slack documentation: - <a href="https://api.slack.com/docs/attachments" target="_blank">https://api.slack.com/docs/attachments</a> - <a href="https://api.slack.com/docs/formatting#formatting_and_attachments " target="_blank">https://api.slack.com/docs/formatting#formatting_and_attachments</a> For Slack bots, in the `“data”` field in the response from the service, the message format should be defined as the value for the `“slack”` field: ``` "data": {"slack": {<slack_message>}} ``` In our example, the message format is already defined and looks like this: slack_message = { "text": speech, "attachments": [ { "title": channel.get('title'), "title_link": channel.get('link'), "color": "#36a64f", "fields": [ { "title": "Condition", "value": "Temp " + condition.get('temp') + " " + units.get('temperature'), "short": "false" }, { "title": "Wind", "value": "Speed: " + channel.get('wind').get('speed') + ", direction: " + channel.get('wind').get('direction'), "short": "true" }, { "title": "Atmosphere", "value": "Humidity " + channel.get('atmosphere').get('humidity') + " pressure " + channel.get('atmosphere').get('pressure'), "short": "true" } ], "thumb_url": "http://l.yimg.com/a/i/us/we/52/" + condition.get('code') + ".gif" } ] } [block:api-header] { "type": "basic", "title": "Deploying the Web Service" } [/block] Log in or sign up to <a href="https://www.heroku.com/" target="_blank">Heroku</a>. Go to <a href="https://github.com/xVir/apiai-slack-richformatting" target="_blank">https://github.com/xVir/apiai-slack-richformatting</a> and click 'Deploy to Heroku' button. Heroku website will open, and you’ll be asked to fill in the app name. Insert the app name (in our example, it’s “yahoo-weather”, but you can choose your own name) and click 'Deploy for Free' button. Wait until 'Your app was successfully deployed.' appears. [block:api-header] { "type": "basic", "title": "Creating an Agent and Enabling Webhook" } [/block] <a href="https://console.api.ai/api-client/#/newAgent" target="_blank">Create an API.AI agent</a> and enable webhook: - Click on Fulfillment in the left side menu - Turn Webhook on - Insert the link `https://[App Name].herokuapp.com/webhook` into the ‘URL’ field - Click ‘Save’. [block:image] { "images": [ { "image": [ "https://files.readme.io/zZCFN2CTRa36XTRIrbV0_slak_webhook-enable_webhook.png", "slak_webhook-enable_webhook.png", "2050", "1256", "#2d9adf", "" ], "sizing": "80" } ] } [/block] Create an <a href="https://docs.api.ai/docs/concept-intents" target="_blank">intent</a> that will match weather requests. The intent should have the `geo-city` parameter. The action should be defined as `yahooWeatherForecast`. Make sure the ‘Enable webhook for this intent’ option in the ‘Speech Response’ section is checked. In the ‘Speech Response’ field, define the response that will appear in case of <a href="https://docs.api.ai/docs/webhook#section-errors" target="_blank">web service errors</a>. [block:image] { "images": [ { "image": [ "https://files.readme.io/gI7BWqYFR0a0lPHnZ5Mf_intent-weather.png", "intent-weather.png", "1999", "1387", "#228d50", "" ], "sizing": "80" } ] } [/block] [block:api-header] { "type": "basic", "title": "Creating and Testing Your Slack Bot" } [/block] Сlick ‘Integrations’ from the left side menu and turn Slack integration on. [block:image] { "images": [ { "image": [ "https://files.readme.io/cJ6SqbISNSxQVUoQxk4i_Slack-integration-enable.png", "Slack-integration-enable.png", "2078", "986", "#2d9be0", "" ], "sizing": "full" } ] } [/block] To define the way people can interact with your bot, tick the relevant checkboxes in the ‘Message Types’ section. * **Direct message.** The bot will receive a direct message from a user. * **Direct mention.** The bot will answer when mentioned at the beginning of a message. * **Mention**. The bot will answer when mentioned in any part of a message. * **Ambient**. The bot will monitor any message in a channel. [block:image] { "images": [ { "image": [ "https://files.readme.io/ULX8YWsWTNk9M5DZYx3z_Slack-message-type.png", "Slack-message-type.png", "2220", "800", "#143b5b", "" ], "sizing": "full" } ] } [/block] Before publishing your agent as a Slack bot or App, you can run it in test mode. To do this, connect it to your Slack account by clicking 'Test in Slack' and then signing in with your team account. The API.AI Bot will appear in your Slack team members list. To stop the test, click the ‘Shutdown test bot’ button. [block:api-header] { "type": "basic", "title": "Making Your Bot Public" } [/block] To make your bot public, follow the instructions <a href="https://docs.api.ai/docs/slack-integration#making-your-bot-public" target="_blank">here</a>. [block:api-header] { "type": "basic", "title": "Related Topics" } [/block] - <a href="https://docs.api.ai/docs/webhook" target="_blank">Webhook Integration</a> - <a href="https://docs.api.ai/docs/slack-integration" target="_blank">Slack Integration</a>