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

# Klaviyo

> Connect Klaviyo to Moshi, sync shoppers into a Moshi shoppers segment, and hide sign-up popups from them.

Connect Klaviyo to send the shoppers Moshi captures into your Klaviyo account.
Moshi also creates a **Moshi shoppers** segment, so you can build reports and keep sign-up popups away from people who already chatted with you.

## Connecting Klaviyo

**1. Create a private API key in Klaviyo**

In Klaviyo, open `Settings`, then `API keys`, and select `Create Private API Key`.
Give the key these scopes:

| Scope | Access |
| - | - |
| Lists | Read |
| Profiles | Read/Write (Full) |
| Segments | Read/Write (Full) |

**2. Paste the key in Moshi**

In Moshi, open `Integrations`, select `Klaviyo`, and paste the private API key.

**3. Save**

Moshi checks the key when you save it.

> [!NOTE]
>
> Profiles write access and Segments write access are both required.

## What Moshi sends to Klaviyo

Turn on `Send funnel data to Klaviyo`.
Once a day, Moshi syncs the shoppers it captured. Each profile can include:

* Email and name
* Address, where available
* Survey answers you mapped
* `moshi_flow`: the name of the Moshi flow
* `moshi_flow_id`: the id of that flow

You can also pick a Klaviyo list, and Moshi adds the synced shoppers to it.

Moshi does not send phone numbers.
Moshi does not subscribe anyone to marketing. Consent stays with your own forms.

> [!NOTE]
>
> Build your segments and reports on `moshi_flow_id` or `moshi_flow`.
> A `$source` value of `moshi` may also appear, but other tools, such as popup apps, can overwrite `$source`. Don't rely on it.

## The "Moshi shoppers" segment

When you connect, Moshi automatically creates a segment named **Moshi shoppers** in your Klaviyo account.
It includes every profile where `moshi_flow_id` is set.

* Don't rename or delete it.
* If it is deleted, save your key in Moshi again to recreate it.
* Klaviyo can take a little while to fill a new segment.

## Hide sign-up popups from Moshi shoppers

Shoppers who arrive from a Moshi chat have usually already shared their details.
A "join our list" popup interrupts them on the way to checkout.

Use two rules together:

| Rule | What it covers |
| - | - |
| URL contains `utm_source=moshi` | The page the shopper lands on from a Moshi link. It covers only that page, because the URL parameter disappears once they click to another page. |
| Segment is **Moshi shoppers** | Returning shoppers, once Klaviyo recognizes their browser (for example after they click a Klaviyo email, sign up, or check out). It can't recognize a brand-new visitor on their first click. |

### Klaviyo sign-up forms

**1. Open the form**

In Klaviyo, go to `Sign-up forms` and open the popup or flyout.
Go to the `Targeting & Behavior` (or `Targeting`) tab.

**2. Exclude the segment**

Under visitor targeting, set `Don't show to` and choose profiles in list or segment: **Moshi shoppers**.

**3. Exclude the Moshi URL**

Under URL targeting, set `Don't show on certain URLs` and choose URL contains `utm_source=moshi`.

**4. Publish**

Save and **Publish** the form.

Repeat for every live popup and flyout.
Embedded forms that sit on a page usually don't need this.

> [!WARNING]
>
> Labels in Klaviyo can differ slightly between versions.

### Alia popups

If you use Alia for popups, follow the [Alia guide](https://docs.moshi.ai/integrations/alia.md). It uses the same two rules.

### Test it

1. Open an incognito window.
2. Visit a product page on your store with `?utm_source=moshi` added to the end of the URL.
3. The popup should not appear. For exit-intent popups on desktop, move your mouse toward the browser tabs.
4. Visit the same page without `?utm_source=moshi`. The popup should appear as normal.

> [!TIP]
>
> If the popup is hidden with the parameter and shown without it, your rules work.

## Troubleshooting

| Message or symptom | What to do |
| - | - |
| Key rejected, missing scopes | Create a new key with the scopes listed in [Connecting Klaviyo](#connecting-klaviyo). |
| The segment is empty | Turn on `Send funnel data to Klaviyo`. The sync runs daily, and Klaviyo can take a while to fill a new segment. |
| A popup still shows on later pages | This is expected for brand-new visitors. The URL rule only covers the landing page, and the segment rule needs Klaviyo to recognize the browser. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.