API Campagnes #

Une campagne regroupe tout ce dont le bot IA a besoin pour communiquer avec vos contacts : ses instructions, les canaux sur lesquels il fonctionne, ses heures d’activité et son comportement de suivi. L’API Campagnes vous permet de lister, créer, mettre à jour, dupliquer, activer, archiver et affiner vos campagnes depuis votre propre code plutôt que depuis le tableau de bord.

Tous les points de terminaison ci-dessous sont relatifs à l’URL de base https://api.youraiconnector.com/v1. Chaque requête doit être authentifiée — consultez Accès à l’API et Authentification pour savoir comment obtenir et transmettre votre clé API. L’accès à l’API est une fonctionnalité payante ; sans cela, les requêtes seront rejetées avec une erreur 403.

Attention : Certains exemples montrent la forme de requête simple ?apiKey=YOUR_API_KEY, d’autres utilisent l’en-tête X-API-Key. Les deux fonctionnent partout — utilisez celle qui convient le mieux à votre configuration.

Types de campagnes #

Lorsque vous créez une campagne, vous devez choisir l’un de ces types :

La casse n’a pas d’importance. type, status, booking_provider, first_response_mode, bot.anthropic_model et bot.ai_speed acceptent tous n’importe quelle casse — "live", "Live" et "LIVE" sont la même chose — et la valeur est stockée sous sa forme canonique, qui est celle renvoyée lorsque vous lisez la campagne. La seule exception est la paire de pause : "Paused" et "paused" sont deux états réellement différents, donc une orthographe ambiguë comme "PAUSED" est rejetée avec une 400 vous demandant d’en choisir un.

Les deux états de pause #

Les deux arrêtent la campagne : le routage entrant ne fonctionne que lorsque le statut est exactement Live. Depuis l’API, utilisez Paused pour mettre en pause et Live pour reprendre — la paire en minuscules existe pour le bouton du tableau de bord et est maintenue pour celui-ci.

Aucun de ces cas ne correspond à ce qui se passe lorsque l’IA cesse de répondre au sein d’une conversation. Il s’agit d’un commutateur par contact, is_bot_active sur le contact — défini lorsqu’un humain prend le relais, lorsque le contact se désabonne ou lorsque l’IA termine la discussion. Le statut de la campagne elle-même reste inchangé et toutes les autres conversations qu’elle contient continuent de fonctionner. Voir mettre en pause ou reprendre l’IA pour un contact.

La création d’une campagne ne détermine pas qui répond à un canal. Le routage est géré par des points d’entrée sur un agent IA, et non par des campagnes. Chaque canal possède un point d’entrée par défaut qui désigne l’agent répondant aux nouveaux contacts inconnus : définissez-le avec PUT /entry-points/channel-defaults, vérifiez si l’échelle est active pour le compte avec GET /entry-points/routing-status, effacez-le avec DELETE /entry-points/channel-defaults. POST /channels/campaign écrit toujours la carte de routage de campagne héritée par canal, mais cette carte n’est plus consultée pour le routage entrant sur aucun compte ; elle est conservée uniquement pour une restauration éventuelle. Ne développez pas en vous basant sur celle-ci. Consultez Routage d’un canal vers une campagne pour voir les deux surfaces côte à côte.

Lister les campagnes #

GET /campaigns

Renvoie vos campagnes, de la plus récente à la plus ancienne. Les campagnes archivées sont exclues, sauf si vous passez archived=true.

Paramètres de requête

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Réponse

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Lorsque next_cursor est null, vous avez atteint la dernière page.

Obtenir une campagne #

GET /campaigns/{campaignId}

Renvoie le document complet de la campagne, y compris la configuration du bot en direct (bot), les paramètres de suivi, les canaux activés et tous les mots-clés. Les horodatages sont renvoyés en millisecondes depuis l’époque.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Réponse

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Créer une campagne #

POST /campaigns

Crée une nouvelle campagne. name et type sont obligatoires ; tout le reste est facultatif. Vous pouvez inclure n’importe quel autre champ de campagne dans la même requête — par exemple language, ai_mode, ou un objet de configuration bot complet — et il sera enregistré avec la nouvelle campagne. Le propriétaire et l’heure de création sont définis automatiquement.

Champs de la requête

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Mettre à jour une campagne #

PUT /campaigns/{campaignId}

