# Prompts de los agentes

> Leer los prompts con los que trabaja un agente, encontrar por qué dijo algo, cambiar un prompt desde tus herramientas, comparar dos versiones y restaurar una.

Source: https://docs.whatsetter.com/es/developers/guides/prompts/

Un agente trabaja con unos pocos textos: su forma de responder, su primer mensaje y sus seguimientos. La API los lee tal como el agente los usa, los cambia y guarda el historial. En la API, un agente se llama campaña.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/campaigns/{id}/prompts`](/api-reference/operations/getcampaignprompts/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/getcampaignprompt/) | `prompts:read` |
| PUT | [`/campaigns/{id}/prompts/{type}`](/api-reference/operations/updatecampaignprompt/) | `prompts:write` |
| GET | [`/campaigns/{id}/prompts/{type}/versions`](/api-reference/operations/listpromptversions/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}`](/api-reference/operations/getpromptversion/) | `prompts:read` |
| GET | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/compare`](/api-reference/operations/comparepromptversions/) | `prompts:read` |
| POST | [`/campaigns/{id}/prompts/{type}/versions/{versionId}/restore`](/api-reference/operations/restorepromptversion/) | `prompts:write` |

`{id}` es el `id` de la campaña o su `campaign_id`, ambos devueltos por `GET /campaigns`. `{type}` es uno de estos:

| `type` | En el dashboard | Historial |
|---|---|---|
| `conversation` | **Conversación**: cómo responde el agente | Versiones |
| `first_message` | **Primer mensaje** | Versiones |
| `follow_up_cold_1`, `follow_up_cold_2` | **Seguimientos** a un lead que nunca respondió | Ninguno |
| `follow_up_abandoned_1`, `follow_up_abandoned_2` | **Seguimientos** a un lead que dejó de responder | Ninguno |
| `group_reply`, `group_dm` | Los dos textos de un agente de grupo | Ninguno |

Un agente de mensajes privados tiene los seis primeros. Un agente de grupo tiene los dos últimos. Pedir a un agente un texto que no tiene responde `409 invalid_state`.

## Leer con qué trabaja un agente

Una sola llamada devuelve todos los textos del agente, los valores de sus variables y la base de conocimientos de la que responde.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \
  -H "Authorization: Bearer ws_live_…"
```

**JavaScript**

```js
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');
```

**Python**

```python
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")
```

```json
{
  "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": "## Identidad\nEres {{agent_name}} de {{company_name}}.\n\n## Objetivo\nCalifica al lead y luego envía {{goal_link}}.",
            "characters": 112
          }
        ],
        "unpublished_drafts": [],
        "max_characters": 40000
      },
      {
        "type": "follow_up_cold_1",
        "versioned": false,
        "body": "Escribe un seguimiento corto a {{prospectName}}, que aún no ha respondido.",
        "uses_default": false,
        "characters": 74,
        "max_characters": 15000,
        "enabled": true,
        "delay_hours": 24
      }
    ],
    "variables": {
      "agent_name": "Julien",
      "company_name": "Acme France",
      "goal_link": "https://cal.com/acme/demo",
      "language": "español"
    },
    "knowledge_base_id": "68c1f1c4001a09be5d10"
  }
}
```

