> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/integrations/marketing/integrating-klaviyo-with-alhena-ai.md).

# Klaviyo

Capture leads from AI conversations and sync them to Klaviyo as profiles, with automatic consent handling and subscription management.

Automatically extract lead information from conversations and create or update profiles in Klaviyo. Includes built-in consent handling for email and SMS marketing subscriptions.

## Prerequisites

* A Klaviyo account
* A Klaviyo Private API key

## Getting Your API Key

1. In Klaviyo, go to **Settings > API Keys**
2. Click **Create Private API Key**
3. Give the key a name, then **Select scopes** (see below) and create the key
4. See [Klaviyo's guide](https://help.klaviyo.com/hc/en-us/articles/7423954176283) for detailed instructions

### Required Scopes

When creating the Private API Key, set the following scopes. Everything else can be set to **No Access**.

| Klaviyo scope     | Access              |
| ----------------- | ------------------- |
| **Lists**         | Full (Read & Write) |
| **Profiles**      | Full (Read & Write) |
| **Subscriptions** | Full (Read & Write) |

## Setup

### Step 1: Connect Klaviyo

1. In Alhena, go to **Settings > Integrations**
2. Find **Klaviyo** and click **Enable**
3. Paste your Klaviyo Private API key
4. Click **Connect**

### Step 2: Configure Attributes

Choose which information the AI should extract from conversations and sync to each Klaviyo profile:

1. Click **Add attribute** to open the **Add attributes for Klaviyo profiles** dialog.
2. Pick an **Attribute name** from the dropdown of predefined Klaviyo properties — `first_name`, `last_name`, `phone_number`, `organization`, `title`, `utm_source`, `utm_medium`, `utm_campaign`, `gclid` — or choose **Custom attribute** to enter your own property key (e.g., `company_size`, `industry`).
3. Add an **Attribute description** that tells the AI how to extract the value (required). Selecting a predefined attribute pre-fills a suggested description and examples, which you can edit.
4. Optionally add **Examples** of expected values using **Add example** (up to 10).
5. Click **Save changes**.

Default attributes are pre-configured:

* `email` and `consent` are always included and **cannot be removed**
* `first_name` and `last_name`

{% hint style="info" %}
These attributes tell Alhena what to extract and sync; they do not make the AI proactively request the information. Add a matching [lead-capture guideline](/docs/integrations/marketing.md#set-up-proactive-lead-capture), or ask [AI Help](/docs/features/ai-help.md) to draft one. Configure a Klaviyo attribute for every value the guideline collects.
{% endhint %}

***

### Step 3: Assign Conversations to Lists (Optional)

Beyond creating or updating profiles, you can have the AI add conversations to specific Klaviyo lists based on rules you describe in plain language.

#### Assignment rules

In the **Klaviyo Lists** section:

1. Click **Add assignment rule**.
2. Select the **Klaviyo list** the matching conversations should be added to. (Each list can have one rule; lists that already have a rule are not shown.)
3. Under **When should conversations be added to this list?**, describe the condition in natural language — e.g., *"Identify users looking for wholesale opportunities and extract their business email."* The AI uses this during conversations to decide when to add a profile to the list.
4. Click **Save changes**.

Saved rules appear in a table showing the **List name** and **Assignment rule**, with actions to **edit** or **delete** each one.

#### Fallback list

In the **Fallback List** section, select a list to catch conversations that don't match any assignment rule, then click **Save changes**. Leave it unset if you don't want a catch-all list.

***

## What Gets Captured

**Automatic context (no setup needed):**

* `alhena_chat_id` - Conversation identifier
* `page_url` and `page_title` - Where the conversation happened
* Visitor location (city, region, country, timezone, IP)

**Optional attributes you can add:**

* Standard Klaviyo fields (`phone_number`, `organization`, `title`, etc.)
* Custom profile properties
* UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `gclid`)

***

## Consent Handling

Consent is handled automatically:

* The `consent` attribute is included by default
* If a user indicates they want to receive marketing communications, Alhena records their consent
* With consent + email: subscribed to Email Marketing
* With consent + phone: subscribed to SMS Marketing (requires Klaviyo SMS to be enabled)
* Without consent: profile is created but not subscribed

***

## Enabled Agents

When you connect Klaviyo, lead capture is enabled for the lead generation agent:

| Agent                     | Description                                                                 |
| ------------------------- | --------------------------------------------------------------------------- |
| **Lead generation agent** | Extracts configured attributes from conversations and syncs them to Klaviyo |

You can configure this agent in **AI Settings > Agents**.

***

## Disconnecting

To disconnect Klaviyo:

1. Go to **Settings > Integrations > Klaviyo**
2. Click **Disconnect** — this takes effect immediately