API de diffusions #

Une diffusion est un envoi sortant unique : une audience, un message d’ouverture, un canal et une planification. Elle nomme également, de manière optionnelle, l’agent IA qui gère les réponses reçues. L’API de diffusions vous permet de créer, tarifer, lancer et surveiller ces envois depuis votre propre code plutôt que depuis le tableau de bord. Pour le produit lui-même, consultez le guide des diffusions.

• URL de base — https://api.youraiconnector.com/v1
• Authentification — votre clé API (voir Authentification)
• Erreurs et pagination — voir Erreurs et pagination

Tous les exemples ci-dessous utilisent le format de requête ?apiKey= en cURL et l’en-tête X-API-Key en JavaScript et Python — les deux fonctionnent sur chaque point de terminaison.

Dans l’explorateur d’API. Chaque point de terminaison sur cette page figure dans la spécification OpenAPI publiée, vous pouvez donc parcourir ses champs exacts et exécuter des requêtes en direct dans l’explorateur d’API.

Comment un envoi est structuré #

L’envoi d’une diffusion se fait en quatre appels, et non un seul :

1. Créer la diffusion avec son audience, son canal et sa planification — elle commence en tant que Draft.
2. Définir le message d’ouverture. Sur WhatsApp Business, cela signifie soumettre un modèle pour approbation (ou en choisir un déjà approuvé). Sur tout autre canal, il s’agit de texte brut.
3. Estimer le coût si vous souhaitez vérifier le prix avant de dépenser quoi que ce soit (optionnel).
4. Le lancer. Le lancement effectue une vérification complète — audience, message, approbation du modèle, expéditeur connecté — et soit démarre l’envoi, soit vous indique exactement ce qui manque.

Rien n’est envoyé tant que vous n’appelez pas le lancement.

L’objet de diffusion #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Les horodatages sont renvoyés en millisecondes d’époque (execution_date, created_at, last_modified_at, …), et toute référence de contact est renvoyée sous forme de chaîne de chemin comme contacts/uid_whatsapp_15551234567.

Champs que vous définissez #

Tout ce que vous envoyez en tant que user_id, id, status ou source_campaign_id est ignoré lors de la création et supprimé lors de la mise à jour — le statut ne change qu’à travers les points de terminaison de lancement, de pause et de reprise ci-dessous.

Champs maintenus par la plateforme #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, les compteurs de lots, et contacts (les contacts individuels joints depuis le tableau de bord, lus sous forme de chaînes de chemin). Lisez-les, ne les écrivez pas.

Statuts #

Créer une diffusion #