| Campo | Significado |
|---|---|
| `prompts[].live` | Lo que el agente lee ahora mismo. Una entrada, o una por variante mientras corre un test A/B. |
| `live[].version` | El número de versión. `null` solo cuando el texto en servicio no está en ninguna versión: entonces está en línea por sí solo. |
| `live[].traffic_share` | La parte de las conversaciones nuevas que recibe esta variante. `1` cuando está sola. |
| `unpublished_drafts` | Los textos guardados en el dashboard y nunca publicados, que el agente no lee. Mira [Cuando un borrador espera](#cuando-un-borrador-espera). |
| `enabled`, `delay_hours` | Solo seguimientos: si se envía, y tras cuántas horas de silencio. |
| `uses_default` | `true` cuando el agente no tiene texto propio ahí y usa el incluido. `body` vale entonces `null`. |
| `variables` | El valor detrás de cada marcador de los textos, incluidas tus propias variables. |
| `knowledge_base_id` | La base de la que responde el agente. Mira [Bases de conocimientos](/es/developers/guides/knowledge/). |

Los marcadores se escriben entre dobles llaves, como `{{agent_name}}`. Se resuelven en cada mensaje. `{{first_name}}` y `{{lead:<columna>}}` se rellenan para cada lead, por eso no están en `variables`. Añade `?rendered=true` para recibir también `rendered_body`: cada texto en línea con sus variables resueltas y el estilo del agente insertado.

## Qué está en línea

**En línea** significa lo que el agente lee en su próximo mensaje, con la misma regla que el propio agente:

- Un texto publicado con **Publicar** en el dashboard, o escrito con esta API, está en línea.
- Un texto guardado sin publicar es un borrador. El agente no lo lee. Aparece en `unpublished_drafts` mientras sea el texto más reciente de su variante y difiera de lo que el agente lee.
- Mientras corre un test A/B, varias variantes están en línea a la vez. Cada mensaje de una conversación dice qué variante lo escribió: mira `variant` en [Conversaciones](/es/developers/guides/conversations/).

El texto en línea es una versión numerada. Un caso es distinto: un texto en servicio que no está en ninguna versión. Entonces está en línea por sí solo, con `version` y `version_id` en `null`. El primer cambio hecho con la API lo archiva en el historial antes de reemplazarlo.

## Cambiar un prompt

Envía el texto completo, no una diferencia. Léelo primero, cambia lo necesario, deja los marcadores y los títulos de sección como están.

**cURL**

```bash
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": "## Identidad\nEres {{agent_name}} de {{company_name}}.\n\n## Objetivo\nCalifica al lead y luego envía {{goal_link}}.\n\n## Reglas\nNunca des un precio antes de que el lead diga qué necesita.",
    "if_version": 7
  }'
```

**JavaScript**

```js
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);
```

**Python**

```python
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"])
```

```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", "version": 8, "…": "…" } ], "unpublished_drafts": [], "max_characters": 40000 }
  }
}
```

| Campo | Reglas |
|---|---|
| `body` | Obligatorio. El texto completo. Hasta 40000 caracteres para `conversation` y `group_reply`, 25000 para `first_message` y `group_dm`, 15000 para un seguimiento. |
| `if_version` | Opcional. La versión en línea que leíste (`0` cuando el texto en línea no tiene versión). Si el texto cambió desde entonces, la llamada responde `409 version_conflict` y no escribe nada. |
| `variant` | Solo mientras corre un test A/B: `A`, `B`, `C` o `D`, la variante que cambias. Su parte del tráfico se conserva. |
| `ignore_draft` | Opcional. `true` para publicar aunque un borrador espere en este texto. Mira [Cuando un borrador espera](#cuando-un-borrador-espera). |

> **El cambio está en línea al instante**
Un prompt escrito con la API se usa desde el próximo mensaje del agente, también en un agente activo. Es lo mismo que **Publicar** en el dashboard. Guarda el `previous_version_id` de la respuesta: es tu camino de vuelta.

Cuatro cosas más que conviene saber:

- Enviar el texto que ya está en línea no escribe nada y responde `changed: false`.
- La respuesta lista `unknown_tokens`: los marcadores de tu texto que no corresponden a ninguna variable del agente. No se resuelven, así que el agente los leería tal cual. Corrígelos y envía el texto de nuevo.
- Lanzar, parar o reequilibrar un test A/B se queda en el dashboard, igual que las variables mismas.
- Cuando el texto en servicio no estaba en ninguna versión, primero se archiva en el historial, como una versión marcada `snapshot`. `previous_version_id` la señala, y el cambio se deshace como cualquier otro.

## Cuando un borrador espera

Un borrador es un texto guardado en el dashboard y nunca publicado. Su autor lo ve en el editor, y el agente no lo lee. Mientras un borrador espera en un texto, una escritura sobre ese texto responde `409 draft_pending` y no escribe nada: publicar otro texto dejaría el borrador de lado sin que nadie lo haya decidido.

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

El borrador aparece en `unpublished_drafts`, con su `version_id`. Dos llamadas lo resuelven:

1. **Ver qué cambia.** `GET …/versions/{versionId}/compare` con el id del borrador lo compara con el texto en servicio.
2. **Elegir.** Para publicar el borrador, restáuralo: `POST …/versions/{versionId}/restore`. Para mantener el texto en servicio como base, envía tu escritura de nuevo con `"ignore_draft": true`.

Un borrador dejado de lado no se elimina. Se queda en el historial con el estado `draft`, y sale de `unpublished_drafts` porque una versión más reciente está en línea.

## Seguimientos y agentes de grupo

Estos textos no guardan historial. Una escritura reemplaza el texto, y la respuesta trae `previous_body`, el texto reemplazado. Guárdalo si puedes querer volver a él. `variant` e `if_version` no se aplican.

```json
{
  "data": {
    "changed": true,
    "type": "follow_up_cold_1",
    "previous_body": "Escribe un seguimiento corto a {{prospectName}}, que aún no ha respondido.",
    "unknown_tokens": [],
    "prompt": { "type": "follow_up_cold_1", "versioned": false, "body": "Haz una sola pregunta sencilla sobre su proyecto.", "uses_default": false, "characters": 49, "max_characters": 15000, "enabled": true, "delay_hours": 24 }
  }
}
```

Escribir un seguimiento no lo activa. `enabled` y `delay_hours` se ajustan en el dashboard, en **Seguimientos**.

## Historial y restauración

`conversation` y `first_message` guardan cada versión. La lista va de la más reciente a la más antigua y trae una vista previa. Una versión sola da su texto completo.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions?limit=10" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "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": 183, "preview": "## Identidad Eres {{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": 112, "preview": "## Identidad Eres {{agent_name}} de {{company_name}}." }
  ],
  "pagination": { "has_more": false, "next_cursor": "68e60d3100212c0a9b41" }
}
```

| `status` | Significado |
|---|---|
| `live` | Lo que el agente lee ahora. |
| `draft` | Guardada en el dashboard, nunca publicada. |
| `inactive` | Reemplazada por una versión posterior, o su variante salió del test. |

`author` vale `api` para una versión escrita con una clave API y `dashboard` para las demás.

`snapshot` vale `true` en una versión que la API archivó ella misma: el texto que estaba en servicio fuera del historial, guardado en el momento en que un cambio lo reemplazó. Su `created_at` es la fecha de ese cambio, no el día en que se escribió el texto.

`name` es el nombre que una persona dio a la variante al publicar. Una fecha escrita por el dashboard no es un nombre: vuelve como `null`, y la fecha está en `created_at`.

Para volver atrás, restaura una versión: pasa el `previous_version_id` de una escritura para deshacerla. La versión se publica de nuevo como una versión nueva con el mismo texto, carácter por carácter: el historial sigue siendo una línea recta y la restauración también se puede deshacer. Restaurar un borrador lo publica. Restaurar otra versión mientras un borrador espera responde `409 draft_pending`, salvo que el cuerpo lleve `"ignore_draft": true`. Como una escritura, una restauración acepta `"if_version"`, la versión en línea que leíste de la variante de esa versión (la variante cuenta para un agente en test A/B): si ese texto cambió desde entonces, responde `409 version_conflict` y no se reemplaza nada.

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

## Comparar dos versiones

`GET …/versions/{versionId}/compare` devuelve lo que una versión cambia respecto a otra, línea por línea. Nombra la otra en `against`. Sin `against`, la versión se compara con el texto en servicio.

```bash
curl "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts/conversation/versions/68e61f7700093d5b1c02/compare?against=68e60d3100212c0a9b41" \
  -H "Authorization: Bearer ws_live_…"
