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.
Endpoints
Sección titulada «Endpoints»| 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.
Leer con qué trabaja un agente
Sección titulada «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 "https://app.whatsetter.com/api/v1/campaigns/acme-france-1-ab12/prompts" \ -H "Authorization: Bearer ws_live_…"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');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"){ "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.
Qué está en línea
Sección titulada «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_draftsmientras 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
varianten 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.
Cambiar un prompt
Sección titulada «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 -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 }'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);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"]){ "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_idla señala, y el cambio se deshace como cualquier otro.
Cuando un borrador espera
Sección titulada «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.
{ "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:
- Ver qué cambia.
GET …/versions/{versionId}/comparecon el id del borrador lo compara con el texto en servicio. - 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
Sección titulada «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.
{ "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
Sección titulada «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.
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.
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
Sección titulada «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.
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_idconprevious_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_iden línea con la antigua.
Encontrar por qué un agente dijo algo
Sección titulada «Encontrar por qué un agente dijo algo»Tres lecturas responden a la pregunta «por qué mi agente dijo eso»:
- El intercambio.
GET /conversations/{leadId}/messagesda cada mensaje con sutype. UnLEAD_WELCOMEse escribió a partir defirst_message, unAI_RESPONSEa partir deconversation, unFOLLOWUPa partir de un seguimiento. UnMANUAL_RESPONSElo escribió una persona. - El prompt.
GET /campaigns/{id}/promptspara elcampaign_iddel 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. - Los conocimientos. Para una respuesta,
GET /knowledge-bases/{id}/searchcon 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.
Errores que encontrarás
Sección titulada «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. |