> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segment

> Guide to integrate and sync data from Segment on SuprSend using webhooks.

The SuprSend segment integration enables you to sync users and events from Segment to SuprSend. This allows for seamless migration of users from Segment to SuprSend and the ability to use events from Segment to power automated workflows within SuprSend.

## Connector setup on SuprSend

Login to SuprSend dashboard. Go to **Settings**-> **Connectors**. Select **"Segment"** from the connectors list. This is how segment integration page looks like.

<Frame>
  <img src="https://mintcdn.com/suprsend/dnAGb1CmSRGCSyT3/images/docs/4c4ce80-image.png?fit=max&auto=format&n=dnAGb1CmSRGCSyT3&q=85&s=5dafca7534a8dd74777696ca86937ecd" width="2204" height="1502" data-path="images/docs/4c4ce80-image.png" />
</Frame>

Before beginning the Segment integration, it is important to establish how Segment events and users will be mapped in SuprSend. The following form fields will assist in setting up the desired data mapping within SuprSend:

### 1. Add Prefix to track events

This option allows for distinguishing the events coming from multiple data sources such as SuprSend SDK and Segment, or any other connector. By enabling this feature, a prefix of **`segment : `**will be added to all event names coming from Segment. This is particularly useful for existing Segment and SuprSend users who are passing the same events from both SuprSend SDK and Segment. By default, SuprSend assumes that events coming from all sources are unique and does not add any prefix to the event name.

