Prompts
Change a prompt
const url = 'https://app.whatsetter.com/api/v1/campaigns/example/prompts/conversation';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"body":"## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.\n\n## Rules\nNever give a price before the lead says what they need.","if_version":7}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://app.whatsetter.com/api/v1/campaigns/example/prompts/conversation \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "body": "## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.\n\n## Rules\nNever give a price before the lead says what they need.", "if_version": 7 }'Replaces a text of the agent. The change is live on the agent’s next message, on an active agent included: this is the same as Publish in the dashboard. Send the full text, not a diff.
For conversation and first_message, the change is a new version:
the previous one stays in the history and can be put back with
POST …/versions/{versionId}/restore, which takes the
previous_version_id of the answer. Sending the text that is already
live changes nothing (changed: false). When the text in service was
in no version, it is filed in the history first (a version marked
snapshot), so this change can be undone like any other.
if_version: the live version you read. The write is refused with409 version_conflictif someone changed the text since.variant: only while an A/B test runs, to say which variant you change. Its share of the traffic is kept. Starting, stopping or rebalancing a test stays in the dashboard.ignore_draft: a draft saved in the dashboard and never published is the text its author sees in the editor. While one waits (unpublished_drafts), a write is refused with409 draft_pending: compare the draft with the text in service (GET …/versions/{versionId}/compare), then either publish it (restore) or send the write again withignore_draft: true. The draft then stays in the history, unpublished.
Follow-ups and group texts keep no history: the answer carries
previous_body, the text this write replaced.
{{tokens}} are kept as written and resolved for each message. The
answer lists unknown_tokens: the tokens of your text that match no
variable of the agent. They are not resolved, so the agent would read
them as they stand: correct them.
Requires scope prompts:write.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A text the agent runs on. A private-message agent has conversation
(how it replies), first_message and the four follow-ups: cold goes
to a lead who never replied, abandoned to a lead who stopped
replying, _1 then _2. A group agent has group_reply (in the
group) and group_dm (in private).
Request Bodyrequired
Section titled “Request Bodyrequired”object
The full text. Up to 40000 characters for conversation and group_reply, 25000 for first_message and group_dm, 15000 for a follow-up.
The variant to change, while an A/B test runs. Versioned prompts only.
The live version number you read (0 when the live text has no version). Versioned prompts only.
Publish although a draft waits on this variant. The draft stays in the history, unpublished. Versioned prompts only.
Example
{ "body": "## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.\n\n## Rules\nNever give a price before the lead says what they need.", "if_version": 7}Responses
Section titled “Responses”The prompt as it is now
object
object
false when the text sent is already the live one: nothing was written.
A text the agent runs on. A private-message agent has conversation
(how it replies), first_message and the four follow-ups: cold goes
to a lead who never replied, abandoned to a lead who stopped
replying, _1 then _2. A group agent has group_reply (in the
group) and group_dm (in private).
Versioned prompts only.
Versioned prompts only. The version now live.
Versioned prompts only.
Versioned prompts only. The version this write replaced. null only when the agent had no text.
Versioned prompts only. The id of that version: pass it to restore to undo this write.
Follow-ups and group texts only. The text this write replaced.
Tokens of the text that match no variable of the agent (promo_code for {{promo_code}}). The agent would read them as they stand. Empty when every token resolves.
The conversation or first_message prompt.
object
true while two variants or more share the traffic.
What the agent runs on now. One entry, or one per variant while an A/B test runs.
object
The name a person gave the variant in the dashboard, if any.
null when the text in service is in no version: the agent’s own copy, kept outside the history.
Share of new conversations this variant gets (1 when it is alone).
The text, with its {{tokens}}.
Only with rendered=true. The text with variables resolved and the agent’s style inlined.
Saved in the editor and never published. Each one is the newest text of its variant and differs from what the agent reads. A write on that variant is refused until the draft is published or ignore_draft is sent.
object
A follow-up or a group text. One text, no versions.
object
null when the agent has no text of its own and uses the built-in one.
Follow-ups only. Whether this follow-up is sent.
Follow-ups only. Hours of silence before it is sent.
Example
{ "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", "name": null, "version": 8, "version_id": "68e61f7700093d5b1c02", "traffic_share": 1, "created_at": "2026-10-08T14:02:11.000+00:00", "body": "## Identity\nYou are {{agent_name}} from {{company_name}}.\n\n## Goal\nQualify the lead, then send {{goal_link}}.\n\n## Rules\nNever give a price before the lead says what they need.", "characters": 175 } ], "unpublished_drafts": [], "max_characters": 40000 } }}Missing, unknown or revoked API key
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}The key lacks the required scope (insufficient_scope), the plan does not have this part of the API (not_in_plan), or Instagram is not enabled on the workspace (instagram_not_enabled, Instagram routes)
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Resource not found in this workspace
object
object
Examplegenerated
{ "error": { "code": "example", "message": "example" }}version_conflict (the live version is not if_version),
draft_pending (a draft saved in the dashboard waits: see
ignore_draft), variant_required (an A/B test runs, name the
variant), variant_not_live (that variant is out of the rotation)
or invalid_state (this agent has no text of that type).
object
object
Example
{ "error": { "code": "version_conflict", "message": "The live version is 8, not 7: the text changed since you read it. Read it again, then publish." }}Missing, empty or too long body, or a variant the agent does not have
object
object
Example
{ "error": { "code": "validation_error", "message": "\"body\" is empty. An agent cannot run on an empty text: send the full text you want it to follow." }}