Créer une intégration de bout en bout

Ce guide vous accompagne dans tout ce dont vous avez besoin pour exécuter Your AI Connector depuis votre propre code, sans jamais ouvrir le tableau de bord. À la fin, vous aurez construit une intégration minimale qui :

S’authentifier avec une clé API
Créer un agent IA et configurer son comportement d’assistant
Connecter un canal de messagerie (nous utilisons WhatsApp Web comme exemple pratique) et le diriger vers l’agent
Importer des contacts
Envoyer et lire des messages
Lire les analyses
S’abonner aux webhooks pour des événements en temps réel

Chaque étape renvoie vers le guide de ressources complet afin que vous puissiez approfondir les détails si nécessaire. Cette page est la carte ; les guides de ressources sont le terrain.

Avant de commencer. L’accès à l’API est une fonctionnalité payante. Si votre forfait ne l’inclut pas, chaque requête renverra 403. Consultez Accès API pour confirmer qu’il est activé, et Authentification pour connaître toutes les façons de transmettre votre clé.

Tous les chemins ci-dessous sont relatifs à l’URL de base :

https://api.youraiconnector.com/v1

Étape 1 — Obtenir une clé API et effectuer votre première requête

Votre clé API se trouve dans l’application sous Paramètres → Intégrations → Clé API — sa propre section sous Intégrations, distincte des Webhooks, qui n’apparaît que si l’accès API est inclus dans le forfait. Générez-en une, copiez-la et stockez-la dans un endroit sûr (un coffre-fort de secrets côté serveur ou une variable d’environnement — jamais dans le code du navigateur). Les instructions complètes sont disponibles dans Accès API.

Une fois que vous avez une clé, confirmez qu’elle fonctionne en appelant le point de terminaison de santé. Il existe plusieurs façons d’envoyer la clé ; la plus simple est le paramètre de requête ?apiKey=, mais pour du code réel, préférez l’en-tête X-API-Key afin que la clé ne se retrouve jamais dans les journaux du serveur ou l’historique du navigateur.

cURL

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

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Chaque réponse réussie est enveloppée dans la même structure — un champ success: true ainsi que les données de résultat. Les erreurs renvoient success: false avec un message error et un error_code. Consultez Erreurs et pagination pour la liste complète et pour savoir comment les points de terminaison de liste paginent avec ?limit et ?cursor.

Limite de débit. Les requêtes authentifiées sont limitées à 300 par minute (avec un plafond plus large de 1 200 par minute par compte). Tout dépassement renvoie 429 ; veuillez patienter et réessayer.

Étape 2 — Créer un agent IA

Un agent IA est l’unité qui contient le comportement de votre assistant : ses instructions, son objectif, ses heures d’activité et sa manière de communiquer avec les contacts. C’est lui qui répond aux conversations, c’est donc la première chose à créer.

Créez-en un avec POST /agents. name est le seul champ qui mérite d’être envoyé au départ ; tout le reste peut être défini avec l’appel bot-config ci-dessous.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

Une création réussie renvoie 201 avec le nouvel ID :

{
  "success": true,
  "agent_id": "abc123agent"
}

Enregistrez l’identifiant agent_id — vous y ferez référence lors du routage des canaux.

Configurer l’assistant

PUT /agents/{agentId}/bot-config définit le comportement de l’assistant. Il fusionne les champs que vous envoyez avec la configuration existante, donc tout ce que vous omettez est préservé :

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Définissez les heures d’activité avec PUT /agents/{agentId}/active-hours afin que l’assistant ne réponde que pendant les heures de bureau ; en dehors de ces plages, il ne répond pas automatiquement.

Base de connaissances. Pour que l’assistant réponde à partir de votre propre contenu, joignez des FAQ. Consultez le guide des FAQ.

Héritage : campagnes classiques. Les comptes qui possèdent encore une page Campagnes créent le même comportement d’assistant sur une campagne à la place (POST /campaigns avec un objet type et bot, puis PUT /campaigns/{campaignId}/bot-config). La liste complète des champs de campagne et les contrôles de cycle de vie se trouvent dans le guide des campagnes. Si vous développez quelque chose de nouveau, créez un agent.

Étape 3 — Connecter un canal