Met partiellement à jour une campagne — envoyez uniquement les champs que vous souhaitez modifier. Il s’agit du seul verbe de mise à jour générale ; il n’existe pas de PATCH /campaigns/{campaignId} (les deux routes PATCH sont les bascules étroites activer et archiver).

Quels champs vous pouvez modifier. Tout ce que l’éditeur de campagne écrit, y compris name, status, type, language, ai_mode, enabled_channels, les paramètres de déclenchement et de drip, les indicateurs de réservation et de suivi, les champs de surveillance Instagram/Facebook, et toute la configuration bot. L’identité et la propriété sont verrouillées pour la durée de vie de la campagne : user, id et created_at sont rejetés, tout comme tout nom de champ que le point de terminaison ne reconnaît pas. Le rejet s’effectue par requête, et non par champ — une clé inconnue renvoie une 400 et rien dans cette requête n’est écrit.

ai_mode sur une campagne gérée par un agent reflète l’agent. Lorsqu’une campagne est répondue par un agent IA, la lecture de la campagne renvoie ai_mode dérivé du bouton Actif de cet agent — le commutateur unique qui décide réellement si l’IA répond. L’écriture de ai_mode sur une telle campagne est acceptée mais ne modifiera pas ce que vous relisez ; activez ou désactivez plutôt le bouton Actif de l’agent (dans le tableau de bord ou via l’API Agents). Sur les campagnes classiques sans agent, ai_mode lit et écrit la valeur stockée comme auparavant.

Les champs du bot fusionnent, ils ne sont pas écrasés. Envoyez les paramètres du bot soit sous forme de clés pointées ("bot.instructions": "..."), soit sous forme d’objet imbriqué ("bot": { "instructions": "..." }) — les deux écrivent feuille par feuille, de sorte que les champs que vous omettez conservent leurs valeurs actuelles. bot.instructions, bot.goal, bot.rules et bot.personality sont tous modifiables de cette manière, tout comme tout autre paramètre de bot répertorié sous Champs de configuration du bot. Il en va de même pour test_bot, frequency et follow_up_config.

Pour remplacer intégralement une configuration de bot — en supprimant tout champ que vous n’envoyez pas — utilisez bot_replace (ou test_bot_replace) avec l’objet complet. Vous ne pouvez pas combiner un remplacement et une fusion pour le même objet dans une seule requête ; cela renvoie une 400.

Quelques champs sont définis via une clé dédiée plutôt qu’écrits directement : utilisez list_id pour la liste de contacts, event_id pour le type d’événement (ou event_ids, un tableau ordonné d’ID de types d’événement, pour permettre à l’IA d’en réserver plusieurs — le premier est celui par défaut ; un tableau vide les dissocie tous), et contact_ids (un tableau d’ID de contacts) pour les contacts de la campagne. Les entrées de la base de connaissances sont gérées via l’API FAQ, et non via ce point de terminaison.

Les tags remplacent, ils ne fusionnent pas. Envoyez tags en tant que tableau complet et il deviendra l’ensemble de tags de la campagne — consultez Tags de campagne pour les champs et pour les points de terminaison qui ajoutent ou modifient un seul tag.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Supprimer une campagne #

DELETE /campaigns/{campaignId}

Supprime définitivement une campagne. Cette action est irréversible — si vous pensez avoir besoin de la campagne ultérieurement, archivez-la à la place.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Réponse

{
  "success": true
}

Dupliquer une campagne #

POST /campaigns/{campaignId}/duplicate

Crée une copie de la campagne en conservant tous ses paramètres. La copie est créée à l’état désactivé et son nom reçoit le suffixe (copy), afin qu’elle n’envoie jamais de messages tant que vous ne l’activez pas explicitement.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Réponse

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Copies en double au sein d’un même compte.

Activer ou désactiver une campagne #

PATCH /campaigns/{campaignId}/enabled

Active ou désactive une campagne. Une campagne désactivée cesse d’interagir avec les contacts mais conserve toute sa configuration.

Champs de la requête

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Archiver ou restaurer une campagne #

PATCH /campaigns/{campaignId}/archived

Archive ou restaure une campagne. Les campagnes archivées sont masquées de la liste par défaut des campagnes, mais conservent toutes leurs données et peuvent être restaurées à tout moment.