For example- if the [segment track](https://segment.com/docs/connections/spec/track/) API call looks like this

<CodeGroup>
  ```javascript javascript theme={"system"}
  {
    "type": "track",
    "event": "User Registered",
    "properties": {
      "plan": "Pro Annual",
      "accountType" : "Facebook"
    }
  }
  ```
</CodeGroup>

associated event JSON at SuprSend with **add prefix enabled** will look like this

<CodeGroup>
  ```javascript javascript theme={"system"}
  event_name = "segment : User Registered"

  properties = {
  	"plan": "Pro Annual",
      "accountType" : "Facebook"
  }
  ```
</CodeGroup>

### 2. User preference mapping

There are certain reserved properties in SuprSend user profile, such as language preference. In order to map these reserved properties, you have to define the trait in [Segment identify](https://segment.com/docs/connections/spec/identify/) call whose value should be mapped to the reserved property.

e.g.. if you define `language` as the mapping key for Preferred Language in SuprSend. The value passed against `language` trait in Segment identify call will be mapped as user preferred language in SuprSend.

Example of Segment `identify` API call

<CodeGroup>
  ```javascript javascript theme={"system"}
  {
    "type": "identify",
    "traits": {
      "name": "Peter Gibbons",
      "email": "peter@example.com",
      "language": "hi",
      "plan": "premium",
      "logins": 5
    },
    "userId": "97980cfea0067"
  }
  ```
</CodeGroup>

associated user JSON at SuprSend will be.

* Segment`userID`is used to map the`distinct_id`of user on SuprSend.

* All properties inside`traits`are considered as user properties which can be further used to map user channels and preferences in SuprSend.

<CodeGroup>
  ```javascript javascript theme={"system"}
  distinct_id = "97980cfea0067"

  properties = {
    "name": "Peter Gibbons",
    "email": "peter@example.com",
    "language": "hi",
    "plan": "premium",
    "logins": 5
  }
  ```
</CodeGroup>

and with language set as mapping key, `hi` will be set as the preferred\_language in user profile

<Frame caption="Key mapping in Segment Connector Settings">
  <img src="https://mintcdn.com/suprsend/09Y8zJBSaqwwb23r/images/docs/6695612-image.png?fit=max&auto=format&n=09Y8zJBSaqwwb23r&q=85&s=8713ab22d074fabec7d2218a4a6b84d0" width="1190" height="332" data-path="images/docs/6695612-image.png" />
</Frame>

<Frame caption="mapped value in user profile">
  <img src="https://mintcdn.com/suprsend/iZJ8XgyTL4NrLVtX/images/docs/a92931f-image.png?fit=max&auto=format&n=iZJ8XgyTL4NrLVtX&q=85&s=95ce836603c50b85df378b377f564ac9" width="1140" height="728" data-path="images/docs/a92931f-image.png" />
</Frame>

<Warning>
  Language is stored in ISO 639-1 standard language codes. So, if you pass any value in language which is not in this format, it will be ignored. You can refer to all the [language codes here](https://github.com/suprsend/suprsend-py-sdk/blob/v0.12.0/src/suprsend/language_codes.py)
</Warning>

### 3. User channel mapping

For existing segment users, you can use the same mapping that is used to track user channels in your segment identify call in SuprSend as well. Just map the channel keys in the [Segment identify](https://segment.com/docs/connections/spec/identify/) call with the corresponding communication channel in SuprSend interface.

By default, the `email` trait in the Segment identify call is mapped to the Email channel in SuprSend, and the `phone` trait is mapped to the SMS channel. You can add the mapping of other channels in the similar way

For new users setting up a fresh Segment integration, below table can be used as a reference for mapping user channels in both SuprSend and Segment:

| SuprSend User Channel | Segment key       |
| --------------------- | ----------------- |
| Email                 | email             |
| SMS                   | phone             |
| Whatsapp              | whatsapp          |
| Slack (Email)         | slackEmail        |
| Slack (User ID)       | slackUserID       |
| Androidpush (FCM)     | fcmAndroidpush    |
| Androidpush (Xiaomi)  | xiaomiAndroidpush |
| iospush (APNS)        | apnsIospush       |

Example of Segment `identify` API call

<CodeGroup>
  ```javascript javascript theme={"system"}
  {
    "type": "identify",
    "traits": {
      "name": "Peter Gibbons",
      "email": "peter@example.com",
      "phone":"+15555555555",
      "slack_email":"peter@abccompany.com",
      "language": "hi",
      "plan": "premium",
      "logins": 5
    },
    "userId": "97980cfea0067"
  }
  ```
</CodeGroup>

with below User Channel mapping

<Frame>
  <img src="https://mintcdn.com/suprsend/dnAGb1CmSRGCSyT3/images/docs/421f348-image.png?fit=max&auto=format&n=dnAGb1CmSRGCSyT3&q=85&s=afa8d7517f5738fed232db8684935167" width="1366" height="576" data-path="images/docs/421f348-image.png" />
</Frame>

Communication channels in user profile will look like this

<Frame>
  <img src="https://mintcdn.com/suprsend/dnAGb1CmSRGCSyT3/images/docs/3bd2518-image.png?fit=max&auto=format&n=dnAGb1CmSRGCSyT3&q=85&s=fcc1610e784c6e0be88fb61b16d1b2be" width="1130" height="610" data-path="images/docs/3bd2518-image.png" />
</Frame>

Click on **`Save Mapping`** to save the changes

<Warning>
  **Changes in mapping keys will be applied to future syncs**

  It's important to note that any changes made to channel or preference mapping will only be applied to future user syncs. If the mapping is changed, you'll have to replay all past user syncs in order to update the data in the user profile for existing users.

  Also, we don't override channel information. So, if a user's email or any other channel value is changed in user profile, it will be appended to the user channel list and notification will be sent on both old and new email. This is to ensure that no communication is lost during the change and users can continue to receive notifications on their preferred channels.
</Warning>

Now that the desired mapping of Segment events and users in SuprSend has been established, the next step is to start Segment integration.

## Setting up data sync from Segment to SuprSend

You'll have to configure SuprSend as a destination in Segment.

<Info>
  **Use webhooks destination to connect with SuprSend**

  Since, we are in beta and we don't have a first-party integration with Segment yet, you can use webhooks in Segment destination list to connect with SuprSend.
</Info>

Follow below steps to configure SuprSend Destination in Segment:

<Steps>
  <Step title="Add SuprSend as destination in your segment account">
    1. Login to your Segment account. Select **Connections**-> **Destinations** from the side navigation menu and click on **"Add Destination"**

    <Frame>
      <img src="https://mintcdn.com/suprsend/JOwfEC79k-vs3tUR/images/docs/97a2e63-segment_1.png?fit=max&auto=format&n=JOwfEC79k-vs3tUR&q=85&s=936c034375a3a7bf3a4778d72b8014f5" width="2876" height="738" data-path="images/docs/97a2e63-segment_1.png" />
    </Frame>
  </Step>

  <Step title="Search for webhook">
    This will open destinations catalog. Search for webhook and select **"Webhooks (Actions)"**

    <Frame>
      <img src="https://mintcdn.com/suprsend/JOwfEC79k-vs3tUR/images/docs/914e86b-image.png?fit=max&auto=format&n=JOwfEC79k-vs3tUR&q=85&s=bba6407c052c6908f20e160754e18fe5" width="2448" height="1626" data-path="images/docs/914e86b-image.png" />
    </Frame>
  </Step>

  <Step title="Add Destination">
    On the Webhooks page, click on **"Add destination"**

    <Frame>
      <img src="https://mintcdn.com/suprsend/y77gmHjmaTSnbCzd/images/docs/c2d4b57-image.png?fit=max&auto=format&n=y77gmHjmaTSnbCzd&q=85&s=1c072b2c71f7a3d2c309d9e21b2e0e51" width="2426" height="1114" data-path="images/docs/c2d4b57-image.png" />
    </Frame>
  </Step>

  <Step title="Pick Data Source">
    Select the data source from which you are syncing your user and event data and click on "Next"
  </Step>

  <Step title="Add Destination Name">
    On the setup screen, add Destination name. Destination name can be **"SuprSend \{workspace}"**. For example- For staging workspace, the destination name can be "SuprSend Staging". Choose **"Fill in settings manually"** and click on **"Create destination"**.

    <Frame>
      <img src="https://mintcdn.com/suprsend/jhGzZpggWCp1KSgu/images/docs/e27856c-image.png?fit=max&auto=format&n=jhGzZpggWCp1KSgu&q=85&s=0b7700d5bded5ea2d169bd4cec55cf80" width="2200" height="784" data-path="images/docs/e27856c-image.png" />
    </Frame>
  </Step>

  <Step title="Create a New Mapping">
    Now, on your webhook destination page, go to **Mappings** tab and create a **+New Mapping**.

    <Frame>
      <img src="https://mintcdn.com/suprsend/jhGzZpggWCp1KSgu/images/docs/ebd8075-image.png?fit=max&auto=format&n=jhGzZpggWCp1KSgu&q=85&s=a0d4a58ef0858fd549f38c81e923d29e" width="2368" height="976" data-path="images/docs/ebd8075-image.png" />
    </Frame>
  </Step>

  <Step title="Send an HTTP Request">
    Select **Send an HTTP request** in Add Mapping modal and add below details

    <Frame>
      <img src="https://mintcdn.com/suprsend/y77gmHjmaTSnbCzd/images/docs/be129b0-image.png?fit=max&auto=format&n=y77gmHjmaTSnbCzd&q=85&s=d856ee7c0f32186a7793c20686ab21d3" width="1192" height="660" data-path="images/docs/be129b0-image.png" />
    </Frame>
  </Step>

  <Step title="Add below mapping in the send request:">
    * Select any of event type- track and identify

          <Frame>
            <img src="https://files.readme.io/71ff24e-image.png" />
          </Frame>

    * In Add test event, select **Load Test Event from Source**

          <Frame>
            <img src="https://files.readme.io/141834f-image.png" />
          </Frame>

    * In Select Mappings, add below details:

    > URL: [https://hub.suprsend.com/connector/segment/](https://hub.suprsend.com/connector/segment/)
    > <br /> Method: `POST`
    > <br />`Authorization` in headers: `Bearer _api_key_`(Please make sure to replace "*`api_key`*" with actual api key from segment connector settings page.)

    <Frame>
      <img src="https://files.readme.io/8d6594d-image.png" />
    </Frame>
  </Step>

  <Step title="Sending Test Event">
    Now, send a test event of type `track` or `identify`. You'll see status `200 OK` response and the corresponding event on [SuprSend dashboard -> API logs](https://app.suprsend.com/en/staging/logs/api/?last_n_minutes=1440) page.

    <Frame>
      <img src="https://mintcdn.com/suprsend/ysJyO3LOXwZ5L098/images/docs/f0fc0a8-image.png?fit=max&auto=format&n=ysJyO3LOXwZ5L098&q=85&s=41c8414801d1affd69a519b936bddf89" width="1844" height="1000" data-path="images/docs/f0fc0a8-image.png" />
    </Frame>

    <Warning>
      Callout ContentIf you don't get `200 OK` response in event tester, this means that Segment was unable to successfully setup your SuprSend connection. Double check Webhook URL and header in step-7 and see if its configured correctly in the Destination settings.
    </Warning>

    Once your SuprSend connection is successful, try sending a test `identify call` and see if the user channels are mapped correctly in SuprSend. You can see the synced user on [*SuprSend dashboard -> Subscribers*](https://app.suprsend.com/en/staging/subscribers/subscribers/) page. Also, send a test `track event` call and check if the workflows are getting triggered.
  </Step>

  <Step title="Enable Mapping">
    1. After successful testing, **Save and Enable** the mapping.

    <Frame>
      <img src="https://mintcdn.com/suprsend/jhGzZpggWCp1KSgu/images/docs/d92dc6b-image.png?fit=max&auto=format&n=jhGzZpggWCp1KSgu&q=85&s=e33b860b8f0cea60984d891044db212a" width="2404" height="518" data-path="images/docs/d92dc6b-image.png" />
    </Frame>
  </Step>

  <Step title="Enable Destination in Settings ">
    Also enable destination in Settings tab to start sending webhook data to SuprSend.

    <Frame>
      <img src="https://mintcdn.com/suprsend/3ix_OjxB_ZGM-pa-/images/docs/1afc9f3-image.png?fit=max&auto=format&n=3ix_OjxB_ZGM-pa-&q=85&s=36fa3d84184b30378dbdf9e4e956d9f5" width="2382" height="248" data-path="images/docs/1afc9f3-image.png" />
    </Frame>
  </Step>
</Steps>

Your setup is now complete, enabling events and users data to flow from Segment to SuprSend. You can use this info to automatically power SuprSend workflows without making any changes in your codebase.

***