# Campagnes

> Lister tes campagnes, les mettre en pause et les reprendre depuis tes outils, et pousser des leads opt-in qui reçoivent un premier message personnalisé.

Source: https://docs.whatsetter.com/fr/developers/guides/campaigns/

Une campagne, c'est ce que le dashboard appelle un agent : un agent IA, son numéro WhatsApp et ses contacts. L'API te donne l'annuaire (ids, statut, état de connexion), l'interrupteur pause et reprise, et la porte pour les leads opt-in.

## Endpoints

| Méthode | Chemin | Scope |
|---|---|---|
| GET | [`/campaigns`](/api-reference/operations/listcampaigns/) | `campaigns:read` |
| POST | [`/campaigns/{id}/pause`](/api-reference/operations/pausecampaign/) | `campaigns:write` |
| POST | [`/campaigns/{id}/resume`](/api-reference/operations/resumecampaign/) | `campaigns:write` |
| POST | [`/campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/) | `messages:send` |

## Lister les campagnes

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/campaigns" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/campaigns', {
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: campaigns } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/campaigns",
    headers={"Authorization": "Bearer ws_live_…"},
)
campaigns = r.json()["data"]
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0c1",
      "campaign_id": "acme-france-1-ab12",
      "name": "Acme France",
      "agent_name": "Alex",
      "status": "active",
      "purpose": "setter",
      "whatsapp_connected": true,
      "knowledge_base_id": "68c1f1c4001a09be5d10",
      "created_at": "2026-08-01T09:00:00.000Z"
    }
  ]
}
```

| Champ | Signification |
|---|---|
| `id` | L'id du document campagne. Accepté dans tous les chemins `/campaigns/{id}/...`. |
| `campaign_id` | Le slug que les leads, conversations et rendez-vous portent dans leur propre `campaign_id`. Accepté aussi dans les chemins et les filtres. |
| `name` | Le nom d'affichage de l'agent. |
| `agent_name` | Le prénom avec lequel l'agent signe, celui par lequel on l'appelle. |
| `status` | `active`, `draft`, `paused`, `archived`, ou `unknown` pour une valeur interne. |
| `purpose` | `setter` (conversations 1-à-1) ou `group` (groupes WhatsApp). |
| `whatsapp_connected` | `true` quand le numéro de la campagne peut envoyer maintenant. |
| `knowledge_base_id` | La base de connaissances dont l'agent se sert, ou `null`. Vois [Bases de connaissances](/fr/developers/guides/knowledge/). |

La liste contient jusqu'à 100 campagnes, les plus récentes d'abord. Pas de curseur.

## Pause et reprise

Mettre en pause arrête les réponses de l'IA et les envois, comme l'interrupteur du dashboard. Reprendre les réactive.

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/pause" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/pause', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…' },
});
const { data: campaign } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/pause",
    headers={"Authorization": "Bearer ws_live_…"},
)
campaign = r.json()["data"]
```

La réponse est l'objet campagne avec son nouveau `status`. Il n'existe que deux transitions :

| Appel | Autorisé depuis | Résultat | Sinon |
|---|---|---|---|
| `POST /campaigns/{id}/pause` | `active` | `paused` | `409 invalid_state` |
| `POST /campaigns/{id}/resume` | `paused` | `active` | `409 invalid_state` |

Une campagne `draft` doit être activée depuis le dashboard. Une campagne `archived` ne peut pas être reprise.

La reprise dépend de la limite de campagnes actives de ton plan : Free et Starter 1, Business 3, Scale 10, plus les agents supplémentaires ajoutés à ton plan. Quand la limite est atteinte, la reprise répond `402 plan_limit_reached` : mets une autre campagne en pause ou change de plan.

## Pousser un lead opt-in

Quand quelqu'un s'inscrit sur ton funnel ou ton CRM, pousse-le vers la campagne. WhatSetter déroule le même pipeline que le webhook de page de vente de la campagne : validation du téléphone et vérification WhatsApp, déduplication contre les contacts déjà contactés, quota quotidien de premiers contacts, puis un premier message écrit par l'IA à partir du template de la campagne, du nom du lead et de chaque clé de `additional_data`.

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/leads" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+33612345678",
    "name": "Julien",
    "email": "julien@example.com",
    "source_url": "crm:hubspot",
    "external_reference": "4471",
    "additional_data": { "offre": "Pack Pro", "ville": "Lyon", "budget": "500-1000" }
  }'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/leads', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '+33612345678',
    name: 'Julien',
    email: 'julien@example.com',
    source_url: 'crm:hubspot',
    external_reference: '4471',
    additional_data: { offre: 'Pack Pro', ville: 'Lyon', budget: '500-1000' },
  }),
});
const { data } = await res.json(); // 202
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/leads",
    headers={"Authorization": "Bearer ws_live_…"},
    json={
        "phone": "+33612345678",
        "name": "Julien",
        "email": "julien@example.com",
        "source_url": "crm:hubspot",
        "external_reference": "4471",
        "additional_data": {"offre": "Pack Pro", "ville": "Lyon", "budget": "500-1000"},
    },
)
data = r.json()["data"]  # 202
```