Champs de la requête

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Mettre à jour la configuration du bot #

PUT /campaigns/{campaignId}/bot-config

C’est la méthode sécurisée pour modifier les paramètres individuels d’un bot. Chaque champ envoyé est fusionné avec la configuration existante du bot ; les champs omis sont donc conservés. Utilisez cette méthode plutôt que le point de terminaison de mise à jour de campagne lorsque vous souhaitez uniquement ajuster une partie du bot.

Les clés des champs ne doivent contenir que des lettres, des chiffres, des traits de soulignement et des traits d’union.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Champs de configuration du bot #

Tous les champs du bot sont facultatifs. Envoyez uniquement ceux que vous souhaitez définir. Tout champ supplémentaire non listé ici sera accepté et stocké tel quel.

Définir les heures d’activité du bot #

PUT /campaigns/{campaignId}/active-hours

Définit le planning de disponibilité du bot. En dehors des fenêtres configurées, le bot ne répond pas automatiquement. Cela écrit dans le champ availability de la configuration du bot.

Champs de la requête

Chaque jour de la semaine contient soit une fenêtre horaire unique, soit un tableau de fenêtres. Une fenêtre possède un start_time et une end_time au format HH:MM 24 heures.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Lister les fonctions personnalisées d’une campagne #

GET /campaigns/{campaignId}/custom-functions

Renvoie les fonctions personnalisées liées à cette campagne, résolues en définitions complètes. Les fonctions personnalisées sont des actions HTTP externes que le bot peut appeler pendant une conversation — par exemple, vérifier le stock dans votre boutique ou créer un enregistrement dans votre CRM.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Réponse

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Lier une fonction personnalisée à une campagne #

POST /campaigns/{campaignId}/custom-functions

Lie une fonction personnalisée existante à cette campagne afin que le bot puisse l’appeler pendant une conversation. Lier une fonction déjà liée est une opération sans effet.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Dissocier une fonction personnalisée d’une campagne #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Dissocier une fonction qui n’est pas liée est une opération sans effet.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Lier une source de base de connaissances à une campagne #

POST /campaigns/{campaignId}/kb-sources

Lie une source de base de connaissances (créée via l’API FAQ) à cette campagne afin que le bot puisse s’y référer pour répondre. Lier une source déjà liée est une opération sans effet.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Dissocier une source de base de connaissances d’une campagne #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Dissocier une source qui n’est pas liée est une opération sans effet.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Lier un serveur MCP à une campagne #

POST /campaigns/{campaignId}/mcp-servers

Associe un serveur MCP à cette campagne, donnant au bot accès aux outils de ce serveur pendant une conversation. L’association d’un serveur déjà associé est sans effet.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Dissocier un serveur MCP d’une campagne #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

La dissociation d’un serveur qui n’est pas associé est sans effet.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Bibliothèque multimédia de la campagne #

La bibliothèque multimédia contient les images, vidéos, documents et notes vocales que le bot peut envoyer au cours d’une conversation.

Lister la bibliothèque multimédia d’une campagne #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url est une URL signée capturée au moment du téléchargement — elle peut déjà être expirée au moment où vous la relisez ; le tableau de bord la re-signe à la demande.

Télécharger un élément multimédia #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Réponse

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Mettre à jour un élément multimédia #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Modifie uniquement les métadonnées de l’élément — pour remplacer le fichier lui-même, supprimez l’élément et téléchargez-en un nouveau.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Supprimer un élément multimédia #

DELETE /campaigns/{campaignId}/media-library/{itemId}

La suppression d’un élément déjà supprimé est une opération sans effet.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Réponse

{ "success": true, "deleted": true }

Tags de campagne #

Un tag de campagne est une étiquette que vous apprenez au bot à appliquer à un contact pendant une conversation — hot-lead, not-interested, booked-a-call. Chaque tag comporte trois parties :

Les noms de tags doivent être uniques au sein d’une campagne. Le bot applique les tags par nom, donc deux entrées partageant le même nom n’ont pas de gagnant défini.

Définir tous les tags d’une campagne #

PUT /campaigns/{campaignId} avec un tableau tags.

Ceci remplace les tags de la campagne par exactement ce que vous envoyez, ce qui est la même chose que ce que fait l’onglet Tags du tableau de bord lorsque vous enregistrez. Envoyez le tableau complet à chaque fois — un tag que vous omettez est un tag que vous supprimez. Envoyer [] les efface tous.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Relisez les tags avec GET /campaigns/{campaignId}.

