Guides par ressource
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.
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
Section intitulée « Endpoints »| Méthode | Chemin | Scope |
|---|---|---|
| GET | /campaigns/{id}/prompts |
prompts:read |
| GET | /campaigns/{id}/prompts/{type} |
prompts:read |
| PUT | /campaigns/{id}/prompts/{type} |
prompts:write |
| GET | /campaigns/{id}/prompts/{type}/versions |
prompts:read |
| GET | /campaigns/{id}/prompts/{type}/versions/{versionId} |
prompts:read |
| GET | /campaigns/{id}/prompts/{type}/versions/{versionId}/compare |
prompts:read |
| POST | /campaigns/{id}/prompts/{type}/versions/{versionId}/restore |
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
Section intitulée « 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 "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \ -H "Authorization: Bearer ws_live_…"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');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"){ "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. |
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. |
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
Section intitulée « 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_draftstant 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
variantdans 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
Section intitulée « 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 -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 }'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);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"]){ "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. |
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_idla désigne, et la modification s’annule comme une autre.
Quand un brouillon attend
Section intitulée « 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é.
{ "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 :
- Voir ce qu’il change.
GET …/versions/{versionId}/compareavec l’id du brouillon le compare au texte en service. - 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
Section intitulée « 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.
{ "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
Section intitulée « 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.
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions?limit=10" \ -H "Authorization: Bearer ws_live_…"{ "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é.
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
Section intitulée « 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.
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e61f7700093d5b1c02/compare?against=68e60d3100212c0a9b41" \ -H "Authorization: Bearer ws_live_…"{ "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_iden ligne à l’ancienne.
Trouver pourquoi un agent a dit quelque chose
Section intitulée « Trouver pourquoi un agent a dit quelque chose »Trois lectures répondent à la question « pourquoi mon agent a dit ça » :
- L’échange.
GET /conversations/{leadId}/messagesdonne chaque message avec sontype. UnLEAD_WELCOMEa été écrit à partir defirst_message, unAI_RESPONSEà partir deconversation, unFOLLOWUPà partir d’une relance. UnMANUAL_RESPONSEa été écrit par une personne. - Le prompt.
GET /campaigns/{id}/promptspour lecampaign_iddu 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. - Les connaissances. Pour une réponse,
GET /knowledge-bases/{id}/searchavec le message du prospect renvoie les passages que l’agent a reçus. Vois Bases de connaissances.
Avec le serveur MCP, un assistant fait ces trois lectures pour toi et cite la phrase qui explique la réponse.
Les erreurs que tu rencontreras
Section intitulée « 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. |