Slack Destination

Slack is a team collaboration tool where work flows. It’s where the people you need, the information you share, and the tools you use come together to get things done.

This document was last updated on January 25, 2018. If you notice any gaps, out-dated information or simply want to leave some feedback to help us improve our documentation, let us know!

Getting Started

Before you start, make sure Slack supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

1. From the Segment web app, click Catalog.
2. Search for “Slack” in the Catalog, select it, and choose which of your sources to connect the destination to.
3. In your Slack custom integration settings, create a new Incoming Webhook URL by selecting a Slack channel associated with your account.
4. Enter this in your Segment UI settings under ‘Incoming Webhook URL’. The Slack channel you selected will be the default channel which will receive events.

Identify

If you’re not familiar with the Segment Specs, take a look to understand what the Identify method does. An example call would look like:

analytics.identify('userId123', {
  name: 'John Doe',
  email: 'john.doe@example.com'
});

Whitelisted Traits

By default, your identify calls will not be sent through to Slack unless you have whitelisted a trait and the identify call contains that trait. If you whitelist multiple traits in the Segment app’s destintation settings under “Whitelisted Traits”, then the identify call must contain all of them in order to be sent into your Slack. Following the code example above, we can whitelist the trait names of name and email.

Identify Template

Once you’ve saved your whitelisted traits, you can now use them alongside Handlebars expressions syntax within a template. Make sure you reference the spec for the Identify method and common object. Identify events that contain the whitelisted traits will appear as a Slack message with the following default template:

Identified user \. \n\

where “name” is the first found of the following:

• context.traits.name
• context.traits.firstName + context.traits.lastName
• context.traits.username
• properties.email
• context.traits.email
• User + userId
• Anonymous user + anonymousId

Using the above code example, you can create the following template:

The user {{name}} has an email of {{email}}

Which would result in the following message within your Slack channel:

The user John Doe has an email of john.doe@example.com

Track

If you’re not familiar with the Segment Specs, take a look to understand what the Track method does. An example call using the analytics.js library would look like:

analytics.track('Email Opened', {
  name: 'John Doe',
  email: 'john.doe@example.com'
});

Event Channels

By default, all track events are sent to the default Slack channel configured in the Segment UI when getting started. To prevent events from sending you will need to modify your track call to use selective integrations. Business Tier customers also have the option to filter the events within the “Schema” section of the Segment UI.

If you would like to have specific events be sent to a particular channel (#channel) or user (@user) using a direct message, you can specify this in the “Events Channels” settings within the Segment UI.

Event Templates

Event templates also use Handlebars expressions syntax. Make sure you reference the spec for the Track method and common object. Track events will trigger a Slack message with the following default template:

'\ did \.'

where “event” is the event name and “name” is found with the same logic as that of the “name” in the Identify template.

The basic Track structure:

{
  "type": "track",
  "event": "Email Opened",
  "properties": {
    "plan": "Pro Annual",
    "custom" : "Bay Area",
    "name": "Peter Reinhardt"
  }
}

Using the above code example, you can enter the event name Email Opened and create the following template:

{{name}} opened an email from {{properties.name}} ({{properties.email}})

Which would result in the following message within your Slack channel depending on how “name” was set:

Jane opened an email from John Doe (john.doe@example.com)

Regex Matching

In addition to exact event names, you can also enter regex patterns for channels and templates to map multiple events to a single channel or template rather than creating a mapping for each individual event. An example which captures all event names in both lower and upper case ending in “-ing” would look like:

/[a-zA-Z]+ing$/g

More information on regex can be found here.

Troubleshooting

Page, Identify, Group calls are not showing up

The Slack Destination does not support page or group calls. Only track events are supported by default. Remember that track.properties object is an open dictionary and may include any data you choose.

In order for identify events to work, make sure you whitelist the traits.

I’m seeing [object Object] in my Slack message

If you try to print an object (eg., \), you will see [object Object] in Slack. Drill down to a primitive type value (eg., properties.plan).

Personas

You can send computed traits and audiences generated using Segment Personas to this destination as a user property. To learn more about Personas, contact us for a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Personas sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Personas sets that value to false.

When you first create an audience, Personas sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

Event Channels

Use these fields to map your Segment event names to Slack channels.

Event Templates

Use these fields to map your Segment event names to Slack event names.

Identify Template

Use “handlebarsjs” templating to format messages sent to Slack. The default template is “Identified {{name}}. {{traits}}”. You do not need to append ‘traits’, as this template is specific to .identify() calls only and thus is assumed. Make sure whatever trait you try to use in your template, you send as a trait in your .identify() calls, otherwise we will reject the message.

Incoming Webhook URL

Your Slack incoming webhook URL.

Whitelisted Traits

List the traits you want to forward to Slack. If you do not list any traits, we will not forward any .identify() calls! Whitelist the traits you want catch and forward to Slack.