Ajouter un tag #

POST /campaigns/{campaignId}/tags

Ajoute un seul tag sans renvoyer le reste. Utilisez ceci lorsque vous ajoutez à un ensemble que vous n’avez pas construit dans cette requête.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Publier exactement le même tag deux fois ne fait rien la deuxième fois. Publier le même tag_id avec un nom ou une description différent ajoute une deuxième entrée plutôt que de modifier la première — utilisez le point de terminaison ci-dessous pour modifier sur place.

Mettre à jour ou supprimer un tag #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Ces derniers traitent une entrée par son tag_id, ils ne fonctionnent donc que sur les tags qui en possèdent un. Si un tag n’a pas de tag_id, modifiez-le avec le PUT /campaigns/{campaignId} de tableau complet ci-dessus.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Un tagId qui n’est pas dans la campagne renvoie 404 avec "Tag not found in campaign tags".

Basculer les canaux d’une campagne #

POST /campaigns/{campaignId}/channels

Ajoute ou supprime des canaux du tableau enabled_channels de la campagne sans renvoyer l’intégralité du tableau — plus sûr que PUT /campaigns/{campaignId} lorsqu’un autre processus pourrait modifier la campagne en même temps.

Envoyez soit une seule bascule, soit un lot — mais pas les deux dans la même requête :

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Canaux valides : whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Ceci modifie uniquement les canaux sur lesquels la campagne fait de la publicité — cela ne détermine pas qui répond à un canal. Voir Types de campagne ci-dessus et Routage d’une campagne vers les canaux entrants ci-dessous pour cela.

Comment-to-DM (Instagram et Facebook) #

Comment-to-DM transforme un commentaire sur l’une de vos publications en une conversation privée : quelqu’un commente, le bot lui envoie un message privé (DM), et la campagne prend le relais pour la suite de la conversation. Tout est configuré via l’objet de campagne, il n’y a donc aucun élément propre à l’interface utilisateur.

Connectez d’abord la page Facebook — consultez Connexion de canal. Configurez ensuite les champs ci-dessous avec PUT /campaigns/{campaignId}.

La campagne doit être Live. La surveillance des commentaires ne récupère que les campagnes dont le status est Live (toute casse — voir Types de campagne). Tout autre statut la désactive silencieusement, et un statut inventé comme "Active" est désormais rejeté avec une 400 plutôt que d’être stocké. Les statuts valides incluent Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent et Failed.

Champs

Effacement d’un champ

Ces champs sont supprimés plutôt que définis sur null lorsque vous envoyez null, afin que le bot revienne à ses valeurs par défaut : instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Une seule clé inconnue rejette toute la requête. PUT /campaigns/{campaignId} valide l’intégralité du corps de la requête par rapport à une liste autorisée. Une clé non reconnue renvoie 400 pour l’ensemble de la requête — elle n’est pas ignorée silencieusement, et aucun des autres champs de ce corps n’est enregistré.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

La réponse visible laissée sur le commentaire nécessite la fonctionnalité de réponse aux commentaires de votre forfait. Sans cela, le DM est tout de même envoyé et la réponse publique est ignorée.

Optimiser une campagne avec l’IA #

POST /campaigns/{campaignId}/optimize

Exécute la même réécriture par IA que les flux « Optimiser » et les retours « pouce vers le bas » du tableau de bord : prend vos commentaires, réécrit les instructions du bot et prépare le résultat sous forme d’une nouvelle version brouillon que vous pouvez examiner.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Réponse (202 — la réécriture s’exécute en arrière-plan)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Interrogez GET /campaigns/{campaignId} et surveillez test_bot.status : il passe immédiatement à "Optimizing", puis revient à "Draft" une fois que la réécriture est arrivée dans test_bot. À partir de là, il se comporte comme n’importe quel brouillon du tableau de bord : examinez-le, puis publiez-le dans le tableau de bord pour le mettre en ligne. Un 409 signifie qu’une optimisation est déjà en cours pour cette campagne.

L’optimisation consomme des crédits, tout comme n’importe quelle autre opération d’IA sur votre compte.

