> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/fr/marketing-automation/klaviyo/setup.md).

# Configuration

Connectez The Wallet Crew et Klaviyo de façon sécurisée et validez la synchronisation.

Cette configuration relie **Klaviyo** (segmentation, flux, campagnes) à **L'équipe Wallet** (l’exécution du Wallet et les signaux de cycle de vie).

Klaviyo a besoin de deux choses :

* des identifiants pour que The Wallet Crew puisse envoyer des événements et mettre à jour les propriétés de profil Klaviyo
* un flux webhook pour que Klaviyo puisse demander une rétro-alimentation de `neostore.authenticationToken` pour les profils existants

<details>

<summary><strong>Exemples réels</strong></summary>

* Une marque veut des segments « installé vs non installé » pour supprimer les e-mails de rappel.
* Une équipe CRM veut des liens authentifiés dans les e-mails sans modifier les modèles existants.
* Un partenaire veut des mises à jour du statut d’abonnement pilotées par le consentement collecté dans un formulaire d’inscription The Wallet Crew.

</details>

### Prérequis

L’accès est requis des deux côtés.

* **L'équipe Wallet**: accès à la console d’administration et aux fichiers de configuration avancés.
* **Klaviyo**: accès pour créer des clés API, des segments, des flux et des webhooks.
* Un profil de test existe dans Klaviyo avec une adresse e-mail et/ou un numéro de téléphone connus.
* L’environnement cible est identifié (préproduction vs production).

### Configuration de The Wallet Crew

The Wallet Crew utilise le connecteur Klaviyo pour envoyer des événements du cycle de vie Wallet vers Klaviyo, maintenir les propriétés de profil et, éventuellement, gérer les abonnements aux listes sur la base du consentement collecté dans les flux d’inscription.

<details>

<summary><strong>Exemples réels</strong></summary>

* Un formulaire d’inscription de fidélité collecte l’e-mail + le consentement, puis abonne le client à une liste de newsletter.
* Un événement d’installation de Carte devient une métrique Klaviyo utilisée pour déclencher un flux de bienvenue.

</details>

#### Configurez le connecteur dans The Wallet Crew

Ouvrez les paramètres d’intégration Klaviyo dans la console d’administration The Wallet Crew.

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/integrations/klaviyo" class="button secondary" data-icon="chevrons-right">Ouvrir les paramètres du connecteur Klaviyo</a></p>

<div data-with-frame="true"><figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2FPFZ4WdF7QJj4PPWcDTau%2Fdocumentation-klaviyo-general.png?alt=media&#x26;token=9d4a4ac0-00cf-4bb7-b89e-51a162b71679" alt="The Wallet Crew Klaviyo connector: general configuration screen"><figcaption><p>Les paramètres généraux stockent l’ID du site Klaviyo et la clé API privée Klaviyo.</p></figcaption></figure></div>

**Valeurs Klaviyo requises**

Les valeurs Klaviyo sont disponibles à `https://www.klaviyo.com/settings/account/api-keys`.

* `siteId` correspond à **Clé API publique / ID du site**.
* `privateApiKey` est une **nouvelle** clé privée créée pour The Wallet Crew.

**Autorisations requises sur la clé privée Klaviyo**

Les autorisations minimales dépendent des fonctionnalités activées.

* Toujours requis
  * Événements : **Accès complet**
* Requis lorsque la synchronisation des abonnements aux listes est activée
  * Listes : **Accès complet**
  * Profils : **Accès complet**
  * Abonnements : **Accès complet**

<div data-with-frame="true"><figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2FWxpWTaMCS0r5wb3KjNiE%2Fdocumentation-klaviyo-todo-alt-image-58-png.png?alt=media&#x26;token=a2184c95-4faa-4dd5-994f-e9f53c1d87e1" alt="Klaviyo API keys screen showing permissions for a private key"><figcaption><p>Assurez-vous que les autorisations de la clé privée correspondent aux fonctionnalités attendues.</p></figcaption></figure></div>

{% hint style="warning" %}
Si les événements n’apparaissent pas dans Klaviyo, le premier contrôle concerne les autorisations de la clé privée Klaviyo.
{% endhint %}