```

```json
{
  "data": {
    "version": { "id": "68e61f7700093d5b1c02", "version": 8, "variant": "A", "status": "live", "created_at": "2026-10-08T14:02:11.000+00:00", "characters": 183 },
    "against": { "id": "68e60d3100212c0a9b41", "version": 7, "variant": "A", "status": "inactive", "created_at": "2026-10-07T09:18:22.000+00:00", "characters": 112 },
    "identical": false,
    "lines_added": 3,
    "lines_removed": 0,
    "diff": "@@ -4,2 +4,5 @@\n ## Objetivo\n Califica al lead y luego envía {{goal_link}}.\n+\n+## Reglas\n+Nunca des un precio antes de que el lead diga qué necesita."
  }
}
```

| Campo | Significado |
|---|---|
| `version`, `against` | Los dos textos comparados. `id` y `version` valen `null` para un texto en servicio que no está en ninguna versión. |
| `identical` | `true` cuando los dos textos son iguales. Los finales de línea y los espacios al final de una línea no son diferencias. |
| `lines_added`, `lines_removed` | Las líneas que la versión tiene y `against` no, y al revés. |
| `diff` | Un diff unificado con dos líneas de contexto. Una línea que empieza por `+` está en la versión y no en `against`. Una línea que empieza por `-`, al revés. Vacío cuando `identical` vale `true`. |

Tres preguntas que responde:

- **¿Qué cambió una escritura?** Compara el nuevo `version_id` con `previous_version_id`.
- **¿Qué cambiaría un borrador?** Compara el id del borrador, sin `against`.
- **¿Qué cambió desde una versión más antigua?** Compara el `version_id` en línea con la antigua.

## Encontrar por qué un agente dijo algo

Tres lecturas responden a la pregunta «por qué mi agente dijo eso»:

1. **El intercambio.** `GET /conversations/{leadId}/messages` da cada mensaje con su `type`. Un `LEAD_WELCOME` se escribió a partir de `first_message`, un `AI_RESPONSE` a partir de `conversation`, un `FOLLOWUP` a partir de un seguimiento. Un `MANUAL_RESPONSE` lo escribió una persona.
2. **El prompt.** `GET /campaigns/{id}/prompts` para el `campaign_id` del lead. Busca la instrucción que llevó al mensaje. Si el mensaje es más antiguo que la versión en línea, la lista de versiones te dice qué estaba en línea ese día. Para ver qué cambió entre dos versiones, mira [Comparar dos versiones](#comparar-dos-versiones).
3. **Los conocimientos.** Para una respuesta, `GET /knowledge-bases/{id}/search` con el mensaje del lead devuelve los pasajes que recibió el agente. Mira [Bases de conocimientos](/es/developers/guides/knowledge/).

Con el [servidor MCP](/es/developers/mcp/), un asistente hace estas tres lecturas por ti y cita la frase que explica la respuesta.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Clave ausente, desconocida o revocada. |
| 403 | `insufficient_scope` | A la clave le falta `prompts:read` o `prompts:write`. Una clave creada antes de que existieran estos scopes no los tiene. |
| 404 | `not_found` | Campaña, tipo o versión desconocidos, o de otro espacio. |
| 409 | `invalid_state` | El agente no tiene texto de ese tipo, ese texto no guarda historial, o la versión que se restaura no contiene ningún texto. |
| 409 | `version_conflict` | `if_version` no es la versión en línea: el texto cambió desde que lo leíste. |
| 409 | `draft_pending` | Un borrador guardado en el dashboard espera en este texto, y la llamada no lleva `ignore_draft`. |
| 409 | `variant_required` | Corre un test A/B y la llamada no nombra una variante. |
| 409 | `variant_not_live` | La variante nombrada salió del test mientras otra sirve. |
| 422 | `validation_error` | `body` ausente, vacío o demasiado largo, una `variant` que el agente no tiene, un `if_version` inválido, un `ignore_draft` que no es un booleano. |
| 429 | `rate_limited` | Demasiadas peticiones este minuto. Respeta `Retry-After`. |

## Relacionado

- [Bases de conocimientos](/es/developers/guides/knowledge/)
- [Conversaciones](/es/developers/guides/conversations/)
- [El prompt de tu agente en el dashboard](/es/dashboard/prompt/)
- [Servidor MCP](/es/developers/mcp/)