Un agent a besoin d’un moyen d’envoyer et de recevoir des messages. Sept flux de connexion peuvent être pilotés depuis l’API : WhatsApp Business, WhatsApp Web, Instagram et Messenger ensemble (un flux Meta partagé), les comptes personnels Instagram, Telegram, LINE et Viber. Les autres canaux — SMS, e-mail, widget de chat et canaux personnalisés entre autres — sont configurés dans le tableau de bord plutôt que via REST, et une fois connectés, les points de terminaison de messagerie, de contact et de routage fonctionnent exactement de la même manière. GET /channels est la source de vérité en temps réel pour ce qui est réellement connecté à un compte donné :

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

L’ensemble complet des flux de connexion/déconnexion pour chaque canal est documenté dans le Guide des canaux. Ci-dessous, nous parcourons WhatsApp Web de bout en bout, car il présente le modèle le plus intéressant : un flux de couplage par code QR que votre wrapper doit rendre et interroger.

Exemple pratique : coupler WhatsApp Web par code QR

Le couplage WhatsApp Web est une danse en trois appels — démarrer, récupérer le QR, interroger jusqu’à la connexion.

1. Démarrer la session de couplage. Indiquez le numéro que vous souhaitez connecter au format E.164.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Récupérer le code QR et le montrer à l’utilisateur. Interrogez ce point de terminaison toutes les 10 à 15 secondes. La réponse inclut la charge utile qr_code brute (rendez-la vous-même sous forme d’image QR) et une qr_data_url prête à être affichée.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

Dans l’interface utilisateur de votre wrapper, insérez qr_data_url directement dans une <img src="..."> et demandez à l’utilisateur de le scanner depuis WhatsApp → Appareils connectés sur son téléphone. Si le QR expire (une réponse 410), recommencez à partir de l’étape 1 pour en obtenir un nouveau.