#### Activez l’étape Klaviyo dans `server/flows.yml`

Le connecteur envoie des événements lorsqu’un flux inclut une `klaviyo` étape.

{% hint style="info" %}
Le `klaviyo` étape peut être ajoutée à tout flux qui doit émettre des événements du cycle de vie.
{% endhint %}

{% code title="server/flows.yml" %}

```yaml
flux :
  - type: userRegistration
    name: user
    steps :
      - type: shopify
      - type: Carte
        passType: user
      - type: klaviyo
      - type: mail
        mailTemplate: downloadCarte
```

{% endcode %}

{% hint style="warning" %}
Si les événements n’apparaissent pas dans Klaviyo, confirmez que la `klaviyo` étape est présente dans le flux exécuté.
{% endhint %}

#### Configuration du consentement et des abonnements aux listes

Le consentement peut être collecté dans le formulaire d’inscription The Wallet Crew. Le connecteur Klaviyo peut le transformer en mises à jour d’abonnement aux listes.

**Configuration d’une seule liste**

Le `listId` valeur est disponible dans les paramètres de liste Klaviyo.

Lorsqu’un `listId` est configuré dans les paramètres Klaviyo de The Wallet Crew :

* quand `e-mail` est présent, `consents_email` contrôle le statut d’abonnement e-mail
* quand `phoneNumber` est présent, `consents_sms` contrôle le statut d’abonnement SMS

**Plusieurs listes (avancé)**

Le routage vers plusieurs listes peut être implémenté avec du script.

Créer ou modifier `/server/script/klaviyo.js` et implémenter `GetSubscriptions`.

{% code title="/server/script/klaviyo.js" %}

```javascript
function getSubscriptions(account) {
  var subscriptions = [];

  var newsletterSubscription;
  if (account["email"] && account["consents_email"] !== undefined) {
    newsletterSubscription = newsletterSubscription || { ListId: "WnP7MK" };
    newsletterSubscription.Email = !!account["consents_email"];
  }

  if (account["phoneNumber"] && account["consents_sms"] !== undefined) {
    newsletterSubscription = newsletterSubscription || { ListId: "WnP7MK" };
    newsletterSubscription.Sms = !!account["consents_sms"];
  }

  if (newsletterSubscription) {
    subscriptions.push(newsletterSubscription);
  }

  return subscriptions;
}

export default function (context) {
  context.register("extensions.klaviyo.subscriptions.provider", {
    GetSubscriptions: getSubscriptions,
  });
}
```

{% endcode %}

{% hint style="warning" %}
Si les mises à jour d’abonnement ne fonctionnent pas, confirmez **Listes** et **Abonnements** que les autorisations sont accordées à la clé privée Klaviyo.
{% endhint %}

### Configuration Klaviyo

`neostore.authenticationToken` est la pierre angulaire de l’identité pour les liens authentifiés.

Lorsque cette propriété existe sur un profil Klaviyo, les e-mails et les SMS peuvent inclure des liens qui ouvrent la bonne page Wallet pour ce client.

<details>

<summary><strong>Exemples réels</strong></summary>

* Un e-mail de réactivation ouvre la page Carte sans demander de connexion.
* Un e-mail de rappel ouvre le formulaire d’inscription lorsqu’une Carte n’est pas installée.

</details>

#### Créez le segment « TWC unsynced profiles »

Ce segment cible les profils auxquels il manque le jeton.

1. Accédez à `https://www.klaviyo.com/lists/create` et sélectionnez **Segment**.
2. Nom : `Profils TWC non synchronisés`.
3. Définition :
   * `Propriétés d’une personne`
   * `neostore.authenticationToken`
   * `n’est pas défini`

{% hint style="warning" %}
Une faute de frappe dans cette règle empêche la rétro-alimentation. C’est l’erreur de configuration la plus courante.
{% endhint %}

#### Créez le flux de synchronisation des profils

Ce flux appelle le webhook The Wallet Crew pour synchroniser le jeton des profils entrant dans le segment.

{% stepper %}
{% step %}
**Créer un flux**

* Accédez à `https://www.klaviyo.com/flows/create`.
* Créer à partir de zéro.
* Nom : `synchroniser les profils TWC non synchronisés`.
* Déclencheur : « Lorsqu’une personne rejoint les profils TWC non synchronisés ».
  {% endstep %}

