Aller au contenu
Dashboard

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.

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.

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

Terminal window
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \
-H "Authorization: Bearer ws_live_…"
{
"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é.

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.

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.

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.

Terminal window
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
}'
{
"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_id la désigne, et la modification s’annule comme une autre.

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 :

  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.

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.

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.

Terminal window
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é.

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

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.

Terminal window
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_id en ligne à l’ancienne.

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

Avec le serveur MCP, un assistant fait ces trois lectures pour toi et cite la phrase qui explique la réponse.

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.