# Change a prompt

`PUT https://app.whatsetter.com/api/v1/campaigns/{id}/prompts/{type}`

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

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `type` | path | conversation \| first_message \| follow_up_cold_1 \| follow_up_cold_2 \| follow_up_abandoned_1 \| follow_up_abandoned_2 \| group_reply \| group_dm | yes |  |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `body` | string | yes | The full text. Up to 40000 characters for `conversation` and `group_reply`, 25000 for `first_message` and `group_dm`, 15000 for a follow-up. |
| `variant` | A \| B \| C \| D | no | The variant to change, while an A/B test runs. Versioned prompts only. |
| `if_version` | integer | no | The live version number you read (`0` when the live text has no version). Versioned prompts only. |
| `ignore_draft` | boolean | no | Publish although a draft waits on this variant. The draft stays in the history, unpublished. Versioned prompts only. |

```json
{
  "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
}
```

## Example request

```bash
curl --request PUT \
  --url 'https://app.whatsetter.com/api/v1/campaigns/{id}/prompts/{type}' \
  --header 'Authorization: Bearer ws_live_…'
  --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}'
```

## Responses

### 200: The prompt as it is now

```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",
          "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
    }
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 403: 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)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: `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).


```json
{
  "error": {
    "code": "version_conflict",
    "message": "The live version is 8, not 7: the text changed since you read it. Read it again, then publish."
  }
}
```

### 422: Missing, empty or too long `body`, or a `variant` the agent does not have

```json
{
  "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."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/updatecampaignprompt/
