{"_id":"5845a4a99f6fbb1b004307ff","__v":0,"project":"54d3007669578e0d002730c9","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"},"user":"55bf6cdcad601c2b00762d13","category":{"_id":"5845a4a89f6fbb1b004307bd","project":"54d3007669578e0d002730c9","__v":0,"version":"5845a4a89f6fbb1b004307b7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-08T18:48:02.369Z","from_sync":false,"order":5,"slug":"integrations","title":"Integrations"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-01T01:01:37.173Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"- [Overview](#overview)\n- [Slack Test Bot](#slack-test-bot)\n- [Creating a Public Slack Bot](#creating-a-public-slack-bot)\n * [Create a Public Slack App](#section-create-a-slack-app)\n * [Add Bot User](#section-add-bot-user)\n * [Enable Event Subscriptions](#section-enable-event-subscriptions)\n * [Add Slack App Credentials to API.AI Slack Integration](#section-add-slack-app-credentials-to-api-ai-slack-integration)\n * [Add OAuth URL to Slack App](#section-add-oauth-url-to-slack-app)\n * [Add Event Request URL to Slack App](#section-add-event-request-url-to-slack-app)\n- [Add Your Slack Bot to a Slack Team](#add-your-slack-bot-to-a-slack-team)\n- [Using Rich Messages in Public Slack Bot](#using-rich-messages-in-public-slack-bot)\n[block:api-header]\n{\n  \"title\": \"Overview\"\n}\n[/block]\n**API.AI Slack Integration** makes it easy to create your <a href=\"https://api.slack.com/slack-apps\" target=\"_blank\">Slack apps</a> and <a href=\"https://api.slack.com/bot-users\" target=\"_blank\">Slack bots</a> and train them to understand natural language.\n\nYou can use our source code from <a href=\"https://github.com/api-ai/apiai-botkit-client/tree/master/samples/slack\">github</a> to create custom Slack bots.\n[block:api-header]\n{\n  \"title\": \"Slack Test Bot\"\n}\n[/block]\nSlack Integration allows you to test your integrated agent in Slack without creating a public bot. \n\nTo integrate your agent to a Slack test bot, click on ‘Integrations’ in the left hand menu and switch the toggle to enable Slack integration:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a5494af-NewSlackEnable.jpg\",\n        \"NewSlackEnable.jpg\",\n        2034,\n        740,\n        \"#faf3fa\"\n      ]\n    }\n  ]\n}\n[/block]\nIn the pop-up window, click ‘TEST IN SLACK’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f0299a8-NewSlackTestBot.jpg\",\n        \"NewSlackTestBot.jpg\",\n        2204,\n        690,\n        \"#475064\"\n      ]\n    }\n  ]\n}\n[/block]\nA pop-up appears and prompts you to login to Slack (if you haven't already). Login to the Slack instance you'd like to test on. You may need to choose which Slack instance to test if you're logged into multiple Slack instances. Click Authorize to authorize API.AI to access your Slack instance.\n\nGo to the Slack instance you'd like to test on and find the bot user called :::at:::apiai_bot. You can now test your API.AI agent in Slack by messaging @apiai_bot via direct messages or add the @apiai_bot to channels and starting each message to the bot by @apiai_bot.\n\nTo change your bot display name and avatar, you need to make your bot public.\n\n[block:api-header]\n{\n  \"title\": \"Creating a Public Slack Bot\"\n}\n[/block]\n## Create a Slack App\n\nGo to https://api.slack.com/apps/new to create a new Slack app. Enter a name for your app as well as the Slack instance it will be connected to for testing and then click ‘Create App’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4bfc580-NewSlackCreateSlackApp.jpg\",\n        \"NewSlackCreateSlackApp.jpg\",\n        2116,\n        1282,\n        \"#ededed\"\n      ]\n    }\n  ]\n}\n[/block]\n## Add Bot User\n\nClick ‘Bot Users’ in the menu on the left of the page (or in the menu hidden by the <i class=\"fa fa-bars\" aria-hidden=\"true\"></i> button in the upper left corner) and then ‘Add a Bot User’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0f992c0-NewSlackBotUsers.jpg\",\n        \"NewSlackBotUsers.jpg\",\n        2370,\n        1140,\n        \"#fbfafb\"\n      ]\n    }\n  ]\n}\n[/block]\nEnter a name for your Slack bot (users will see this name when they add your bot), turn on ‘Always Show My Bot as Online’, and click ‘Add Bot User’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6ae8d07-NewSlackAddBotUser.jpg\",\n        \"NewSlackAddBotUser.jpg\",\n        2370,\n        1262,\n        \"#f9f9f9\"\n      ]\n    }\n  ]\n}\n[/block]\n## Enable Event Subscriptions\n\nGo to ‘Event Subscriptions’ in the menu on the left of the page (or in the menu hidden by the <i class=\"fa fa-bars\" aria-hidden=\"true\"></i> button in the upper left corner) and click on the ‘Off’ button to enable events:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4c4685b-NewSlackEventSubscriptions.jpg\",\n        \"NewSlackEventSubscriptions.jpg\",\n        2360,\n        1104,\n        \"#fafafb\"\n      ]\n    }\n  ]\n}\n[/block]\nThen scroll down to the ‘Subscribe to Bot Events’ section and click ‘Add Bot User Event’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3ef55a3-NewSlackSubscribeToBotEvents.jpg\",\n        \"NewSlackSubscribeToBotEvents.jpg\",\n        2294,\n        648,\n        \"#f9f9f9\"\n      ]\n    }\n  ]\n}\n[/block]\nSearch and add events that you'd like your bot to respond to. Here’s the list of events you may need:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event Name\",\n    \"h-1\": \"Event Description\",\n    \"0-0\": \"message.im\",\n    \"0-1\": \"A message was posted in a direct message channel\",\n    \"1-0\": \"message.groups\",\n    \"1-1\": \"A message was posted to a private channel\",\n    \"2-0\": \"message.channels\",\n    \"2-1\": \"A message was posted to a channel\",\n    \"3-0\": \"im_created\",\n    \"3-1\": \"A DM was created\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nAfter all necessary events has been added, click ‘Save Changes’ at the bottom of the page:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ccd75d0-NewSlackSaveEvents.jpg\",\n        \"NewSlackSaveEvents.jpg\",\n        2244,\n        1156,\n        \"#faf9fa\"\n      ]\n    }\n  ]\n}\n[/block]\n## Add Slack App Credentials to API.AI Slack Integration\n\nIn the Slack app, click  ‘Basic Information’ in the menu on the left of the page (or in the menu hidden by the <i class=\"fa fa-bars\" aria-hidden=\"true\"></i> button in the  upper left corner) and scroll down to the section labeled ‘App Credentials’. Click ‘Show’ in the box titled ‘Client Secret’ to view and copy the client secret. You’ll need to copy this credentials and paste to your Slack Integration settings.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cf61bef-NewSlackAppCredentials.jpg\",\n        \"NewSlackAppCredentials.jpg\",\n        1412,\n        1256,\n        \"#f8f8f8\"\n      ]\n    }\n  ]\n}\n[/block]\nIn the API.AI developer console, go to ‘Integrations’ in the left hand menu and open ‘Slack’ settings. Copy the Client ID, Client Secret, and Verification Token from Slack app into API.AI and click ‘START’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/577ca2e-NewSlackIntegrationSettings.jpg\",\n        \"NewSlackIntegrationSettings.jpg\",\n        2174,\n        1382,\n        \"#495063\"\n      ]\n    }\n  ]\n}\n[/block]\n## Add OAuth URL to Slack App\n\nCopy the ‘OAuth URL’ in the API.AI Slack Integration settings. Go to your Slack app settings and click ‘OAuth & Permissions’ in the menu on the left of the page and click ‘Add a New Redirect URL’ in the ‘Redirect URLs’ section.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0e0bf9d-NewSlackAddRedirectURL.jpg\",\n        \"NewSlackAddRedirectURL.jpg\",\n        2378,\n        1318,\n        \"#faf9fa\"\n      ]\n    }\n  ]\n}\n[/block]\nInsert the OAuth URL value that you copied in the Slack Integration settings and click ’Add’ and ‘Save URLs’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b3f0c99-NewSlackAddRedirectAndSave.jpg\",\n        \"NewSlackAddRedirectAndSave.jpg\",\n        2340,\n        1450,\n        \"#f8f8f8\"\n      ]\n    }\n  ]\n}\n[/block]\n## Add Event Request URL to Slack App\n\nIn the API.AI Slack Integration settings, copy Event Request URL. Go to your Slack app settings and click ‘Event Subscription’ in the menu on the left of the page. Enter the API.AI ‘Events Request URL’ copied from API.AI earlier. After you click outside the textbox, Slack will test the URL and after a moment you should see a ‘Verified’ label above the textbox as seen below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ca084b8-NewSlackEventRequestURLVerified.jpg\",\n        \"NewSlackEventRequestURLVerified.jpg\",\n        2362,\n        1146,\n        \"#f9f9f9\"\n      ]\n    }\n  ]\n}\n[/block]\nMake sure events are still enabled and the switch is turned to the ‘On’ position and click ‘Save Changes’ at the bottom of the page.\n[block:api-header]\n{\n  \"title\": \"Add Your Slack Bot to a Slack Team\"\n}\n[/block]\nYou API.AI powered Slack integration is now ready!  In Slack's API console, click ‘Manage Distribution’ in the menu on the left of the page and click the ‘Add to Slack’ button:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/59d342f-NewSlackManageDistribution.jpg\",\n        \"NewSlackManageDistribution.jpg\",\n        2390,\n        1112,\n        \"#f9f8f9\"\n      ]\n    }\n  ]\n}\n[/block]\nA popup will appear requesting you give your app access to your Slack instance. Click ‘Authorize’ to approve access after which you should see a page with the message ‘Bot connection success’.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1c21c84-NewSlackAddToYourTEam.png\",\n        \"NewSlackAddToYourTEam.png\",\n        1038,\n        1054,\n        \"#fafafa\"\n      ]\n    }\n  ]\n}\n[/block]\nYou can now send messages to your API.AI powered bot in Slack! Your Slack bot will be identified by the name you specified when created your Slack app (or a similar name if your Slack instance already has a bot or user of the same name).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please note that installing your integration by clicking ‘Install App to Team’ in Slack's API console in the ‘Install App’ page or ‘OAuth & Permissions’ page will prevent your bot from working and you will have to create a new Slack app for the integration to work on your Slack instance.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using Rich Messages in Public Slack Bot\"\n}\n[/block]\nTo be able to use buttons in your public Slack bot, go to Slack's API console and click on the ‘Interactive Messages’. Then click ‘Enable Interactive Messages’ and enter your API.AI's provided 'Events Request URL' in the Request URL box and clicking ‘Enable Interactive Messages’:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a0a7fbb-NewSlackInteractiveMessages.jpg\",\n        \"NewSlackInteractiveMessages.jpg\",\n        2368,\n        932,\n        \"#f8f8f8\"\n      ]\n    }\n  ]\n}\n[/block]\nRead more about <a href=\"https://docs.api.ai/docs/rich-messages\" target=\"_blank\">rich messages</a>.","excerpt":"","slug":"slack-integration","type":"basic","title":"Slack"}
- [Overview](#overview) - [Slack Test Bot](#slack-test-bot) - [Creating a Public Slack Bot](#creating-a-public-slack-bot) * [Create a Public Slack App](#section-create-a-slack-app) * [Add Bot User](#section-add-bot-user) * [Enable Event Subscriptions](#section-enable-event-subscriptions) * [Add Slack App Credentials to API.AI Slack Integration](#section-add-slack-app-credentials-to-api-ai-slack-integration) * [Add OAuth URL to Slack App](#section-add-oauth-url-to-slack-app) * [Add Event Request URL to Slack App](#section-add-event-request-url-to-slack-app) - [Add Your Slack Bot to a Slack Team](#add-your-slack-bot-to-a-slack-team) - [Using Rich Messages in Public Slack Bot](#using-rich-messages-in-public-slack-bot) [block:api-header] { "title": "Overview" } [/block] **API.AI Slack Integration** makes it easy to create your <a href="https://api.slack.com/slack-apps" target="_blank">Slack apps</a> and <a href="https://api.slack.com/bot-users" target="_blank">Slack bots</a> and train them to understand natural language. You can use our source code from <a href="https://github.com/api-ai/apiai-botkit-client/tree/master/samples/slack">github</a> to create custom Slack bots. [block:api-header] { "title": "Slack Test Bot" } [/block] Slack Integration allows you to test your integrated agent in Slack without creating a public bot. To integrate your agent to a Slack test bot, click on ‘Integrations’ in the left hand menu and switch the toggle to enable Slack integration: [block:image] { "images": [ { "image": [ "https://files.readme.io/a5494af-NewSlackEnable.jpg", "NewSlackEnable.jpg", 2034, 740, "#faf3fa" ] } ] } [/block] In the pop-up window, click ‘TEST IN SLACK’: [block:image] { "images": [ { "image": [ "https://files.readme.io/f0299a8-NewSlackTestBot.jpg", "NewSlackTestBot.jpg", 2204, 690, "#475064" ] } ] } [/block] A pop-up appears and prompts you to login to Slack (if you haven't already). Login to the Slack instance you'd like to test on. You may need to choose which Slack instance to test if you're logged into multiple Slack instances. Click Authorize to authorize API.AI to access your Slack instance. Go to the Slack instance you'd like to test on and find the bot user called @apiai_bot. You can now test your API.AI agent in Slack by messaging @apiai_bot via direct messages or add the @apiai_bot to channels and starting each message to the bot by @apiai_bot. To change your bot display name and avatar, you need to make your bot public. [block:api-header] { "title": "Creating a Public Slack Bot" } [/block] ## Create a Slack App Go to https://api.slack.com/apps/new to create a new Slack app. Enter a name for your app as well as the Slack instance it will be connected to for testing and then click ‘Create App’: [block:image] { "images": [ { "image": [ "https://files.readme.io/4bfc580-NewSlackCreateSlackApp.jpg", "NewSlackCreateSlackApp.jpg", 2116, 1282, "#ededed" ] } ] } [/block] ## Add Bot User Click ‘Bot Users’ in the menu on the left of the page (or in the menu hidden by the <i class="fa fa-bars" aria-hidden="true"></i> button in the upper left corner) and then ‘Add a Bot User’: [block:image] { "images": [ { "image": [ "https://files.readme.io/0f992c0-NewSlackBotUsers.jpg", "NewSlackBotUsers.jpg", 2370, 1140, "#fbfafb" ] } ] } [/block] Enter a name for your Slack bot (users will see this name when they add your bot), turn on ‘Always Show My Bot as Online’, and click ‘Add Bot User’: [block:image] { "images": [ { "image": [ "https://files.readme.io/6ae8d07-NewSlackAddBotUser.jpg", "NewSlackAddBotUser.jpg", 2370, 1262, "#f9f9f9" ] } ] } [/block] ## Enable Event Subscriptions Go to ‘Event Subscriptions’ in the menu on the left of the page (or in the menu hidden by the <i class="fa fa-bars" aria-hidden="true"></i> button in the upper left corner) and click on the ‘Off’ button to enable events: [block:image] { "images": [ { "image": [ "https://files.readme.io/4c4685b-NewSlackEventSubscriptions.jpg", "NewSlackEventSubscriptions.jpg", 2360, 1104, "#fafafb" ] } ] } [/block] Then scroll down to the ‘Subscribe to Bot Events’ section and click ‘Add Bot User Event’: [block:image] { "images": [ { "image": [ "https://files.readme.io/3ef55a3-NewSlackSubscribeToBotEvents.jpg", "NewSlackSubscribeToBotEvents.jpg", 2294, 648, "#f9f9f9" ] } ] } [/block] Search and add events that you'd like your bot to respond to. Here’s the list of events you may need: [block:parameters] { "data": { "h-0": "Event Name", "h-1": "Event Description", "0-0": "message.im", "0-1": "A message was posted in a direct message channel", "1-0": "message.groups", "1-1": "A message was posted to a private channel", "2-0": "message.channels", "2-1": "A message was posted to a channel", "3-0": "im_created", "3-1": "A DM was created" }, "cols": 2, "rows": 4 } [/block] After all necessary events has been added, click ‘Save Changes’ at the bottom of the page: [block:image] { "images": [ { "image": [ "https://files.readme.io/ccd75d0-NewSlackSaveEvents.jpg", "NewSlackSaveEvents.jpg", 2244, 1156, "#faf9fa" ] } ] } [/block] ## Add Slack App Credentials to API.AI Slack Integration In the Slack app, click ‘Basic Information’ in the menu on the left of the page (or in the menu hidden by the <i class="fa fa-bars" aria-hidden="true"></i> button in the upper left corner) and scroll down to the section labeled ‘App Credentials’. Click ‘Show’ in the box titled ‘Client Secret’ to view and copy the client secret. You’ll need to copy this credentials and paste to your Slack Integration settings. [block:image] { "images": [ { "image": [ "https://files.readme.io/cf61bef-NewSlackAppCredentials.jpg", "NewSlackAppCredentials.jpg", 1412, 1256, "#f8f8f8" ] } ] } [/block] In the API.AI developer console, go to ‘Integrations’ in the left hand menu and open ‘Slack’ settings. Copy the Client ID, Client Secret, and Verification Token from Slack app into API.AI and click ‘START’: [block:image] { "images": [ { "image": [ "https://files.readme.io/577ca2e-NewSlackIntegrationSettings.jpg", "NewSlackIntegrationSettings.jpg", 2174, 1382, "#495063" ] } ] } [/block] ## Add OAuth URL to Slack App Copy the ‘OAuth URL’ in the API.AI Slack Integration settings. Go to your Slack app settings and click ‘OAuth & Permissions’ in the menu on the left of the page and click ‘Add a New Redirect URL’ in the ‘Redirect URLs’ section. [block:image] { "images": [ { "image": [ "https://files.readme.io/0e0bf9d-NewSlackAddRedirectURL.jpg", "NewSlackAddRedirectURL.jpg", 2378, 1318, "#faf9fa" ] } ] } [/block] Insert the OAuth URL value that you copied in the Slack Integration settings and click ’Add’ and ‘Save URLs’: [block:image] { "images": [ { "image": [ "https://files.readme.io/b3f0c99-NewSlackAddRedirectAndSave.jpg", "NewSlackAddRedirectAndSave.jpg", 2340, 1450, "#f8f8f8" ] } ] } [/block] ## Add Event Request URL to Slack App In the API.AI Slack Integration settings, copy Event Request URL. Go to your Slack app settings and click ‘Event Subscription’ in the menu on the left of the page. Enter the API.AI ‘Events Request URL’ copied from API.AI earlier. After you click outside the textbox, Slack will test the URL and after a moment you should see a ‘Verified’ label above the textbox as seen below: [block:image] { "images": [ { "image": [ "https://files.readme.io/ca084b8-NewSlackEventRequestURLVerified.jpg", "NewSlackEventRequestURLVerified.jpg", 2362, 1146, "#f9f9f9" ] } ] } [/block] Make sure events are still enabled and the switch is turned to the ‘On’ position and click ‘Save Changes’ at the bottom of the page. [block:api-header] { "title": "Add Your Slack Bot to a Slack Team" } [/block] You API.AI powered Slack integration is now ready! In Slack's API console, click ‘Manage Distribution’ in the menu on the left of the page and click the ‘Add to Slack’ button: [block:image] { "images": [ { "image": [ "https://files.readme.io/59d342f-NewSlackManageDistribution.jpg", "NewSlackManageDistribution.jpg", 2390, 1112, "#f9f8f9" ] } ] } [/block] A popup will appear requesting you give your app access to your Slack instance. Click ‘Authorize’ to approve access after which you should see a page with the message ‘Bot connection success’. [block:image] { "images": [ { "image": [ "https://files.readme.io/1c21c84-NewSlackAddToYourTEam.png", "NewSlackAddToYourTEam.png", 1038, 1054, "#fafafa" ] } ] } [/block] You can now send messages to your API.AI powered bot in Slack! Your Slack bot will be identified by the name you specified when created your Slack app (or a similar name if your Slack instance already has a bot or user of the same name). [block:callout] { "type": "warning", "body": "Please note that installing your integration by clicking ‘Install App to Team’ in Slack's API console in the ‘Install App’ page or ‘OAuth & Permissions’ page will prevent your bot from working and you will have to create a new Slack app for the integration to work on your Slack instance." } [/block] [block:api-header] { "title": "Using Rich Messages in Public Slack Bot" } [/block] To be able to use buttons in your public Slack bot, go to Slack's API console and click on the ‘Interactive Messages’. Then click ‘Enable Interactive Messages’ and enter your API.AI's provided 'Events Request URL' in the Request URL box and clicking ‘Enable Interactive Messages’: [block:image] { "images": [ { "image": [ "https://files.readme.io/a0a7fbb-NewSlackInteractiveMessages.jpg", "NewSlackInteractiveMessages.jpg", 2368, 932, "#f8f8f8" ] } ] } [/block] Read more about <a href="https://docs.api.ai/docs/rich-messages" target="_blank">rich messages</a>.