Ir al contenido
Dashboard

Guías por recurso

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.

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.

Método Ruta 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} 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.

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

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": "## 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.
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.

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.

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.

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.

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.

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": "## 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
}'
{
"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.

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.

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.

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

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.

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

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.

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

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

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

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

Con el servidor MCP, un asistente hace estas tres lecturas por ti y cita la frase que explica la respuesta.

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.