Assigner un contact à une campagne #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Ajoute un contact existant à une campagne et, si vous le demandez, envoie immédiatement le message d’ouverture de la campagne. C’est la méthode pour envoyer le modèle WhatsApp approuvé d’une campagne à un contact : le modèle avec lequel une campagne a été approuvée appartient à cette campagne, il n’apparaît donc pas dans la bibliothèque de l’API des modèles et ne peut pas être envoyé via /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Réponse

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Crédits : L’envoi du message d’ouverture d’une campagne WhatsApp est facturé comme tout envoi de modèle, au tarif correspondant au pays du destinataire et à la catégorie du modèle. Sur les autres canaux, le message d’ouverture est un message sortant classique.

Acheminer une campagne vers les canaux entrants #

Ces points de terminaison gèrent la campagne qui répond aux nouveaux contacts inconnus sur un canal. Privilégiez les points d’entrée pour les nouvelles intégrations (voir la note sous Types de campagne) — ils restent utiles pour travailler avec des campagnes acheminées de l’ancienne manière, et pour résoudre un conflit de propriété de canal entre deux campagnes entrantes.

Assigner une campagne aux canaux entrants #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Réponse

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels répertorie uniquement les canaux qui ont été réellement acheminés vers cette campagne ; failed répertorie ceux qui ne l’ont pas été. Si tous les canaux demandés échouent, la requête elle-même échoue.

Effacer l’acheminement entrant d’une campagne #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Réponse

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Réactiver une campagne dormante #

POST /campaigns/{campaignId}/reactivate

Rétablit une campagne depuis Ended, Completed, Paused ou Draft et récupère ses canaux. Fonctionne uniquement sur les campagnes Incoming from Unknown Contacts ou Combined — une campagne déjà Live est considérée comme réussie et ne nécessite aucune action.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Un canal déjà réclamé par l’agent d’une autre campagne apparaît dans channelsBlockedByConflict au lieu de faire échouer l’appel entier — utilisez arrêter une campagne entrante en conflit ci-dessous pour le libérer d’abord si vous souhaitez que cette campagne le reprenne. Un 400 est renvoyé pour un type de campagne qui ne prend pas en charge la réactivation, ou pour un statut qui ne fait pas partie des statuts inactifs ci-dessus.

Arrêter une campagne entrante en conflit #

POST /campaigns/{campaignId}/stop-incoming

Libère les canaux de cette campagne de toute AUTRE campagne qui les détient actuellement, afin que cette campagne puisse les réclamer ensuite. Il s’agit de la version REST de ce que le tableau de bord fait automatiquement lorsque vous lancez une campagne entrante sur un canal déjà utilisé par quelqu’un d’autre.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels renvoie une valeur vide lorsque cette campagne possède déjà tous les canaux qu’elle annonce — il n’y a rien à reprendre.

Estimations de coûts #

Estimez le coût du lancement d’une campagne avant de l’envoyer.

Estimation du coût d’un modèle WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode est "credits" sur la voie WhatsApp gérée. Sur une voie où Meta facture directement votre propre compte WhatsApp Business, costPerContact, subtotal et totalTemplateCost renvoient null — jamais 0, ce qui serait interprété comme gratuit — car il n’y a aucun montant de crédit à signaler.

Estimation du coût des SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

Les SMS sont toujours envoyés via votre propre compte Twilio (voir fournisseur SMS), ils sont donc toujours facturés directement par Twilio — estimatedCostUsd est une estimation de cette facture Twilio, et non un débit de crédit.

Vérifications de limites #

Vérifiez une limite avant de lancer, au lieu de le découvrir après un échec d’envoi.

Vérifications au niveau de la campagne #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — indique si le lancement ou la planification de cette campagne dépasserait la limite de messagerie de crédits IA de votre compte.

GET /campaigns/{campaignId}/limits/messaging — indique si cela dépasserait la limite de messagerie quotidienne de votre compte.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Réponse (limite non dépassée)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Une 400 est renvoyée à la place lorsque la limite est dépassée, avec la raison dans error.

Vérifications au niveau du compte #

GET /campaigns/limits/campaigns — indique si vous avez atteint la limite de création de campagnes mensuelle de votre abonnement.

GET /campaigns/limits/contacts — indique si vous avez atteint la limite de contacts de votre abonnement.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Totaux des statistiques de campagne #

GET /campaigns/stats/totals

