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

# Klaviyo

> Add a bot to Klaviyo using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01K6BFXSKB0G4KMVGJPTR1X835)
*v3.0.2*

The official Klaviyo integration allows your bot to interact with your Klaviyo account. You can use it to:

* Create or update user profiles
* Retrieve individual or bulk user profile data
* Subscribe users to SMS/email marketing

## Setup

> [!NOTE]
>
> You will need:
>
> * A [published bot](https://botpress.com/docs/get-started/quick-start.md)
> * A [Klaviyo account](https://www.klaviyo.com/sign-up)

**1. Install the integration in Botpress**

First, install the integration to your bot:

1. In Botpress Studio, select **Explore Hub** in the upper-right corner.
2. Search for the **Klaviyo** integration, then select **Install Integration**.

In the **Configuration** menu, you should see one field: **API Key**. Leave it empty for now—you'll come back to it after creating your Klaviyo API key.

**2. Create a Klaviyo private API key**

Next, create a private Klaviyo API key:

1. [Log in to your Klaviyo account](https://www.klaviyo.com/login).
2. Select your organization's name in the bottom-left corner.
3. Select **Settings**. Then, navigate to **API keys**.
4. Under **Private API Keys**, select **Create Private API Key**.
5. Enter a name for the API key.
6. Check **Full Access** for the following API scopes:
   * **Profiles**
   * **Subscriptions**
7. Select **Create** in the upper-right corner.
8. Copy the API key—it should start with `pk`.

**3. Configure the integration in Botpress**

Now, you can finish setting up the integration in Botpress:

1. In the integration's **API Key** field, paste your Klaviyo API key.
2. Select **Save Configuration**.

> [!TIP]
>
> Your Klaviyo integration is ready. You can use the integration's [Cards](#cards) to interact with your Klaviyo account.

***

## Cards

> [!WARNING]
>
> If you use any of the following Cards in an [Autonomous Node](https://botpress.com/docs/studio/concepts/nodes/autonomous-node.md), keep in mind that your bot will fill in the Card's fields based on the user's responses. This can lead to unexpected behaviour for fields that have strict conventions.
>
> For example, the [Update Profile](#update-profile) Card lets you update [custom properties](#param-custom-properties-2) associated with a profile. If the user isn't specific about that property's exact name, the bot may accidentally create a new property instead of updating an existing one.

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### Create Profile

Create a profile in Klaviyo: either email or phone is required

**input** `object`

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `string`

Custom key-value pairs to store with the profile (JSON string)

**output** `object`

**profile** `object` *required*

The created profile

**id** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `object`

Custom key-value pairs to store with the profile

### Get Profile

Get a profile in Klaviyo

**input** `object`

**profileId** `string` *required*

The unique (Klaviyo) identifier of the profile

**output** `object`

**profile** `object` *required*

The retrieved profile

**id** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `object`

Custom key-value pairs to store with the profile

### Get Profiles

Get profiles using filters in Klaviyo

**input** `object`

**filterField** `enum\<string\>` *required*

The field to filter on

Available options: `id`, `email`, `phone_number`, `external_id`, `created`, `updated`

**filterOperator** `enum\<string\>` *required*

The comparison operator to use

Available options: `equals`, `greater-than`, `less-than`, `greater-or-equal`, `less-or-equal`, `contains`, `starts-with`, `ends-with`

**filterValue** `string | string` *required*

The value to compare against

**pageSize** `integer`

Number of profiles to return per page (1-100, default: 20)

**sort** `enum\<string\>`

Sort profiles by field. Prefix with - for descending order

Available options: `created`, `-created`, `email`, `-email`, `id`, `-id`, `subscriptions.email.marketing.list_suppressions.timestamp`, `-subscriptions.email.marketing.list_suppressions.timestamp`, `subscriptions.email.marketing.suppression.timestamp`, `-subscriptions.email.marketing.suppression.timestamp`, `updated`, `-updated`

**output** `object`

**profiles** `array` *required*

Array of profiles matching the criteria

**array item properties**

**id** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `object`

Custom key-value pairs to store with the profile

### Subscribe Profiles

Subscribe profiles asynchronously to a SMS and/or email marketing in Klaviyo

**input** `object`

**profileSubscriptions** `array` *required*

The list of profiles and Email/SMS consent to use to subscribe Email/SMS marketing

**array item properties**

**id** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**emailConsent** `boolean` *required*

Whether the profile has consented to email

**smsConsent** `boolean` *required*

Whether the profile has consented to SMS

**listId** `string`

An optional list id to add the subscribed profiles to

**historicalImport** `boolean` (default: false)

Whether to import historical profiles (true = existing subscribers with timestamp, false = new real-time opt-ins)

**output** `object`

**success** `boolean` *required*

Whether the job to subscribe the profiles has been successfully scheduled

### Update Profile

Update a profile in Klaviyo

**input** `object`

**profileId** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `string`

Custom key-value pairs to store with the profile (JSON string)

**output** `object`

**profile** `object` *required*

The updated profile

**id** `string` *required*

The unique (Klaviyo) identifier of the profile

**email** `string (email)`

The email of the profile

**phone** `string`

The phone number of the profile (E.164 format)

**firstName** `string`

The first name of the profile

**lastName** `string`

The last name of the profile

**organization** `string`

The organization or company of the profile

**title** `string`

The job title of the profile

**locale** `string`

The locale of the profile in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

**location** `object`

Address information for the profile

**address1** `string`

First line of the address

**address2** `string`

Second line of the address

**city** `string`

City name

**country** `string`

Country name

**region** `string`

State or region

**zip** `string`

Postal or ZIP code

**customProperties** `object`

Custom key-value pairs to store with the profile


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