// This module is included in the following assemblies:
// as_connecting-to-slack.adoc

[id='creating-slack-connections_{context}']
= Creating a Slack connection

In an integration, a Slack connection can retrieve messages from a 
channel that you specify or send a message to a channel or user. 
You can use the same Slack connection in any number of integrations. 

.Prerequisites

* https://api.slack.com/apps[Create and install a Slack app] for connecting {prodname} to Slack:
** Use the *Bot User OAuth Access Token* as the token for the consumer endpoint.
** Add the relevant user token scope to your app to grant it permission to view messages:
+
history (`channels:history`, `groups:history`, `mpim:history`, or `im:history`)
+
read (`channels:read`, `groups:read`, `mpim:read`, or `im:read`)
* You can obtain the Slack webhook URL for your Slack app.
* You can obtain the *Bot User OAuth Access Token* that authorizes access to your Slack app.

.Procedure

. In {prodname}, in the left panel, click *Connections* to
display any available connections.
. Click *Create Connection* to display
{prodname} connectors.
. Click the *Slack* connector.
. In the *Slack webhook URL* field, enter the webhook URL for your 
Slack app. 
. In the *Token for accessing Slack API* field, enter the *Bot User OAuth Access Token*, which you can obtain from the Slack app's *OAuth & Permissions* page.
. Optionally, enter values for additional parameters:
+
* In the *Sending username for messages* field, enter the user name that 
the bot has when it sends messages to Slack.
*  In the *Message avatar emoji* field, specify one emoji, which the bot
uses as the message avatar when it sends a message. Examples:
*`:smile:`*, *`:wave:`*, *`:question:`*.

+
TIP: Search the web for *emoji cheat sheet* to see some emoji codes.
 
* In the *Message avatar icon URL* field, specify the URL of 
the avatar that the bot uses when it sends messages to Slack. 

+
If you specify an emoji and an icon URL, then the integration uses the
icon URL.  If you specify neither an emoji nor an icon URL, then the message 
is sent without an avatar. 
. Click *Validate*. {prodname} immediately tries to validate the 
connection and displays a message that indicates whether 
validation is successful. If validation fails, revise the
connection configuration values and try again.
. If validation is successful, click *Next*.
. In the *Name* field, enter your choice of a name that
helps you distinguish this connection from any other connections.
For example, enter `*Slack for Tracking Company Sales*`.
. In the *Description* field, optionally enter any information that
is helpful to know about this connection.
. Click *Save* to see the updated list of available 
connections, including the connection that you just created. 
If you entered the example name, you would
see that *Slack for Tracking Company Sales* appears as a connection that you can 
choose to add to an integration. You can add this connection to 
any number of integrations. 
