# 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](../broadcasts/broadcasts.md).

- **URL de base** — `https://api.youraiconnector.com/v1`
- **Authentification** — votre clé API (voir [Authentification](authentication.md))
- **Erreurs et pagination** — voir [Erreurs et pagination](errors-and-pagination.md)

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](reference.md).


---

## 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

```json
{
  "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

| Champ | Description |
|---|---|
| `name` | Le nom de la diffusion tel qu'il apparaît dans le tableau de bord. |
| `channel` | Le canal unique sur lequel cette diffusion est envoyée : `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. Une diffusion possède exactement un canal — pour envoyer le même contenu ailleurs, [dupliquez-la sur un autre canal](#duplicate-a-broadcast). `tiktok` et `skool` sont réservés aux réponses et ne peuvent jamais être utilisés pour une diffusion. |
| `agent_id` | L'agent IA qui répond aux messages. Laissez ce champ `null` pour que les réponses arrivent dans la boîte de réception de votre équipe. |
| `list_id` | La liste de contacts à laquelle envoyer le message. C'est ainsi que vous définissez l'audience via l'API — consultez [Contacts](contacts.md) pour savoir comment créer et remplir des listes. |
| `list_name` | Nom d'affichage indiqué à côté de la diffusion. Purement cosmétique. |
| `send_to_new_list_members` | `true` maintient la diffusion active afin que toute personne ajoutée ultérieurement à la liste reçoive également le message d'ouverture. |
| `whats_app_template` | Le message d'ouverture. Sur WhatsApp Business, il s'agit d'un modèle approuvé ; sur tous les autres canaux, son `body` est utilisé comme texte d'ouverture brut. Définissez-le via les [points de terminaison de modèles](#the-opening-message), et non manuellement. |
| `opener_media` | Une image ou une vidéo envoyée avec le message d'ouverture. Envoyez toujours l'objet complet (ou `null` pour le supprimer) — l'écriture de clés individuelles à l'intérieur sera rejetée. Non pris en charge sur SMS. |
| `execution_date` | Moment de l'envoi. Envoyez un horodatage ISO 8601 ou une valeur en millisecondes (epoch). Une date future planifie l'envoi ; omettez ce champ (ou utilisez une date passée) pour envoyer dès le lancement. |
| `drip_mode` | `true` rythme l'envoi par lots au fil du temps au lieu de tout envoyer d'un coup. |
| `time_critical` | `true` désactive le rythme automatique qui s'active au-delà de 50 contacts — pour une audience chaleureuse qui doit recevoir le message immédiatement. Cela ne lève pas la limite d'envoi quotidienne propre au canal. |
| `batch_size` | Nombre de contacts par lot lors d'un envoi progressif. |
| `follow_up_config` | La chaîne de suivi pour les contacts qui ne répondent jamais. |

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

| Statut | Signification |
|---|---|
| `Draft` | En cours de création. Rien n'est planifié. |
| `Pending Approval` | Lancé, mais son modèle WhatsApp est en attente de décision. L'envoi démarrera automatiquement une fois le modèle approuvé — vous n'avez pas besoin de le relancer. |
| `Scheduled` | Lancé avec une `execution_date` future. |
| `Sending` | En cours d'envoi (une diffusion activée pour de nouveaux membres de liste reste dans cet état en attendant ces derniers). |
| `Paused` | Suspendu — par vous-même ou automatiquement par une vérification de sécurité. |
| `Sent` | Terminé. |
| `Failed` | Terminé avec plus de la moitié des envois en échec. |

---

## Créer une diffusion

`POST /broadcasts` — crée une `Draft`.

**cURL**

```bash
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**

```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**

```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`)

```json
{ "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**

| Paramètre | Requis | Description |
|---|---|---|
| `status` | Non | Retourne uniquement les diffusions ayant un statut spécifique, par ex. `Sending`. Respectez exactement l'orthographe du [tableau des statuts](#statuses). |

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

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

```python
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`)

```json
{ "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.

```bash
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"`.

```bash
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" }'
```

```javascript
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](#launch-a-broadcast), [mettre en pause](#pause-and-resume) et [reprendre](#pause-and-resume).

---

## 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`

| Champ | Requis | Description |
|---|---|---|
| `body` | Oui | Le texte du message, jusqu'à 1024 caractères. Utilisez les espaces réservés `{{variable}}` pour la personnalisation. |
| `name` | Non | Nom du modèle. Par défaut, il s'agit du nom de la diffusion. |
| `language` | Non | Code de langue. La valeur par défaut est `en`. |
| `category` | Non | `marketing` (par défaut), `utility`, `authentication` ou `authentication-international`. C'est ce qui détermine le prix de l'envoi, soyez donc honnête. |
| `variables` | Non | Les noms des espaces réservés, dans l'ordre où ils apparaissent. Laissez ce champ vide pour qu'ils soient lus à partir du corps du message — ce qui est généralement préférable, car l'envoi les remplit à partir de chaque contact. |

```bash
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`)

```json
{ "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](templates.md) vers la diffusion, il n'y a donc rien à attendre.

| Champ | Requis | Description |
|---|---|---|
| `template_id` | Oui | L'identifiant d'un modèle approuvé sur votre compte. |

```bash
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`)

```json
{
  "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.

```bash
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 :

```json
{
  "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 :

```json
{
  "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é :

| `billing_mode` | Qui paie | Signification des chiffres |
|---|---|---|
| `credits` | Votre compte <span data-t="appName">Your AI Connector</span> | `totalTemplateCost` et les chiffres par pays sont des crédits. |
| `twilio_direct` | Votre propre compte Twilio | `estimatedCostUsd` est ce que Twilio vous facturera. |
| `meta_waba_direct` | Votre propre compte WhatsApp Business, facturé par Meta | Chaque chiffre de crédit est renvoyé sous forme de `null` — délibérément, afin de ne jamais être confondu avec « gratuit ». Les décomptes par pays et par contact restent exacts. |

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**

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

**JavaScript**

```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**

```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`)

```json
{ "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 :

| Problème | Que corriger |
|---|---|
| Pas d'audience | Définissez `list_id` (ou joignez des contacts) avant de lancer. |
| Pas de message d'ouverture | Définissez le message d'ouverture — voir [Le message d'ouverture](#the-opening-message). |
| Pièce jointe sur SMS | Les SMS ne peuvent pas contenir d'image ou de vidéo. Supprimez la pièce jointe ou déplacez la diffusion vers WhatsApp. |
| La pièce jointe ne correspond pas au modèle approuvé | Sur WhatsApp, le média se trouve à l'intérieur du modèle approuvé, donc changer la pièce jointe après coup signifie soumettre à nouveau le modèle. |
| Modèle rejeté | Réécrivez le message et soumettez-le à nouveau. |
| Modèle jamais soumis | Soumettez-le (ou sélectionnez-en un approuvé) d'abord. |
| Modèle approuvé mais absent de votre compte WhatsApp | Généralement un modèle approuvé avant que le numéro ne soit connecté. Soumettez-le à nouveau. |
| Aucun expéditeur connecté pour le canal | Connectez le canal d'abord — voir [Canaux](channels.md). |
| Canal de réponse uniquement | TikTok et Skool ne permettent pas à une entreprise d'initier une conversation, ils ne peuvent donc pas être utilisés pour la diffusion. |
| Déjà armé | La diffusion a déjà un envoi programmé. Mettez-la en pause avant de lancer à nouveau. |
| En attente d'approbation | Elle s'enverra automatiquement lorsque le modèle sera approuvé. |
| Compte WhatsApp Business bloqué par Meta | Meta a arrêté les conversations initiées par l'entreprise sur votre propre compte WhatsApp Business — généralement un problème de méthode de paiement. Corrigez-le dans le Business Manager de Meta. |
| Démarré à partir d'une campagne classique | Lancez-la depuis l'éditeur de campagne à la place. Voir [campagnes classiques dans Diffusions](#broadcasts-that-mirror-a-classic-campaign). |

---

## 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.

```bash
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` :

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

**Réponse** (`200`)

```json
{ "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](#pause-and-resume) 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.

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

**Réponse** (`200`)

```json
{ "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.

| Champ | Requis | Description |
|---|---|---|
| `to_channel` | Non | Créer la copie sur un canal différent. C'est ainsi que vous envoyez la même chose sur deux canaux — une diffusion n'en a jamais qu'un seul. |

```bash
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`)

```json
{ "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}`

```bash
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 :

| Statut | Signification |
|---|---|
| `400` | Quelque chose concernant la requête ou l'état de la diffusion est incorrect — un champ manquant, une pièce jointe invalide, ou un lancement/pause/reprise/suppression qui n'est pas autorisé dans le statut actuel de la diffusion. Le message `error` indique la raison. |
| `401` | Clé API manquante ou invalide. |
| `403` | Votre forfait n'inclut pas l'accès à l'API. |
| `404` | Aucune diffusion de ce type sur votre compte (ou, lors de la sélection d'un modèle, aucun modèle de ce type). |
| `429` | Limite de débit atteinte. Patientez et réessayez. |
| `500` | Quelque chose a mal tourné de notre côté. Réessayez après une courte attente. |

---

## Étapes suivantes

- [Guide des diffusions](../broadcasts/broadcasts.md) — le produit derrière ces points de terminaison, y compris le rythme et le comportement de sécurité
- [API Contacts](contacts.md) — construisez la liste vers laquelle une diffusion est envoyée
- [API Modèles](templates.md) — gérez les modèles WhatsApp approuvés que vous pouvez sélectionner
- [API Webhooks](webhooks.md) — abonnez-vous à `Broadcast Started` et `Broadcast Completed` au lieu d'interroger