# Social Media

## What is the Social Media module?

The social media module allows you to track social engagement from your users and report that activity into the Loyalty Engine as [events](https://kbase.whitelabel-loyalty.com/product/loyalty-engine/events). This enables you to reward and react to social behavior such as follows, mentions, tags, and direct messages.

For example, when a user follows your Instagram account or mentions you in a post, the Loyalty Engine can receive that activity as an event, enabling you to award points, unlock offers, or trigger audience segmentation.

The social media module supports Instagram or TikTok. The activities tracked varies by social network.

{% hint style="info" %}
Modules are sold separately and **not included** in the Loyalty Engine core platform licence. For pricing and details, contact your account manager. 

For the Social Media module, different pricing applies per social network.
{% endhint %}

***

## <i class="fa-instagram">:instagram:</i> Instagram

### Setup

{% stepper %}
{% step %}

#### Connecting your brand's Instagram account to the Loyalty Engine

To connect your brand's Instagram account to the Loyalty Engine for the purpose of tracking mentions, follows and DMs:

1. WLL will share a **one-time invitation link** with you.
2. Open the link and log in to the **Facebook account** that owns your Instagram business account.
3. Grant the requested permissions.

Once connected, your loyalty tenant will automatically begin receiving social-related event data for the linked Instagram account.
{% endstep %}

{% step %}

#### Connecting a user's Instagram account to the Loyalty Engine

To track a user's Instagram activity associated with your brand's account:

1. Add their Instagram username to their Loyalty Engine account as a profile attribute called  **`instagramHandle`** *(**not** to be confused with `instagram_handle` which is added automatically by the Loyalty Engine after the first piece of activity tracks)*.
2. The user must then follow your brand account on Instagram (they can skip the step if they already do).
3. The user must then send your brand account a DM.

{% hint style="warning" %}
Because Instagram doesn’t notify WLL directly of follow activity, **a follow is only registered once the user sends your account a DM.** Make sure your loyalty interface makes this clear to users.
{% endhint %}
{% endstep %}
{% endstepper %}

### Tracked activity

The following Instagram activity types are tracked and reported to the Loyalty Engine.

{% hint style="info" %}
For private Instagram accounts, **only follows and DMs are trackable.**

Public, creator, and business accounts support all activity types below.
{% endhint %}

{% tabs %}
{% tab title="Posts & reels" %}
A user mentions your account in the caption of a post or reel, or tags your account in the media itself.&#x20;

Mentions are reported almost instantly. Tags may take up to 20 minutes to appear.

#### Event type & properties

* **Event type:** `MENTIONED_YOU_SOCIAL`
* **Reported properties:**
  * `caption`
  * `platform`
  * `media_url`
  * `mention_type` ("mention" or "tag")
  * `media_type` ("post" or "reel")
    {% endtab %}

{% tab title="Stories" %}
A user mentions your account in a story.

#### Event type & properties

* **Event type:** `MENTIONED_YOU_SOCIAL`
* **Reported properties:** same as above, with `media_type: story`
  {% endtab %}

{% tab title="Follows" %}
A user follows your nominated Instagram account.

Instagram does not provide a follow notification directly. Instead, the follow is inferred when a user sends you a DM and no previous follow status is known, or it was previously "not following."

#### Event type & properties

* **Event type:** `FOLLOWED_YOU_SOCIAL`
* **Triggered by:** user sends a DM for the first time or after being marked as "not following"
  {% endtab %}

{% tab title="DMs" %}
A user sends a direct message to your nominated Instagram account.

Sending a DM also updates the user's follow status in their loyalty profile attributes.

#### Event type & properties

* **Event type:** `DM_YOU_SOCIAL`
* **Reported properties:**
  * `platform` (e.g. "instagram")
  * `message` (the content of the DM)
    {% endtab %}
    {% endtabs %}

### Profile attributes

The following profile attributes are added to a user's Loyalty Engine account when they first DM you and some update each time a user does a trackable activity.

<table><thead><tr><th width="224.5390625" valign="top">Attribute</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><strong><code>dm_keyword</code></strong></td><td valign="top"><a data-footnote-ref href="#user-content-fn-1">The DM keyword they used in their first tracked DM.</a></td></tr><tr><td valign="top"><strong><code>instagram_handle</code></strong></td><td valign="top">The user's Instagram user name at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_posts</code></strong></td><td valign="top">The user's post count at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_follows</code></strong></td><td valign="top">The number of Instagram accounts the user follows at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_followers</code></strong></td><td valign="top">The number of Instagram followers the user has at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_follows_you</code></strong></td><td valign="top">Store as <code>true</code>/<code>false</code>. Whether the user's account follows your account. Only updated whenever the user sends you a DM.</td></tr><tr><td valign="top"><strong><code>instagram_firstname</code></strong></td><td valign="top">The first name on the user's Instagram account at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_lastname</code></strong></td><td valign="top">The last name on the user's Instagram account at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_bio</code></strong></td><td valign="top">The user's current Instagram bio at the time of the most recent trackable activity.</td></tr><tr><td valign="top"><strong><code>instagram_profile_image</code></strong></td><td valign="top">The URL of the user's Instagram profile image.</td></tr><tr><td valign="top"><strong><code>instagram_verified</code></strong></td><td valign="top">Stored as <code>true</code>/<code>false</code>. Whether the user's account has completed the DM linking process.</td></tr></tbody></table>

***

## <i class="fa-tiktok">:tiktok:</i> TikTok

### Setup

{% stepper %}
{% step %}

#### Connecting your brand's TikTok account to the Loyalty Engine

TikTok only tracks hashtags in post captions. As no mentions, DMs or follow status is tracked, there is **no need to link your brand TikTok account to the Loyalty Engine.**

Instead, share a list of hashtags you want to track with your onboarding manager.
{% endstep %}

{% step %}

#### Connecting a user's TikTok account to the Loyalty Engine

To track a user's TikTok activity, add their TikTok username to their Loyalty Engine account as a profile attribute called  `tiktokHandle` (**not** to be confused with `tiktok_handle` which is added automatically by the Loyalty Engine *after* the first piece of activity tracks).
{% endstep %}
{% endstepper %}

### Tracked activity

TikTok tracks hashtags on posts by user's who have added their TikTok username to their loyalty account.

After a user makes a post with one or more of the specified hashtags in the caption, it will be reported to the Loyalty Engine within 24 hours.

{% hint style="info" %}
The user must have a public TikTok account for tracking to work.
{% endhint %}

#### Event type & properties

* **Event type:** `MENTIONED_YOU_SOCIAL`
* **Reported properties:**
  * `caption`
  * `like_count`  (number of likes at the point the post tracks)
  * `comments_count` (number of comments at the point the post tracks)
  * `platform`
  * `mention_type` ("hashtag")
  * `media_type` ("tiktok video")

### Profile attributes

The following profile attributes are added to a user's Loyalty Engine account each time they include a tracked hashtag in one of their posts.

<table><thead><tr><th width="211.51953125">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>tiktok_handle</code></strong></td><td>The user's TikTok user name at the time of the most recent trackable activity.</td></tr><tr><td><strong><code>tiktok_follows</code></strong></td><td>The number of TikTok accounts the user follows at the time of the most recent trackable activity.</td></tr><tr><td><strong><code>tiktok_followers</code></strong></td><td>The number of TikTok followers the user has at the time of the most recent trackable activity.</td></tr><tr><td><strong><code>tiktok_bio</code></strong></td><td>The user's current TikTok bio at the time of the most recent trackable activity.</td></tr><tr><td><strong><code>tiktok_profile_image</code></strong></td><td>The URL of the user's TikTok profile image.</td></tr></tbody></table>

[^1]: You can specify one or more keywords to be tracked via DM, which can help you understand the source of your users.

    These keywords are setup by your onboarding manager during module setup.