# Prompts des agents

> Lire les prompts qui font tourner un agent, trouver pourquoi il a dit quelque chose, modifier un prompt depuis tes outils, comparer deux versions et en restaurer une.

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

Un agent tourne sur quelques textes : sa façon de répondre, son premier message et ses relances. L'API les lit exactement comme l'agent les utilise, les modifie et garde l'historique. Dans l'API, un agent s'appelle une campagne.

## Endpoints

| Méthode | Chemin | Scope |
|---|---|---|
| GET | [`/campaigns/{id}/prompts`](/api-reference/operations/getcampaignprompts/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/getcampaignprompt/) | `prompts:read` |
| PUT | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/updatecampaignprompt/) | `prompts:write` |
| GET | [`/campaigns/{id}/prompts/{type}/versions`](/api-reference/operations/listpromptversions/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}`](/api-reference/operations/getpromptversion/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/compare`](/api-reference/operations/comparepromptversions/) | `prompts:read` |
| POST | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/restore`](/api-reference/operations/restorepromptversion/) | `prompts:write` |

`{id}` est l'`id` de la campagne ou son `campaign_id`, tous deux donnés par `GET /campaigns`. `{type}` est l'un de ceux-ci :

| `type` | Dans le dashboard | Historique |
|---|---|---|
| `conversation` | **Conversation** : la façon dont l'agent répond | Versions |
| `first_message` | **Premier message** | Versions |
| `follow_up_cold_1`, `follow_up_cold_2` | **Relances** d'un prospect qui n'a jamais répondu | Aucun |
| `follow_up_abandoned_1`, `follow_up_abandoned_2` | **Relances** d'un prospect qui a cessé de répondre | Aucun |
| `group_reply`, `group_dm` | Les deux textes d'un agent de groupe | Aucun |

Un agent de messages privés a les six premiers. Un agent de groupe a les deux derniers. Demander à un agent un texte qu'il n'a pas répond `409 invalid_state`.

## Lire ce qui fait tourner un agent

Un seul appel renvoie tous les textes de l'agent, les valeurs de ses variables et la base de connaissances dont il se sert.

**cURL**

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

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data } = await res.json();
const conversation = data.prompts.find((p) => p.type === 'conversation');
```

**Python**

```python
import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts",
    headers={"Authorization": "Bearer ws_live_…"},
)
data = r.json()["data"]
conversation = next(p for p in data["prompts"] if p["type"] == "conversation")
```

```json
{
  "data": {
    "campaign": { "id": "66f1a2b3c4d5e6f7a8b9c0c1", "campaign_id": "acme-france-1-ab12", "name": "Acme France", "agent_name": "Julien", "status": "active", "purpose": "setter" },
    "prompts": [
      {
        "type": "conversation",
        "versioned": true,
        "ab_test": false,
        "live": [
          {
            "variant": "A",
            "name": null,
            "version": 7,
            "version_id": "68e60d3100212c0a9b41",
            "traffic_share": 1,
            "created_at": "2026-10-07T09:18:22.000+00:00",
            "body": "## Identité\nTu es {{agent_name}} de {{company_name}}.\n\n## Objectif\nQualifie le prospect, puis envoie {{goal_link}}.",
            "characters": 115
          }
        ],
        "unpublished_drafts": [],
        "max_characters": 40000
      },
      {
        "type": "follow_up_cold_1",
        "versioned": false,
        "body": "Écris une courte relance à {{prospectName}}, qui n'a pas encore répondu.",
        "uses_default": false,
        "characters": 72,
        "max_characters": 15000,
        "enabled": true,
        "delay_hours": 24
      }
    ],
    "variables": {
      "agent_name": "Julien",
      "company_name": "Acme France",
      "goal_link": "https://cal.com/acme/demo",
      "language": "français"
    },
    "knowledge_base_id": "68c1f1c4001a09be5d10"
  }
}
```

| Champ | Signification |
|---|---|
| `prompts[].live` | Ce que l'agent lit en ce moment. Une entrée, ou une par variante pendant un test A/B. |
| `live[].version` | Le numéro de version. `null` seulement quand le texte en service n'est dans aucune version : il est alors en ligne à lui seul. |
| `live[].traffic_share` | La part des nouvelles conversations que reçoit cette variante. `1` quand elle est seule. |
| `unpublished_drafts` | Les textes enregistrés dans le dashboard et jamais publiés, que l'agent ne lit pas. Vois [Quand un brouillon attend](#quand-un-brouillon-attend). |
| `enabled`, `delay_hours` | Relances seulement : si elle est envoyée, et après combien d'heures de silence. |
| `uses_default` | `true` quand l'agent n'a pas de texte à lui à cet endroit et utilise celui fourni. `body` vaut alors `null`. |
| `variables` | La valeur derrière chaque jeton des textes, tes propres variables comprises. |
| `knowledge_base_id` | La base dont l'agent se sert pour répondre. Vois [Bases de connaissances](/fr/developers/guides/knowledge/). |

