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, please let us know!

Getting Started

The first step is to make sure Slack supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

WebMobileServer
📱 Device-based
☁️ Cloud-based
  1. From your Segment UI’s Destinations page click on “Add Destination”.
  2. Search for “Slack” within the Destinations Catalog and confirm the Source you’d like to connect 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 haven’t had a chance to review our spec, please 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@segment.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 within the Segment UI 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 {{name}}. \n{{traits}}

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@segment.com

Track

If you haven’t had a chance to review our spec, please 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@segment.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) via a direct message, you can specify this in the “Events Channels” settings within the Segment UI.

Event Templates

Event templates also utilize 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:

'{{name}} did {{event}}.'

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@gmail.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, please make sure you whitelist the traits.

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

If you try to print an object (eg., {{properties}}), 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 through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

Event Channels

Use these fields to map your Segment event names to Nanigans 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.

Event Templates

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

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.



Questions? Need help? Contact us!
Can we improve this doc?
Email us: docs-feedback@segment.com!