Développer l'agent marketing IA (publicités Facebook/Meta)

1. Ce que vous allez construire

Chaque marchand sur Kayroo dispose déjà gratuitement d'un Expert Marketing IA interne qui lit ses paniers abandonnés, ses stocks à rotation lente et ses segments clients, et formule des conseils sur ce qu'il faut faire. Il n'envoie jamais rien, ne publie rien, ne dépense rien — c'est un rapport, pas un acteur.

Ce module fait l'inverse : un agent IA qui fait réellement le marketing. Il lit le catalogue produit réel de la boutique et ses commandes récentes via l'API Kayroo Connect, utilise un LLM avec appel d'outils (tool-use) sur l'API Meta Marketing pour rédiger des campagnes publicitaires Facebook/Meta, et — seulement une fois que le marchand a explicitement approuvé — les publie sur le compte publicitaire du marchand, en dépensant l'argent du marchand.

• Lit le catalogue produit de la boutique, les commandes récentes et les frais de livraison via l'API publique Kayroo.
• Rédige le ciblage d'audience, des suggestions de budget, le contenu publicitaire (texte + choix des images produit à utiliser), et la structure de campagne (campagne → ensemble de publicités → publicité).
• Présente chaque brouillon au marchand pour révision et approbation explicite avant toute publication ou tout engagement de budget.
• Une fois approuvée, publie la campagne sur le propre compte publicitaire Meta Business du marchand, sur sa propre facturation publicitaire.
• Renvoie les données de commande/conversion à Meta via l'API Conversions afin d'améliorer l'attribution des campagnes au fil du temps.

Ce que cette première version ne fait explicitement pas : écrire quoi que ce soit dans Kayroo, toucher aux données personnelles des clients au-delà de ce qu'exige l'API Conversions de Meta elle-même (hachées, selon les propres règles de Meta), ou prendre une décision de dépense sans supervision.

2. Lisez le guide de l'API avant de commencer

Ce module entier est construit au-dessus de Kayroo Connect — l'API REST publique et le système de webhooks de Kayroo. Ce guide suppose que vous avez déjà lu cette référence et que vous comprenez les jetons, les scopes, les endpoints et la vérification des signatures de webhook.

Le modèle de confiance est identique à toute autre intégration Kayroo : votre service vit entièrement sur votre propre infrastructure et votre propre dépôt de code. Vous n'obtenez jamais le code source de Kayroo, des identifiants de base de données, un accès serveur, ni un identifiant interne — vous ne communiquez avec la boutique d'un marchand qu'à travers son jeton API et votre endpoint webhook enregistré.

3. Plan de développement, étape par étape

Voici l'ordre recommandé pour construire la Phase 1. Chaque étape ne dépend que des précédentes.

1. Mettez en place votre propre service hébergé (votre infrastructure, votre dépôt, votre CI/CD) — c'est là que tout ce qui suit s'exécute.
2. Construisez un parcours d'intégration marchand : un écran où le marchand colle un jeton API Kayroo (qu'il crée lui-même depuis Admin → Jetons API, avec store.read + products.read + orders.read), et connecte son propre compte Meta Business à votre application via le flux OAuth propre de Meta.
3. Récupérez le contexte de la boutique à la connexion : appelez GET /api/v1/store pour la devise/les frais de livraison, GET /api/v1/products pour le catalogue (images, prix, stock), et GET /api/v1/orders pour l'historique récent des commandes — voir le tableau de la section 4 pour les champs qui comptent ici.
4. Enregistrez un abonnement webhook (le marchand le fait depuis Admin → Webhooks dans son panneau, en pointant vers votre endpoint) pour order.created et product.updated, afin que vos données de campagne et votre contenu publicitaire restent synchronisés sans interrogation continue.
5. Utilisez un LLM avec appel d'outils sur l'API Meta Marketing pour rédiger une campagne : ciblage d'audience, suggestion de budget, contenu publicitaire (texte + choix des images produit du catalogue), et structure (campagne → ensemble de publicités → publicité).
6. Montrez au marchand chaque brouillon sur un écran de révision clair et exigez une approbation explicite avant toute publication ou tout engagement de budget — voir la section 5, cette étape est obligatoire, pas optionnelle.
7. Une fois approuvée, publiez la campagne sur le propre compte publicitaire Meta Business du marchand via l'API de Meta, entièrement facturée via le moyen de paiement Meta du marchand.
8. Lorsque vous recevez un webhook order.created, envoyez l'événement de conversion correspondant à l'API Conversions de Meta (avec les données personnelles du client hachées selon les propres exigences de Meta) afin d'améliorer la performance et l'attribution publicitaires au fil du temps.
9. Lorsque vous recevez un webhook product.updated, actualisez le contenu publicitaire/les données de catalogue que vous avez mis en cache pour ce produit, afin que les campagnes n'annoncent jamais des prix obsolètes ou des articles en rupture de stock.

4. Données que vous lisez depuis Kayroo Connect

La Phase 1 n'a besoin que de scopes de lecture qui existent déjà aujourd'hui. Ne demandez que ceux-ci — ne demandez pas customers.read à un marchand sauf si vous construisez la Phase 2 (voir section 8).

5. La règle de supervision humaine (non négociable)

C'est la seule exigence la plus stricte de ce module, et ce n'est pas un choix de style : votre agent ne doit jamais publier une campagne ni engager le budget publicitaire d'un marchand sans que ce marchand ne l'approuve explicitement au préalable, à chaque fois.