Les jetons s'écrivent entre doubles accolades, comme `{{agent_name}}`. Ils sont remplacés à chaque message. `{{first_name}}` et `{{lead:<colonne>}}` sont remplis pour chaque prospect, ils ne sont donc pas dans `variables`. Ajoute `?rendered=true` pour recevoir aussi `rendered_body` : chaque texte en ligne avec ses variables remplacées et le style de l'agent inséré.

## Ce qui est en ligne

**En ligne** veut dire ce que l'agent lit à son prochain message, avec la même règle que l'agent lui-même :

- Un texte publié avec **Publier** dans le dashboard, ou écrit par cette API, est en ligne.
- Un texte enregistré sans être publié est un brouillon. L'agent ne le lit pas. Il est listé dans `unpublished_drafts` tant qu'il est le texte le plus récent de sa variante et qu'il diffère de ce que l'agent lit.
- Pendant un test A/B, plusieurs variantes sont en ligne en même temps. Chaque message d'une conversation dit quelle variante l'a écrit : vois `variant` dans [Conversations](/fr/developers/guides/conversations/).

Le texte en ligne est une version numérotée. Un cas est différent : un texte en service qui n'est dans aucune version. Il est alors en ligne à lui seul, avec `version` et `version_id` à `null`. La première modification faite par l'API le range dans l'historique avant de le remplacer.

## Modifier un prompt

Envoie le texte entier, pas une différence. Lis-le d'abord, change ce qu'il faut, garde les jetons et les titres de section tels quels.

**cURL**

```bash
curl -X PUT "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "## Identité\nTu es {{agent_name}} de {{company_name}}.\n\n## Objectif\nQualifie le prospect, puis envoie {{goal_link}}.\n\n## Règles\nNe donne jamais de prix avant que le prospect ait dit ce qu’il cherche.",
    "if_version": 7
  }'
```

**JavaScript**

```js
const res = await fetch(
  'https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation',
  {
    method: 'PUT',
    headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
    body: JSON.stringify({ body: newText, if_version: 7 }),
  },
);
const { data } = await res.json();
console.log(data.changed, data.version, data.previous_version_id);
```

**Python**

```python
import requests

r = requests.put(
    "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"body": new_text, "if_version": 7},
)
data = r.json()["data"]
print(data["changed"], data["version"], data["previous_version_id"])
```

```json
{
  "data": {
    "changed": true,
    "type": "conversation",
    "variant": "A",
    "version": 8,
    "version_id": "68e61f7700093d5b1c02",
    "previous_version": 7,
    "previous_version_id": "68e60d3100212c0a9b41",
    "unknown_tokens": [],
    "prompt": { "type": "conversation", "versioned": true, "ab_test": false, "live": [ { "variant": "A", "version": 8, "…": "…" } ], "unpublished_drafts": [], "max_characters": 40000 }
  }
}
```

