Skip to content
Dashboard

Change a prompt

PUT
/campaigns/{id}/prompts/{type}
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 with 409 version_conflict if 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 with 409 draft_pending: compare the draft with the text in service (GET …/versions/{versionId}/compare), then either publish it (restore) or send the write again with ignore_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.

id
required
string
type
required

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

string
Allowed values: conversation first_message follow_up_cold_1 follow_up_cold_2 follow_up_abandoned_1 follow_up_abandoned_2 group_reply group_dm
Media typeapplication/json
object
body
required

The full text. Up to 40000 characters for conversation and group_reply, 25000 for first_message and group_dm, 15000 for a follow-up.

string
>= 1 characters
variant

The variant to change, while an A/B test runs. Versioned prompts only.

string
Allowed values: A B C D
if_version

The live version number you read (0 when the live text has no version). Versioned prompts only.

integer
ignore_draft

Publish although a draft waits on this variant. The draft stays in the history, unpublished. Versioned prompts only.

boolean
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
}

The prompt as it is now

Media typeapplication/json
object
data
object
changed

false when the text sent is already the live one: nothing was written.

boolean
type

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

string
Allowed values: conversation first_message follow_up_cold_1 follow_up_cold_2 follow_up_abandoned_1 follow_up_abandoned_2 group_reply group_dm
variant

Versioned prompts only.

string
Allowed values: A B C D
version

Versioned prompts only. The version now live.

integer | null
version_id

Versioned prompts only.

string | null
previous_version

Versioned prompts only. The version this write replaced. null only when the agent had no text.

integer | null
previous_version_id

Versioned prompts only. The id of that version: pass it to restore to undo this write.

string | null
previous_body

Follow-ups and group texts only. The text this write replaced.

string | null
unknown_tokens

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.

Array<string>
prompt
One of:

The conversation or first_message prompt.

object
type
string
Allowed values: conversation first_message
versioned
boolean
ab_test

true while two variants or more share the traffic.

boolean
live

What the agent runs on now. One entry, or one per variant while an A/B test runs.

Array<object>
object
variant
string
Allowed values: A B C D
name

The name a person gave the variant in the dashboard, if any.

string | null
version

null when the text in service is in no version: the agent’s own copy, kept outside the history.

integer | null
version_id
string | null
traffic_share

Share of new conversations this variant gets (1 when it is alone).

number
created_at
string | null format: date-time
body

The text, with its {{tokens}}.

string
rendered_body

Only with rendered=true. The text with variables resolved and the agent’s style inlined.

string
characters
integer
unpublished_drafts

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.

Array<object>
object
variant
string
Allowed values: A B C D
version
integer
version_id
string
created_at
string | null format: date-time
max_characters
integer
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

Media typeapplication/json
object
error
object
code
string
message
string
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)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
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).

Media typeapplication/json
object
error
object
code
string
message
string
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

Media typeapplication/json
object
error
object
code
string
message
string
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."
}
}