{% step %}
**Ajouter une action webhook**

Klaviyo nécessite un **conforme à la 2FA** compte pour activer les webhooks.

Définissez l’URL de destination du webhook :

`https://app.neostore.cloud/api/<tenantId>/webhooks/listeners/klaviyo/profiles/sync`

`<tenantId>` est l’identifiant du tenant The Wallet Crew.

{% hint style="info" %}
`<tenantId>` est le même identifiant utilisé dans les URL The Wallet Crew et les routes API pour un tenant donné.
{% endhint %}

Ajoutez un en-tête :

* Clé : `X-API-KEY`
* Valeur : une clé API The Wallet Crew qui inclut `tenant.klaviyo.listener` l’autorisation d’écriture

Corps (JSON) :

```json
{
  "email": "{{ person.email }}",
  "phone_number": "{{ person.phone_number }}"
}
```

{% endstep %}

{% step %}
**Activez, puis rétro-alimentez les profils passés**

* Activez le flux.
* Dans le menu du flux, utilisez **Ajouter des profils passés**.
* Sélectionnez « depuis le début ».
* Lancer la rétro-alimentation.

Cela force l’évaluation et la synchronisation des profils existants.
{% endstep %}
{% endstepper %}

#### Dépannage : le jeton manque toujours après la rétro-alimentation

* Confirmez que le segment est correct : `neostore.authenticationToken` **n’est pas défini**.
* Confirmez que le flux est **activé**.
* Confirmez que l’action webhook affiche des exécutions réussies dans l’historique du flux Klaviyo.
* Confirmez que l’en-tête webhook utilise `X-API-KEY`.
* Confirmez que la clé API The Wallet Crew possède `tenant.klaviyo.listener` l’autorisation d’écriture.
* Confirmez que l’URL de destination utilise le bon `<tenantId>`.

### Erreurs de configuration courantes

Ces problèmes expliquent la plupart des situations « c’est configuré mais rien ne se passe ».

* La clé privée Klaviyo ne dispose pas des autorisations requises (événements uniquement vs événements + profils + abonnements).
* L’URL du webhook utilise le mauvais identifiant de tenant.
* La clé API The Wallet Crew utilisée par le webhook ne possède pas `tenant.klaviyo.listener` l’autorisation d’écriture.
* La règle du segment Klaviyo contient une faute de frappe, souvent autour de `neostore.authenticationToken` « n’est pas défini ».
* Le flux Wallet exécuté ne comprend pas l’ `klaviyo` étape, donc aucun événement n’est envoyé.
* Les webhooks ne sont pas activés dans Klaviyo car le compte n’est pas conforme à la 2FA.
* Le flux de synchronisation Klaviyo est désactivé, donc la rétro-alimentation ne s’exécute jamais.

### FAQ

<details>

<summary><strong>Quel environnement doit être configuré en premier ?</strong></summary>

La préproduction est généralement configurée en premier.

Cela facilite la validation des événements, de la synchronisation des profils et du comportement des abonnements avant la production.

</details>

<details>

<summary><strong>Quelles équipes sont généralement responsables de la configuration ?</strong></summary>

Les paramètres du connecteur et les clés API sont généralement gérés par l’IT ou un partenaire d’implémentation.

Les segments, les flux et les campagnes sont généralement gérés par le CRM ou les opérations marketing.

</details>

<details>

<summary><strong>The Wallet Crew a-t-il besoin d’un accès Klaviyo pour gérer les campagnes ?</strong></summary>

Non. Klaviyo conserve la propriété des flux, des campagnes et des modèles.

The Wallet Crew synchronise uniquement les signaux Wallet et les propriétés de profil.

</details>

<details>

<summary><strong>L’e-mail est-il requis pour synchroniser <code>neostore.authenticationToken</code>?</strong></summary>

L’e-mail est l’identifiant le plus courant. Le téléphone peut aussi être fourni.

Le webhook accepte les deux champs. Les règles de correspondance dépendent de la configuration du tenant.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thewalletcrew.io/connectors/fr/marketing-automation/klaviyo/setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.