• Affichez un brouillon clair et lisible (audience, budget, contenu, structure) avant toute publication — pas un simple export JSON technique.
• Exigez une action explicite (un vrai clic sur « Approuver et publier ») — jamais un délai ou une valeur par défaut qui approuve automatiquement si le marchand ne répond pas.
• Toute modification d'une campagne déjà approuvée et en cours (augmentation de budget, nouveau contenu, mise en pause/reprise) nécessite la même étape d'approbation explicite, pas seulement le lancement initial.
• L'agent peut proposer, expliquer et recommander — mais le marchand décide. À chaque fois.

6. Ce que vous ne devez jamais faire

• Ne détenez, n'avancez, ni ne déplacez jamais vous-même le budget publicitaire d'un marchand. L'argent ne circule qu'entre le marchand et Meta directement — votre module configure des campagnes, il ne touche jamais au paiement.
• Ne demandez jamais à Kayroo ou à un marchand un accès direct à la base de données, un accès serveur, SSH, ou une copie du code source de Kayroo. Si quelque chose semble en avoir besoin, la solution est de demander à Kayroo d'étendre l'API publique — pas d'obtenir un accès direct.
• Ne prenez jamais une décision de dépense ou de publication sans supervision — voir la section 5.
• Ne recalculez jamais une logique que Kayroo expose déjà. Pour la segmentation clients (Phase 2), lisez GET /api/v1/customers/segments plutôt que de redériver vous-même les segments RFM à partir des données brutes de commande.
• Ne partagez, n'agrégez, ni ne revendez jamais les données d'un marchand — issues de Kayroo ou de Meta — avec ou contre un autre marchand.

7. Exigences de sécurité et de traitement des données

• Stockez les jetons API Kayroo et les jetons OAuth Meta chiffrés au repos dans votre propre infrastructure — Kayroo ne voit jamais les jetons Meta, et Meta ne voit jamais les jetons Kayroo.
• Ne journalisez jamais les jetons en clair, et ne les exposez jamais dans du code côté client.
• Prenez en charge la révocation immédiate : si un marchand désactive votre module ou supprime son jeton API Kayroo, tout accès doit s'arrêter immédiatement de votre côté aussi — traitez cela comme une déconnexion définitive, pas comme une erreur transitoire à réessayer.
• Hachez ou traitez les numéros de téléphone et e-mails des clients exactement selon les exigences propres à chaque canal (l'API Conversions de Meta a ses propres règles de hachage) — ne les conservez que le temps nécessaire à cet usage, jamais au-delà du marketing de ce marchand.
• Définissez et respectez une durée de conservation pour toute donnée issue de Kayroo que vous mettez en cache (produits/commandes récupérés via l'API), et supprimez-la sur demande ou à la déconnexion d'un marchand.
• Journalisez chaque action de votre agent (campagne rédigée, marchand ayant approuvé, campagne publiée, budget modifié) de votre côté, récupérable en cas de litige d'un marchand.
• Signalez rapidement à Kayroo toute faille ou fuite d'identifiants suspectée impliquant des données marchand ou un accès au compte publicitaire.

8. Phases futures possibles — ne construisez pas encore

Voici des pistes crédibles une fois la Phase 1 en ligne et éprouvée — aucune n'est commandée, et aucune ne doit être développée avant que Kayroo ne donne son feu vert explicite. Elles sont listées ici pour que vous compreniez où cette intégration pourrait aller, pas comme un cahier des charges à démarrer.

• Agent de contenu organique — rédiger des légendes pour les réseaux sociaux et suggérer les photos de produits à associer, que le marchand publie manuellement.
• Relances automatisées de réengagement — séquences WhatsApp/e-mail ciblant les segments que GET /api/v1/customers/segments identifie déjà (paniers abandonnés, clients à risque, champions), avec le même schéma d'approbation à supervision humaine que la Phase 1. Ne réimplémentez pas la logique de segmentation — lisez-la depuis l'API.
• Assistance au contenu SEO — suggestions de titres/descriptions meta pour les pages de la boutique, lues/écrites via l'API publique plutôt que redéveloppées de zéro.

9. Comment démarrer

Il n'existe pas encore de parcours central « devenir partenaire Kayroo » — c'est une collaboration directe entre petites équipes, pas une inscription sur une place de marché.

1. Envoyez un e-mail à [email protected] pour présenter votre équipe et confirmer que vous construisez cette opportunité précise (afin que deux équipes ne dupliquent pas les efforts).
2. Lisez le guide développeur Kayroo Connect sur /developers de bout en bout.
3. Demandez à un marchand Kayroo sur le forfait Scale ou à la consommation de vous créer un jeton API de test (Admin → Jetons API) avec store.read, products.read et orders.read — cela peut être une boutique de test que vous mettez en place vous-même, puisque ce sont les forfaits sur lesquels l'accès API est disponible.
4. Construisez et testez votre intégration, la synchronisation du catalogue et le flux de rédaction/approbation de bout en bout sur cette boutique de test avant de toucher à un compte publicitaire Meta réel.

10. Des questions ?

Si un aspect de l'API, des événements webhook, ou du flux d'approbation dont ce module a besoin n'est pas couvert par ce guide ou par le guide développeur sur /developers, envoyez un e-mail à [email protected] plutôt que de deviner ou de contourner le problème.