Totaux des messages envoyés et des réponses pour chaque campagne ET chaque agent IA de votre compte, sur une fenêtre glissante — les mêmes chiffres que ceux affichés sur la page de liste des campagnes à côté de chaque ligne, en un seul appel au lieu d’une requête par campagne.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent est son propre cumul, et non une somme de byCampaign — le trafic d’un compte natif AI-Agent peut ne comporter aucune campagne, il serait donc autrement invisible ici.

Tester une campagne dans le terrain de jeu (playground) #

Le terrain de jeu vous permet d’avoir une conversation avec le bot d’une campagne sans toucher à un canal réel ou à un contact réel. Il s’agit du même environnement de test que le panneau d’essai du tableau de bord, et il est entièrement disponible via l’API.

Le flux est le suivant : créer un contact de test masqué, envoyer un message, puis interroger la campagne pour obtenir la réponse du bot. Les réponses sont générées de manière asynchrone, elles arrivent donc dans test_messages sur la campagne plutôt que dans le corps de la réponse.

Le Playground utilise les crédits de coût de l’API. Une conversation de test démarrée avec une clé API est facturée au tarif normal des messages IA, identique à une réponse réelle, et apparaît dans votre historique d’utilisation comme une entrée classique. Les tests effectués depuis le tableau de bord restent gratuits. Cette différence est intentionnelle : un test effectue le même travail d’IA qu’une exécution en direct ; un Playground API non facturé permettrait donc d’utiliser l’IA de manière illimitée aux frais de quelqu’un d’autre.

Étape 1 - Créer le contact de test #

POST /campaigns/{campaignId}/try-out/contact

Crée le contact de test masqué et le lie à la campagne. Tous les champs du corps de la requête sont facultatifs ; tout ce que vous omettez est remplacé par une identité d’exemple intégrée (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Réponse

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Étape 2 - Enregistrer le message entrant #

POST /campaigns/{campaignId}/try-out/messages

Ajoute des messages au fil de discussion de test. Envoyez d’abord le message du visiteur ici, afin qu’il apparaisse dans l’historique de la conversation que le bot lit.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Étape 3 - Demander au bot de répondre #

POST /campaigns/{campaignId}/try-out/test-message

Transmet le message au pipeline d’IA. C’est l’appel qui génère réellement une réponse du bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Réponse

{
  "success": true,
  "data": "Published"
}

"Published" signifie que le message a été transmis au pipeline d’IA. "Ignored" signifie qu’un message de test plus récent a remplacé celui-ci — le terrain de jeu (playground) regroupe une rafale rapide en une seule réponse, environ quatre secondes après le dernier message, de la même manière qu’une vraie conversation attend que quelqu’un finisse de taper. En raison de cette fenêtre de regroupement, cet appel prend quelques secondes à renvoyer une réponse.

Étape 4 - Lire la réponse #

GET /campaigns/{campaignId}

La réponse du bot est ajoutée au tableau test_messages de la campagne. Interrogez la campagne jusqu’à ce qu’une nouvelle entrée outbound apparaisse.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Réinitialiser le terrain de jeu #

POST /campaigns/{campaignId}/try-out/reset

Efface tout le bac à sable : supprime le contact de test, vide test_messages et libère les verrous de réponse du bot. À utiliser entre deux exécutions de test.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Autres points de terminaison du terrain de jeu #

Erreurs de l’API Campagnes #

Les points de terminaison de campagne renvoient l’enveloppe d’erreur standard :

{
  "success": false,
  "error": "Campaign not found"
}

Les codes partagés que chaque point de terminaison peut renvoyer — 401, 403 (votre forfait n’inclut pas l’accès à l’API), 429 (limite de débit) et 500 — sont répertoriés avec des conseils de nouvelle tentative dans Erreurs et pagination.

Connexe #

• Diriger un canal vers une campagne — pointez Instagram, WhatsApp ou tout autre canal vers l’agent IA qui doit y répondre, en utilisant les points d’entrée.
• Générer des modèles de suivi avec l’IA — lancez une tâche de fond qui rédige les modèles de suivi WhatsApp d’une campagne.
• API FAQ — gérez les entrées de questions-réponses utilisées par vos campagnes.
• Accès API — générez votre clé API.
• Authentification — toutes les méthodes pour transmettre votre clé.