| Champ | Règles |
|---|---|
| `body` | Obligatoire. Le texte entier. Jusqu'à 40000 caractères pour `conversation` et `group_reply`, 25000 pour `first_message` et `group_dm`, 15000 pour une relance. |
| `if_version` | Facultatif. La version en ligne que tu as lue (`0` quand le texte en ligne n'a pas de version). Si le texte a changé depuis, l'appel répond `409 version_conflict` et n'écrit rien. |
| `variant` | Seulement pendant un test A/B : `A`, `B`, `C` ou `D`, la variante que tu modifies. Sa part du trafic est gardée. |
| `ignore_draft` | Facultatif. `true` pour publier alors qu'un brouillon attend sur ce texte. Vois [Quand un brouillon attend](#quand-un-brouillon-attend). |

> **La modification est en ligne tout de suite**
Un prompt écrit par l'API sert dès le prochain message de l'agent, même sur un agent actif. C'est la même chose que **Publier** dans le dashboard. Garde le `previous_version_id` de la réponse : c'est ton chemin de retour.

Quatre choses à savoir en plus :

- Envoyer le texte déjà en ligne n'écrit rien et répond `changed: false`.
- La réponse liste `unknown_tokens` : les jetons de ton texte qui ne correspondent à aucune variable de l'agent. Ils ne sont pas remplacés, l'agent les lirait donc tels quels. Corrige-les et renvoie le texte.
- Lancer, arrêter ou rééquilibrer un test A/B reste dans le dashboard, tout comme les variables elles-mêmes.
- Quand le texte en service n'était dans aucune version, il est d'abord rangé dans l'historique, comme une version marquée `snapshot`. `previous_version_id` la désigne, et la modification s'annule comme une autre.

## Quand un brouillon attend

Un brouillon est un texte enregistré dans le dashboard et jamais publié. Son auteur le voit dans l'éditeur, et l'agent ne le lit pas. Tant qu'un brouillon attend sur un texte, une écriture sur ce texte répond `409 draft_pending` et n'écrit rien : publier un autre texte laisserait le brouillon de côté sans que personne l'ait décidé.

```json
{
  "error": {
    "code": "draft_pending",
    "message": "Version 9 of this text (id 68e7a1c2000f3b7a2d15) was saved in the dashboard on 2026-10-09 and never published: the agent does not read it, and it differs from the text in service. Publishing now would leave that draft aside. Compare it with the text in service (GET …/versions/{id}/compare), then either publish it (POST …/versions/{id}/restore) or send this request again with \"ignore_draft\": true: the draft then stays in the history, unpublished."
  }
}
```

Le brouillon est nommé dans `unpublished_drafts`, avec son `version_id`. Deux appels règlent la question :

1. **Voir ce qu'il change.** `GET …/versions/{versionId}/compare` avec l'id du brouillon le compare au texte en service.
2. **Choisir.** Pour publier le brouillon, restaure-le : `POST …/versions/{versionId}/restore`. Pour garder le texte en service comme base, renvoie ton écriture avec `"ignore_draft": true`.

Un brouillon laissé de côté n'est pas supprimé. Il reste dans l'historique avec le statut `draft`, et il quitte `unpublished_drafts` puisqu'une version plus récente est en ligne.

## Relances et agents de groupe

Ces textes ne gardent pas d'historique. Une écriture remplace le texte, et la réponse porte `previous_body`, le texte remplacé. Garde-le si tu peux vouloir y revenir. `variant` et `if_version` ne s'appliquent pas.

```json
{
  "data": {
    "changed": true,
    "type": "follow_up_cold_1",
    "previous_body": "Écris une courte relance à {{prospectName}}, qui n'a pas encore répondu.",
    "unknown_tokens": [],
    "prompt": { "type": "follow_up_cold_1", "versioned": false, "body": "Pose une seule question simple sur son projet.", "uses_default": false, "characters": 46, "max_characters": 15000, "enabled": true, "delay_hours": 24 }
  }
}
```

Écrire une relance ne l'active pas. `enabled` et `delay_hours` se règlent dans le dashboard, dans **Relances**.

## Historique et restauration

`conversation` et `first_message` gardent chaque version. La liste va de la plus récente à la plus ancienne et porte un aperçu. Une version seule donne son texte entier.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions?limit=10" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "data": [
    { "id": "68e61f7700093d5b1c02", "version": 8, "variant": "A", "name": null, "status": "live", "author": "api", "snapshot": false, "created_at": "2026-10-08T14:02:11.000+00:00", "characters": 198, "preview": "## Identité Tu es {{agent_name}} de {{company_name}}." },
    { "id": "68e60d3100212c0a9b41", "version": 7, "variant": "A", "name": null, "status": "inactive", "author": "dashboard", "snapshot": false, "created_at": "2026-10-07T09:18:22.000+00:00", "characters": 115, "preview": "## Identité Tu es {{agent_name}} de {{company_name}}." }
  ],
  "pagination": { "has_more": false, "next_cursor": "68e60d3100212c0a9b41" }
}
```

| `status` | Signification |
|---|---|
| `live` | Ce que l'agent lit en ce moment. |
| `draft` | Enregistrée dans le dashboard, jamais publiée. |
| `inactive` | Remplacée par une version plus récente, ou sa variante est sortie du test. |

`author` vaut `api` pour une version écrite avec une clé API et `dashboard` pour les autres.

`snapshot` vaut `true` sur une version que l'API a rangée elle-même : le texte qui était en service hors de l'historique, gardé au moment où une modification l'a remplacé. Son `created_at` est la date de cette modification, pas le jour où le texte a été écrit.

`name` est le nom qu'une personne a donné à la variante en publiant. Une date écrite par le dashboard n'est pas un nom : elle revient à `null`, et la date est dans `created_at`.

Pour revenir en arrière, restaure une version : passe le `previous_version_id` d'une écriture pour l'annuler. La version est publiée de nouveau comme une nouvelle version avec le même texte, au caractère près : l'historique reste une ligne droite et la restauration peut elle-même être annulée. Restaurer un brouillon le publie. Restaurer une autre version pendant qu'un brouillon attend répond `409 draft_pending`, sauf si le corps porte `"ignore_draft": true`. Comme une écriture, une restauration accepte `"if_version"`, la version en ligne que tu as lue pour la variante de cette version (la variante compte pour un agent en test A/B) : si ce texte a changé depuis, elle répond `409 version_conflict` et rien n'est remplacé.

```bash
curl -X POST "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e60d3100212c0a9b41/restore" \
  -H "Authorization: Bearer ws_live_…"