3. Interroger le statut jusqu’à la connexion. Une fois que l’utilisateur a scanné, continuez à interroger le point de terminaison de statut jusqu’à ce qu’il indique connected (le service peut également signaler open). Traitez disconnected et not_initialized comme des échecs terminaux.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Attention. Chaque numéro WhatsApp Web connecté entraîne des frais de maintenance mensuels récurrents jusqu’à ce que vous le déconnectiez (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Router le canal vers votre agent

Connecter un canal le rend fonctionnel ; le router indique à la plateforme quel agent IA doit répondre aux toutes nouvelles conversations entrantes sur celui-ci. Définissez le point d’entrée par défaut du canal, en nommant l’agent que vous avez créé à l’étape 2 :

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Répétez l’appel une fois par canal — un point d’entrée par défaut par canal. Pour laisser un canal sans agent pour y répondre, appelez DELETE /entry-points/channel-defaults?channel=whatsapp_web ; pour vérifier si la hiérarchie des points d’entrée est active pour le compte, appelez GET /entry-points/routing-status. L’ancien mappage POST /channels/campaign est conservé uniquement pour le retour en arrière et n’est plus consulté pour le routage entrant. Consultez le guide des canaux pour les autres types de canaux et pour le flux OAuth de WhatsApp Business.

Étape 4 — Importer vos contacts

Une fois le canal actif, chargez les personnes que vous souhaitez atteindre. Le point de terminaison d’importation accepte jusqu’à 500 enregistrements par appel. Chaque enregistrement nécessite un phone_number au format international ; tout le reste est facultatif. Les enregistrements contenant des numéros incorrects, des canaux non pris en charge ou des numéros déjà existants sont ignorés — et chaque omission est signalée avec son index et sa raison, afin que vous puissiez réessayer uniquement les échecs.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

La réponse vous indique exactement ce qui s’est passé :

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Pour la création un par un, la liste/recherche, les listes, les étiquettes et les champs personnalisés, consultez le Guide des contacts.

Étape 5 — Envoyer et lire des messages

Envoyer un message

L’envoi le plus simple est indépendant du canal : indiquez l’identité du contact et le corps du message, et la plateforme le délivre sur le canal utilisé par le contact. Vous pouvez cibler par contact_id, ou par channel plus le champ d’identité correspondant (phone_number pour WhatsApp/WhatsApp Web/SMS, instagram_id pour Instagram, et ainsi de suite).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

La livraison est asynchrone — un 201 signifie que le message a été accepté et mis en file d’attente, et non encore délivré. (Les contacts ayant activé le mode « ne pas déranger » ou le mode privé sont rejetés avec un 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Lire une conversation

Pour lire les messages en retour, listez-les par contact, du plus récent au plus ancien, avec une pagination par curseur. Transmettez le next_cursor d’une réponse en tant que cursor de la suivante pour parcourir l’historique.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

Vous pouvez également filtrer par type de contenu (?filter=text|media|tool_use) ou par direction (?direction=inbound|outbound). Le Guide des messages couvre les pièces jointes, le marquage des messages comme lus et les vues des messages par session.

Ne pas interroger les réponses. Lister les messages sur une minuterie fonctionne, mais cela gaspille des requêtes et ajoute de la latence. Pour les messages entrants, utilisez plutôt des webhooks — c’est l’étape 7.

Étape 6 — Lire les analyses

Une fois que les messages circulent, le résumé analytique vous donne des totaux agrégés sur une plage de dates : envoyés, livrés, lus, répondus, réservés, contacts créés et crédits dépensés/rechargés. Vous obtenez à la fois les totaux sur la période et une série quotidienne remplie de zéros, idéale pour un graphique de tableau de bord. Vous pouvez éventuellement limiter la portée à une seule campagne avec campaign_id (les exemples ci-dessous utilisent un identifiant de campagne fictif, abc123campaign) ; omettez le paramètre pour obtenir les totaux à l’échelle du compte.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

La plage par défaut est de 30 jours et est limitée à 366. Pour des enregistrements d’utilisation crédit par crédit et des ventilations des coûts de l’IA, consultez le guide des analyses.

Étape 7 — S’abonner aux webhooks pour des événements en temps réel

Le polling est acceptable pour un script rapide, mais une véritable intégration doit être basée sur le push. Les webhooks permettent à la plateforme d’appeler votre serveur dès qu’un événement se produit — un nouveau contact, une réponse, un rendez-vous réservé, une discussion terminée.

Tout d’abord, découvrez les noms exacts des événements auxquels vous pouvez vous abonner :

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Créez ensuite un abonnement pointant vers une URL HTTPS sur votre serveur. Utilisez les chaînes d’événements exactes de l’appel ci-dessus.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

L’URL doit utiliser HTTPS et être accessible publiquement. À partir de là, votre serveur reçoit un POST pour chaque événement auquel vous êtes abonné. Vous pouvez envoyer une livraison de test, vérifier l’état d’un abonnement et réactiver un abonnement qui a été automatiquement désactivé après des échecs répétés — consultez le guide des webhooks et la page Webhooks au niveau des intégrations pour connaître les structures de charge utile et la vérification.

Synthèse

Voici l’ensemble du flux en un coup d’œil :

Étape	Objectif	Appel clé
1	Authentification	`GET /health`
2	Créer + configurer l’assistant	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Connecter un canal et le router	`POST /channels/whatsapp-web/connections` → scanner QR + statut → `PUT /entry-points/channel-defaults`
4	Charger les contacts	`POST /contacts/import`
5	Envoyer et lire	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Mesurer	`GET /analytics/summary`
7	Réagir en temps réel	`POST /webhooks`

Un wrapper minimal consiste simplement en ces sept appels intégrés à votre propre interface utilisateur. À partir de là, ajoutez les guides par ressource selon vos besoins :

Campagnes · Contacts · FAQ · Messages · Rendez-vous
Canaux · Modèles · Analyses · Webhooks · Clés API
Nouveau ici ? Démarrage · Authentification · Erreurs et pagination

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Créer une intégration de bout en bout #

Étape 1 — Obtenir une clé API et effectuer votre première requête #

Étape 2 — Créer un agent IA #

Configurer l’assistant #

Étape 3 — Connecter un canal #

Exemple pratique : coupler WhatsApp Web par code QR #

Router le canal vers votre agent #

Étape 4 — Importer vos contacts #

Étape 5 — Envoyer et lire des messages #

Envoyer un message #

Lire une conversation #

Étape 6 — Lire les analyses #

Étape 7 — S’abonner aux webhooks pour des événements en temps réel #

Synthèse #

Créer une intégration de bout en bout

Étape 1 — Obtenir une clé API et effectuer votre première requête

Étape 2 — Créer un agent IA

Configurer l’assistant

Étape 3 — Connecter un canal

Exemple pratique : coupler WhatsApp Web par code QR

Router le canal vers votre agent

Étape 4 — Importer vos contacts

Étape 5 — Envoyer et lire des messages

Envoyer un message

Lire une conversation

Étape 6 — Lire les analyses

Étape 7 — S’abonner aux webhooks pour des événements en temps réel

Synthèse