# Démarrage rapide

> Crée une clé API, vérifie-la, liste tes leads, importe des contacts et crée un webhook : ta première intégration WhatSetter en cinq minutes.

Source: https://docs.whatsetter.com/fr/developers/quickstart/

Cinq requêtes, en cURL, JavaScript et Python. À la fin tu as une clé, une liste de contacts et un webhook qui te prévient quand un lead est qualifié.

## Avant de commencer

- Tu es **propriétaire** ou **admin** de ton espace WhatSetter. La page API le dit : **Seuls les propriétaires et admins peuvent gérer les clés API.**
- Tu as `curl`, Node.js 18 ou plus récent, ou Python 3 avec `requests`.
- L'URL de base est `https://app.whatsetter.com/api/v1`.

## 1. Crée une clé API

1. Ouvre **Paramètres**, puis **API & MCP**.
2. Clique sur **Créer une clé**.
3. Renseigne **Nom de la clé** (par exemple `Sync CRM`) et choisis les **Permissions** : **Accès complet**, ou **Personnalisé** pour cocher les scopes un par un.
4. Clique sur **Créer la clé**.
5. Copie la clé. La fenêtre le dit : **Copie ta clé maintenant. Elle ne sera plus jamais affichée.** Puis clique sur **J'ai enregistré ma clé**.

Range-la dans une variable d'environnement, jamais dans ton code :

```bash
export WHATSETTER_API_KEY="ws_live_…"
```

> **Clé perdue ?**
WhatSetter ne stocke qu'une empreinte de la clé. Si tu la perds, clique sur **Révoquer** sur cette clé et crées-en une nouvelle.

## 2. Vérifie la clé

[GET /me](/api-reference/operations/getme/) ne demande aucun scope. Il te dit quel espace et quelles permissions la clé possède.

**cURL**

```bash
curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
console.log(await res.json());
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
print(r.json())
```

```json
{
  "data": {
    "team_id": "6b0c1d2e3f405162738a",
    "key": {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Sync CRM",
      "scopes": ["leads:read", "leads:write", "lists:write", "webhooks:manage"]
    }
  }
}
```

Un `401 invalid_api_key` signifie que la clé est mal copiée ou révoquée. Un `401 missing_api_key` signifie que l'en-tête ne nous est pas parvenu.

## 3. Liste tes leads

[GET /leads](/api-reference/operations/listleads/) demande `leads:read`. Filtre par `status`, `campaign_id`, `phone`, `source` ou `since`, et pagine avec `limit` (1 à 100) et `cursor`.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&limit=10" \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const url = new URL('https://app.whatsetter.com/api/v1/leads');
url.searchParams.set('status', 'qualified');
url.searchParams.set('limit', '10');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
const { data, pagination } = await res.json();
console.log(data.length, pagination.next_cursor);
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads",
    params={"status": "qualified", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
body = r.json()
print(len(body["data"]), body["pagination"]["next_cursor"])
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-18T09:12:41.000Z",
      "campaign_id": "acme-france-1-ab12",
      "source": "list",
      "tags": ["hot"],
      "messages_count": 14,
      "last_message_at": "2026-09-18T09:12:00.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

L'objet lead est raccourci ici. Quand `has_more` vaut `true`, renvoie `next_cursor` dans `cursor` pour obtenir la page suivante.

## 4. Importe une liste de contacts

Deux appels : [POST /lists](/api-reference/operations/createlist/) crée une liste vide, puis [`POST /lists/{id}/leads`](/api-reference/operations/importleads/) y pousse jusqu'à 500 contacts par appel. Les deux demandent `lists:write`. Les numéros sont dédupliqués dans le lot et contre la liste.

**cURL**

```bash
# 1. Créer la liste
curl -X POST https://app.whatsetter.com/api/v1/lists \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sync CRM, leads chauds"}'

# 2. Y pousser des contacts (remplace LIST_ID par l'id de l'étape 1)
curl -X POST https://app.whatsetter.com/api/v1/lists/LIST_ID/leads \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone":"+33612345678","name":"Julien","custom_variables":{"ville":"Lyon"}}]}'
```

**JavaScript**

```js
const headers = {
  Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Créer la liste
const created = await fetch('https://app.whatsetter.com/api/v1/lists', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Sync CRM, leads chauds' }),
});
const { data: list } = await created.json();

// 2. Y pousser des contacts
const imported = await fetch(`https://app.whatsetter.com/api/v1/lists/${list.id}/leads`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    leads: [{ phone: '+33612345678', name: 'Julien', custom_variables: { ville: 'Lyon' } }],
  }),
});
console.log(await imported.json());
```

**Python**

```python
import os, requests

headers = {"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"}
base = "https://app.whatsetter.com/api/v1"

# 1. Créer la liste
lst = requests.post(f"{base}/lists", headers=headers,
                    json={"name": "Sync CRM, leads chauds"}).json()["data"]

# 2. Y pousser des contacts
r = requests.post(
    f"{base}/lists/{lst['id']}/leads",
    headers=headers,
    json={"leads": [{"phone": "+33612345678", "name": "Julien",
                     "custom_variables": {"ville": "Lyon"}}]},
)
print(r.json())
```

```json
{
  "data": {
    "imported": 1,
    "duplicates_in_list": 0,
    "rejected": [],
    "lead_ids": ["66f1a2b3c4d5e6f7a8b9c0d2"]
  }
}
```

> **Importer n'envoie encore aucun message**
Une liste est un réservoir de contacts. Le premier message part quand la liste est rattachée à une campagne, au rythme du [moteur anti-ban](/fr/dashboard/anti-ban/). Pour ajouter un seul lead opt-in et lui écrire tout de suite, utilise plutôt [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/).

## 5. Crée un webhook

[POST /webhooks](/api-reference/operations/createwebhook/) demande `webhooks:manage`. L'endpoint doit être en HTTPS.

**cURL**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ton-serveur.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"]}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://ton-serveur.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… affiché une seule fois, stocke-le maintenant
```

**Python**

```python
import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
    json={"url": "https://ton-serveur.com/webhooks/whatsetter",
          "events": ["contact.qualified", "contact.not_qualified"]},
)
print(r.json()["data"]["secret"])  # whsec_… affiché une seule fois, stocke-le maintenant
```

```json
{
  "data": {
    "id": "66f1c0ffee00000000000abc",
    "url": "https://ton-serveur.com/webhooks/whatsetter",
    "events": ["contact.qualified", "contact.not_qualified"],
    "active": true,
    "description": null,
    "secret_prefix": "whsec_3f9a",
    "secret": "whsec_3f9a…",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-19T10:00:00.000Z"
  }
}
```

Le `secret` n'apparaît que dans cette réponse. Stocke-le : tu en as besoin pour [vérifier la signature](/fr/developers/webhooks/) de chaque livraison. Envoie-toi ensuite un événement de test signé avec [`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/).

## La suite

- [Authentification et permissions](/fr/developers/authentication/) : scopes, limites de débit, rotation des clés.
- [Erreurs, limites et idempotence](/fr/developers/errors/) : chaque `code`, et comment réessayer sans risque.
- [Les guides par ressource](/fr/developers/) : leads, campagnes, messages, groupes, contacts bloqués, liens.
- [Serveur MCP](/fr/developers/mcp/) : donne la même clé à Claude, Cursor ou ChatGPT.
- [Utiliser ces docs avec des assistants IA](/fr/developers/ai-assistants/) : laisse un assistant construire l'intégration pour toi.