```json
{
  "data": {
    "status": "accepted",
    "campaign_id": "acme-france-1-ab12",
    "phone": "+33612345678",
    "external_reference": "4471",
    "note": "Queued into the first-contact pipeline: deduplication, daily first-contact quota and anti-ban pacing apply. The lead is created later, so no lead id exists yet…"
  }
}
```

| Champ | Règles |
|---|---|
| `phone` | Obligatoire. Format international, 6 à 15 chiffres. Renvoyé avec un `+`. |
| `name`, `email` | Optionnels, coupés à 255 caractères. |
| `source_url` | Optionnel, 255 caractères maximum. D'où vient le lead. Vaut `api` par défaut. |
| `external_reference` | Optionnel, 255 caractères maximum. L'identifiant de ta propre fiche, stocké tel quel et renvoyé sur chaque lead et chaque webhook. |
| `additional_data` | Objet optionnel, 30 clés et 2000 caractères maximum une fois sérialisé. Sert à personnaliser le premier message, jamais stocké, jamais renvoyé. Les clés nommées comme les champs ci-dessus (`phone`, `name`, `email`, `source_url`, `external_reference`) sont ignorées. |

### C'est asynchrone

L'endpoint répond `202` dès que le lead est accepté. La ligne lead est créée plus tard, après déduplication et cadencement, donc il n'y a pas encore d'id de lead. Pour suivre :

- retrouve le lead avec `GET /leads?external_reference=4471` (ou `?phone=+33612345678`) ;
- ou abonne-toi aux [webhooks](/fr/developers/webhooks/) : `contact.external_reference` porte ton identifiant.

Un contact déjà contacté par la campagne est dédupliqué en silence : pas de second premier message, et le `202` est identique. Les leads au-delà du quota sont mis en file pour la fenêtre suivante, jamais perdus.

> **Cet appel envoie un message WhatsApp**
Ne pousse que des personnes qui ont demandé à être contactées. Pour des listes froides, importe plutôt via les [listes](/fr/developers/guides/lists-import/), pour que la campagne cadence et vérifie les numéros.

## Quotas

Deux budgets protègent le numéro, et l'API ne peut contourner ni l'un ni l'autre :

- **Premiers contacts quotidiens** par campagne : les leads opt-in au-delà attendent le lendemain.
- **Messages quotidiens** par numéro WhatsApp : partagés avec `POST /messages`, voir [Messages](/fr/developers/guides/messages/) pour les en-têtes `X-Quota-*`.

En plus, les requêtes sont limitées par espace de travail et par minute selon le plan (`429 rate_limited` avec `Retry-After`).

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 402 | `plan_limit_reached` | Reprise refusée : la limite de campagnes actives du plan est atteinte. |
| 403 | `insufficient_scope` | La clé n'a pas `campaigns:read`, `campaigns:write` ou `messages:send`. |
| 404 | `not_found` | Campagne inconnue, ou campagne d'un autre espace de travail. |
| 409 | `invalid_state` | Pause sur une campagne non active, reprise sur une campagne non en pause, lead poussé vers une campagne non active, ou campagne jamais ouverte dans le dashboard. |
| 422 | `validation_error` | Téléphone invalide, `additional_data` qui n'est pas un objet ou trop gros, `external_reference` trop long. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |
| 502 | `upstream_error` | Le pipeline de premier message était injoignable. Réessaie dans un instant. |

## Voir aussi

- [Listes et import](/fr/developers/guides/lists-import/)
- [Leads](/fr/developers/guides/leads/)
- [Les agents dans le dashboard](/fr/dashboard/agents/)
- [Protection anti-ban](/fr/dashboard/anti-ban/)