```

## Comparer deux versions

`GET …/versions/{versionId}/compare` renvoie ce qu'une version change par rapport à une autre, ligne par ligne. Nomme l'autre dans `against`. Sans `against`, la version est comparée au texte en service.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e61f7700093d5b1c02/compare?against=68e60d3100212c0a9b41" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "data": {
    "version": { "id": "68e61f7700093d5b1c02", "version": 8, "variant": "A", "status": "live", "created_at": "2026-10-08T14:02:11.000+00:00", "characters": 198 },
    "against": { "id": "68e60d3100212c0a9b41", "version": 7, "variant": "A", "status": "inactive", "created_at": "2026-10-07T09:18:22.000+00:00", "characters": 115 },
    "identical": false,
    "lines_added": 3,
    "lines_removed": 0,
    "diff": "@@ -4,2 +4,5 @@\n ## Objectif\n Qualifie le prospect, puis envoie {{goal_link}}.\n+\n+## Règles\n+Ne donne jamais de prix avant que le prospect ait dit ce qu’il cherche."
  }
}
```

| Champ | Signification |
|---|---|
| `version`, `against` | Les deux textes comparés. `id` et `version` valent `null` pour un texte en service qui n'est dans aucune version. |
| `identical` | `true` quand les deux textes sont les mêmes. Les fins de ligne et les espaces en fin de ligne ne sont pas des différences. |
| `lines_added`, `lines_removed` | Les lignes que la version a et que `against` n'a pas, et l'inverse. |
| `diff` | Un diff unifié avec deux lignes de contexte. Une ligne qui commence par `+` est dans la version et pas dans `against`. Une ligne qui commence par `-`, c'est l'inverse. Vide quand `identical` vaut `true`. |

Trois questions auxquelles il répond :

- **Qu'a changé une écriture ?** Compare le nouveau `version_id` à `previous_version_id`.
- **Que changerait un brouillon ?** Compare l'id du brouillon, sans `against`.
- **Qu'est-ce qui a changé depuis une version plus ancienne ?** Compare le `version_id` en ligne à l'ancienne.

## Trouver pourquoi un agent a dit quelque chose

Trois lectures répondent à la question « pourquoi mon agent a dit ça » :

1. **L'échange.** `GET /conversations/{leadId}/messages` donne chaque message avec son `type`. Un `LEAD_WELCOME` a été écrit à partir de `first_message`, un `AI_RESPONSE` à partir de `conversation`, un `FOLLOWUP` à partir d'une relance. Un `MANUAL_RESPONSE` a été écrit par une personne.
2. **Le prompt.** `GET /campaigns/{id}/prompts` pour le `campaign_id` du prospect. Cherche la consigne qui a mené au message. Si le message est plus ancien que la version en ligne, la liste des versions te dit ce qui était en ligne ce jour-là. Pour voir ce qui a changé entre deux versions, vois [Comparer deux versions](#comparer-deux-versions).
3. **Les connaissances.** Pour une réponse, `GET /knowledge-bases/{id}/search` avec le message du prospect renvoie les passages que l'agent a reçus. Vois [Bases de connaissances](/fr/developers/guides/knowledge/).

Avec le [serveur MCP](/fr/developers/mcp/), un assistant fait ces trois lectures pour toi et cite la phrase qui explique la réponse.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clé absente, inconnue ou révoquée. |
| 403 | `insufficient_scope` | Il manque `prompts:read` ou `prompts:write` à la clé. Une clé créée avant l'existence de ces scopes ne les a pas. |
| 404 | `not_found` | Campagne, type ou version inconnus, ou d'un autre espace. |
| 409 | `invalid_state` | L'agent n'a pas de texte de ce type, ce texte ne garde pas d'historique, ou la version à restaurer ne contient aucun texte. |
| 409 | `version_conflict` | `if_version` n'est pas la version en ligne : le texte a changé depuis ta lecture. |
| 409 | `draft_pending` | Un brouillon enregistré dans le dashboard attend sur ce texte, et l'appel ne porte pas `ignore_draft`. |
| 409 | `variant_required` | Un test A/B tourne et l'appel ne nomme pas de variante. |
| 409 | `variant_not_live` | La variante nommée est sortie du test pendant qu'une autre sert. |
| 422 | `validation_error` | `body` absent, vide ou trop long, une `variant` que l'agent n'a pas, un `if_version` invalide, un `ignore_draft` qui n'est pas un booléen. |
| 429 | `rate_limited` | Trop de requêtes cette minute. Respecte `Retry-After`. |

## Voir aussi

- [Bases de connaissances](/fr/developers/guides/knowledge/)
- [Conversations](/fr/developers/guides/conversations/)
- [Le prompt de ton agent dans le dashboard](/fr/dashboard/prompt/)
- [Serveur MCP](/fr/developers/mcp/)
