Loading...
Skip to main content

How To Send Notifications With Segment

Courier’s Destination for Segment provides an easy way to send data from Web or Mobile applications into Courier to improve notification delivery and management. Data and events flow from your application through Segment’s integration to Courier. In order to use Courier's Segment destination, you must already have Segment installed in your application.

Overview​

How do Segment API calls send notifications?

  1. Segment identifies some user action and creates a track API call
  2. The track API call sends the event to Courier
    • Segment properties JSON data is passed into the Courier Send API as elements of the data JSON object
    • Segment's userId is used to locate the recipient in Courier with the same ID or create a new one when none are found
  3. Courier receives the event from Segment
  4. The event within Courier triggers all automations linked to it
  5. The linked automations run send any notifications that are linked to them

Before Starting​

Prior to sending notifications with Segment you will need the following:

  • A Segment account
  • A published notification template routed to a configured provider within Courier

Install Segment​

Within Courier you can access the Segment integration to:

  • Check for events and view all events (sent via Segment and received by Courier)
  • Link Courier automations to received events

Initially, you will need to connect Courier as a destination within Segment. At this stage, you will receive a “No events received” message within Courier.

Courier - Install Segment (No Events Received)

Configure Segment​

Segment supports Courier as a destination. Once you configure Courier destination inside Segment, you should be able to connect one or more sources, and you should see events flowing into Courier.

Events flowing in from Segment into Courier are visible on Segment integration page inside Courier Studio, from where you can map it to trigger notification workflows. For instance, you can trigger an automation that welcomes a new user if an analytics.identify event flows in from Segment.

Supported Segment Events:

  • analytics.group
  • analytics.identify
  • analytics.track

Connecting Segment​

  1. Once logged into the Segment app, navigate to the Destinations catalog page and click Add Destination.
  2. Search for Courier in the Destinations Catalog, and select the Courier destination.
  3. Choose which Source should send data to the Courier destination.
  4. In the Courier Integrations Page, search for Segment and click on it to access the Courier API Key. (If you do not see a key here, go to the Courier Settings Page and copy the Auth Token from the API Keys section.)
  5. Enter the Courier API Key or Auth Token in the Courier destination settings field API Key in Segment.

Check for Segment Events​

In order to receive your first event from Segment, navigate to the destination's "Event Tester" and click "Send Event" at the bottom of the page.

Segment - Test Event

In the Courier API, refresh the page or click "Check for Events" and you will see the event appear in a list if the destination setup and test event send were successful. Below is an example of a test track event sent through Segment.

Courier - Event Received

Troubleshooting:

If you continue to see the "No Segment events received yet." message in Courier, this could mean that Segment was unable to successfully setup your Courier workspace as a destination. To ensure that the test event sent by Segment is successfully received by Courier, double check that your API Key was copied accurately into Segment.

Another suggestion is to check where the email property is placed within the test JSON object in Segment. If it is at the top level, you can move it within the properties object and resend the test event.

Linking Automations​

Linking an automation to a Segment event allows you to create a flow of actions that will be triggered by that specific event. This means that whenever an event is sent through Segment, any and all all linked automations will be triggered.

Locate the event you want to link, click the + sign on the second column, and select the automation(s) of your choice.

The easiest way to successfully link an automation to a segment event is to click “create new automation”. This new automation will use the linked Segment event as a trigger, and have an autopopulated recipient ID in the send step. All you’ll need to do is select the notification template that should be sent.

Additionally, refs.data points to the data object from Segment. refs.data.userid references this data from Segment directly and auto populates the recipient ID in the automation send step (see Automation Send Step figure below). Below the recipient ID, add the "Profile" optional field with the following JSON to get the user's email from the Segment data object:

{
  "$ref": "data.email"
}

Learn more about Courier Automations >

Courier - Map Segment Event to Automation
Courier - Automation Send Step

Segment API: Identify Calls​

Segment Identify calls allow you to connect a user to their actions (Segment events) and record traits to them - the user can be identified by their User ID and can hold additional traits such as their name, email, etc.

Learn more about Segment Identify >

Learn more about Courier Profiles >

Recipients​

Courier recipients can be updated using Segment user profiles over time.

Segment API: Track Calls​

Segment Track calls allow you to record actions performed by your users, including any properties associated with their actions - the actions can be associated with any properties that help you analyze these actions.

Learn more about Segment Track >

Track events appear with a prefix of track/ in Courier. Courier gathers data from the track's properties object - to send notifications based on a Segment event, these track events must be mapped to Courier Automations.

The following is an example Segment API call:

analytics.track('Login Button Clicked', {
  messageId: "segment-test-message-a8rmf",
  timestamp: "2021-12-07T08:41:59.410Z",
  type: "track",
  email: "test@example.org",
  projectId: "4GgKeBoVJkT9EZL4vAmduv",
  properties: {
    property1: 1,
    property2: "test",
    property3: true
  },
  userId": "test-user-cqw3gr",
  event": "Segment Test Event Name"
})

The following is the associated JSON object from the Segment API call:

{
  "messageId": "segment-test-message-a8rmf",
  "timestamp": "2021-12-07T08:41:59.410Z",
  "type": "track",
  "email": "test@example.org",
  "projectId": "4GgKeBoVJkT9EZL4vAmduv",
  "properties": {
    "property1": 1,
    "property2": "test",
    "property3": true
  },
  "userId": "test-user-cqw3gr",
  "event": "Segment Test Event Name"
}

The following is how the above JSON object is mapped into the Courier data object:

{
  "data": {
    "property1": 1,
    "property2": "test",
    "property3": true
  }
}

Troubleshooting:

If the email property isn’t being read into Courier, try to place email within the properties object.

FAQs​

  1. What is the difference between Courier's live and test environments in relation to Segment?

Segment API keys will follow the environment you're in. If you'd like to configure Segment with your production API keys, configure in it the product environment. If you'd like to configure Segment with your test API keys, configure it in the test environment.

  1. What should I do if the recipient ID in the Automation template does not autopopulate?

The reicipient ID will only autopopulate if and when the template is linked to a Segment event. To ensure this, head over to the Segment integration page and make sure that your automation is linked to the correct event. You can also do this by checking the first step of the Automation template itself, labelled "Start".

Once linked to an event, try to refresh the template and check if the reicipient ID appears. If it does not, you can manually write refs.data.userid into the recipient ID field.