POST /broadcasts — crée une Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Réponse (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Lister les diffusions #

GET /broadcasts — toutes les diffusions du compte, de la plus récente à la plus ancienne.

Paramètres de requête

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Réponse (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Obtenir une diffusion #

GET /broadcasts/{broadcastId} — retourne { "success": true, "broadcast": { ... } }. Utilisez-le pour interroger un envoi en cours : total_contacts_sent, unique_contacts_replied, overall_reply_rate et credits_used se mettent à jour au fur et à mesure.

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

Une diffusion qui n’existe pas sur votre compte retourne 404.

Mettre à jour une diffusion #

PUT /broadcasts/{broadcastId} — envoyez uniquement les champs que vous souhaitez modifier. Vous pouvez également cibler une clé unique à l’intérieur d’un objet imbriqué avec un chemin pointé, par ex. "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Un corps vide retourne 400. Deux règles à connaître :

• opener_media est tout ou rien. Envoyez l’objet complet, ou null pour supprimer la pièce jointe. Un chemin pointé vers celle-ci (opener_media.name) est rejeté avec 400, car une pièce jointe partiellement mise à jour décrirait un fichier inexistant.
• Le statut n’est pas modifiable. Utilisez lancer, mettre en pause et reprendre.

Le message d’ouverture #

Chaque diffusion contient son message d’ouverture dans whats_app_template. La signification de ce champ dépend du canal :

• WhatsApp Business — il doit s’agir d’un modèle approuvé par WhatsApp. Utilisez l’un des deux points de terminaison ci-dessous.
• Tous les autres canaux (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — le body du même champ est simplement le texte envoyé. Le soumettre via le point de terminaison ci-dessous l’enregistre et le marque comme prêt sans aucune intervention de WhatsApp.

Soumettre un modèle pour approbation #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Réponse (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status correspond à ce que dit WhatsApp : pending pendant l’examen, approved lorsqu’il est utilisable, rejected s’il a été refusé. Sur un canal autre que WhatsApp, la réponse est directement approved avec template_sid: null — rien à examiner.

Ce qui peut vous bloquer :

• Soumettre une demande alors qu’un modèle précédent est en cours d’examen renvoie 400. Attendez d’abord la décision.
• Modifier un modèle actuellement approuvé maintient le modèle approuvé actif jusqu’à ce que le nouveau soit validé, afin qu’une diffusion en cours ne perde jamais son message d’ouverture.
• Sur un numéro WhatsApp connecté directement via Meta, une diffusion avec une image ou une vidéo jointe ne peut pas être soumise (400) — les pièces jointes sont prises en charge sur le canal WhatsApp Business géré et sur WhatsApp Web.

Utiliser un modèle déjà approuvé #

POST /broadcasts/{broadcastId}/template/select — copie un modèle déjà approuvé depuis votre bibliothèque de modèles vers la diffusion, il n’y a donc rien à attendre.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Réponse (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

L’approbation est vérifiée de notre côté à partir de l’enregistrement de la bibliothèque — vous n’envoyez que l’identifiant. Vous recevrez une erreur 400 si la diffusion n’est pas un brouillon WhatsApp, si le modèle n’est pas approuvé, s’il s’agit d’un modèle de suivi plutôt que d’un message d’ouverture, ou si la diffusion contient une pièce jointe (les modèles de la bibliothèque sont uniquement textuels). Un identifiant de modèle qui ne figure pas sur votre compte renvoie 404.

Estimer le coût #

POST /broadcasts/{broadcastId}/estimate-cost — calcule le prix de l’envoi avant que vous ne vous engagiez. Disponible sur les diffusions whatsapp et sms ; tout autre canal renvoie 400. La diffusion nécessite un list_id, car l’estimation prend en compte l’audience.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

Réponse WhatsApp (200) — crédits, ventilés par pays de destination :

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

Réponse SMS (200) — Dollars américains, basés sur la tarification Twilio en temps réel pour votre propre compte Twilio :

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Lisez billing_mode avant d’afficher un numéro. Cela vous indique qui est facturé :

Les SMS sans identifiants Twilio connectés renvoient toujours le nombre de segments, avec estimatedCostUsd: 0 — il n’y a pas de tarification à consulter.

Lancer une diffusion #

POST /broadcasts/{broadcastId}/launch

Le lancement vérifie tout d’abord, puis fait avancer la diffusion. Il n’y a pas de lancement partiel : soit elle démarre, soit rien ne change et vous recevez un message d’erreur expliquant pourquoi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Réponse (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status est l’endroit où la diffusion a abouti :

• Scheduled — execution_date est dans le futur.
• Sending — elle a démarré maintenant.
• Pending Approval — le modèle WhatsApp est toujours en cours d’examen. Il s’enverra automatiquement dès que le modèle sera approuvé ; ne relancez pas le lancement.

Seule une diffusion Draft (ou une diffusion Pending Approval dont le modèle a été approuvé entre-temps) peut être lancée — toute autre situation renvoie 400.

Pourquoi un lancement est refusé #

Chacun de ces cas est renvoyé sous forme de 400 avec un message error en langage clair :

Mettre en pause et reprendre #

POST /broadcasts/{broadcastId}/pause arrête une diffusion Sending ou Scheduled et supprime tout ce qui est en file d’attente.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Mettre en pause une diffusion Pending Approval la remet à Draft à la place — rien n’était encore planifié, il n’y a donc rien à reprendre. Tout autre statut renvoie 400.

POST /broadcasts/{broadcastId}/resume redémarre une diffusion Paused :

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Réponse (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Elle reprend en Sending, ou revient en Scheduled si son execution_date est toujours dans le futur. Seule une diffusion Paused peut être reprise.

Continuer l’envoi après une pause due à un faible engagement #

POST /broadcasts/{broadcastId}/override-engagement-guard

Pendant qu’une diffusion est envoyée par lots, nous mesurons combien de personnes ont répondu à chaque lot avant de commencer le suivant. Si presque personne ne répond, la diffusion se met en pause d’elle-même — un envoi qui continue de pousser dans le silence est le moyen le plus rapide de se faire filtrer ou bloquer un numéro. C’est le bouton Continuer quand même dans le tableau de bord.

Comme le taux de réponse qui a causé la pause ne peut pas changer pendant que la diffusion est arrêtée, une simple reprise serait à nouveau mise en pause lors de la vérification suivante. Ce point de terminaison est la décision de continuer malgré tout : il enregistre le remplacement sur cette diffusion spécifique et lève la pause lors du même appel si la diffusion était en pause pour faible engagement.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Réponse (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — la diffusion a été mise en pause pour faible engagement et est maintenant à nouveau en cours ; status est l’état vers lequel elle a repris.
• resumed: false — rien n’a été levé, le remplacement est simplement enregistré pour les vérifications futures. C’est ce que vous obtenez si la diffusion n’a jamais été mise en pause, ou si elle a été mise en pause pour une raison différente (vous l’avez mise en pause manuellement, une limite d’envoi a été atteinte, ou trop d’envois ont échoué). Ces pauses ne sont pas levées ici — reprenez-la vous-même une fois que vous avez traité la cause.

Le remplacement s’applique uniquement à cette diffusion. Ce n’est pas un paramètre de compte, et il est sûr de l’appeler deux fois.

Dupliquer une diffusion #

POST /broadcasts/{broadcastId}/duplicate — copie l’audience, le message et les paramètres dans un nouveau Draft. Tout ce qui concerne l’exécution précédente (compteurs, lots, planification, statistiques de réponse) repart à zéro.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Réponse (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Une copie n’hérite jamais d’une approbation WhatsApp en direct : sur une copie WhatsApp, le modèle doit être confirmé par vos soins, et sur une copie vers un autre canal, il est supprimé et le texte devient l’ouverture simple. La copie vers SMS supprime également toute pièce jointe, car les SMS ne peuvent pas en envoyer.

Supprimer une diffusion #

DELETE /broadcasts/{broadcastId}

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

Une diffusion Sending ou Scheduled est refusée avec 400 — mettez-la d’abord en pause.

Diffusions qui reflètent une campagne classique #

Les campagnes classiques qui envoient des messages apparaissent également dans les Diffusions, et l’API les renvoie aux côtés des diffusions natives (elles portent un source_campaign_id). Elles se comportent un peu différemment, car la campagne reste aux commandes :

• La modification de l’audience, du message ou de la planification fonctionne et est répercutée sur la campagne.
• Le canal, l’agent de réponse, la pièce jointe et tous les compteurs d’exécution sont en lecture seule ici — 400 si vous essayez de les modifier. Modifiez-les sur la campagne.
• Le lancement renvoie 400 vous redirigeant vers l’éditeur de campagne.
• La mise en pause et la reprise fonctionnent et agissent sur la campagne.
• La suppression renvoie 400 — supprimez plutôt la campagne, et son entrée dans les Diffusions disparaîtra avec elle.
• La duplication vous donne une diffusion native indépendante, ce qui est la méthode prise en charge pour transférer une campagne éprouvée.

Erreurs #

Les requêtes ayant échoué renvoient {"success": false, "error": "<message>"} avec ces statuts :

Étapes suivantes #

• Guide des diffusions — le produit derrière ces points de terminaison, y compris le rythme et le comportement de sécurité
• API Contacts — construisez la liste vers laquelle une diffusion est envoyée
• API Modèles — gérez les modèles WhatsApp approuvés que vous pouvez sélectionner
• API Webhooks — abonnez-vous à Broadcast Started et Broadcast Completed au lieu d’interroger