Ir al contenido
Base de conocimiento

Herramientas de campaña — Referencia de herramientas MCP

Las herramientas de campaña gestionan el ciclo de vida de las campañas de encuesta: crear campañas, asignar entrevistadores y grupos de encuestados, repartir la carga de trabajo y enviar invitaciones. Muchas operaciones siguen un patrón de respuesta en bloque con los campos added/skipped/reasons.

Lista todas las campañas, opcionalmente filtradas por proyecto, nombre o estado.

Parámetro Tipo Obligatorio Predeterminado Descripción
project_id string No — Filtra por ID de proyecto
name string No — Filtra por nombre de campaña
status string No — Filtra por estado
limit integer No 100 Número máximo de resultados que se devuelven

Devuelve: { items: [...], count, limit }


Obtiene una campaña por su ID.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña

Devuelve: el objeto de la campaña o { error }. Incluye offered_languages: los idiomas que pueden elegir los encuestados; primero el idioma de origen del cuestionario y después cada traducción completa de la versión fijada, cada una como { locale, name, human_edited }. Una campaña sin versión fijada solo ofrece el idioma de origen.


Crea una campaña nueva. El modo de la campaña se determina automáticamente según haya o no entrevistadores asignados.

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre visible de la campaña
project_id string Sí — ID del proyecto al que pertenece
questionnaire_id string Sí — Cuestionario que se utilizará
status string No "draft" Estado inicial: draft, active o scheduled. Cualquier otro valor se rechaza
admits_volunteers boolean Sí — Si pueden participar personas que nunca se extrajeron para el grupo de la campaña (participantes espontáneos, el enlace abierto). No tiene valor predeterminado: indíquelo.
offers_ai_channel boolean Sí — Si los encuestados pueden responder también a la encuesta en su propio asistente de IA. No tiene valor predeterminado: indíquelo.
intro_text string Cuando offers_ai_channel es true — Quién recoge los datos y con qué fin; se muestra literalmente antes de la primera pregunta
consent_text string Cuando offers_ai_channel es true — Lo que acepta el encuestado; se muestra literalmente, y siempre se añade a continuación un párrafo fijo sobre el proveedor de IA

Devuelve: el objeto de la campaña creada.

update_campaign solo cambia status siguiendo el ciclo de vida de la campaña: draft → active o scheduled; scheduled → active o draft; active → paused, completed o aborted; paused → active, completed o aborted; completed o aborted → draft. Cualquier otro cambio, o un estado desconocido, se rechaza y no se modifica nada.

update_campaign también acepta offers_ai_channel, intro_text y consent_text, todos opcionales; si se omiten, se conserva el valor almacenado en la campaña. Los textos se comprueban sobre el resultado: activar el asistente en una campaña que ya tiene ambos textos no requiere volver a indicarlos, y vaciar un texto mientras se ofrece el asistente se rechaza. Desactivar el asistente invalida todos los códigos de emparejamiento aún no utilizados; los encuestados que ya están conectados pueden terminar.


Añade entrevistadores (usuarios con el rol de entrevistador) a una campaña. Sigue el patrón de respuesta en bloque.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
user_ids string[] Sí — Lista de ID de usuario que se añaden como entrevistadores

Devuelve:

{
"campaign_id": "...",
"added": ["uid1"],
"already_present": ["uid2"],
"skipped": [{"id": "uid3", "reason": "User not found"}],
"total_added": 1
}

Motivos de omisión: "User not found" (usuario no encontrado), "No interviewer role" (sin rol de entrevistador).


Retira entrevistadores de una campaña.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
user_ids string[] Sí — Lista de ID de usuario que se retiran

Devuelve:

{
"campaign_id": "...",
"removed": ["uid1"],
"not_found": ["uid2"],
"total_removed": 1
}

Cambia el cuestionario asignado a una campaña.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
questionnaire_id string Sí — UUID del nuevo cuestionario

Devuelve:

{
"campaign_id": "...",
"old_questionnaire_id": "...",
"new_questionnaire_id": "...",
"success": true,
"warning": "Campaign has existing surveys — they reference the old questionnaire"
}

Asigna encuestados concretos a un entrevistador concreto dentro de una campaña para repartir la carga de trabajo.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
interviewer_id string Sí — UUID del usuario entrevistador
respondent_ids string[] Sí — Lista de ID de encuestados que se asignan

Devuelve:

{
"assigned": ["r1"],
"already_assigned": ["r2"],
"not_in_campaign": ["r3"]
}

Retira encuestados de la asignación de un entrevistador. Los encuestados siguen en el grupo de la campaña, pero quedan sin asignar.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
interviewer_id string Sí — UUID del usuario entrevistador
respondent_ids string[] Sí — Lista de ID de encuestados cuya asignación se retira

Devuelve:

{
"unassigned": ["r1"],
"not_assigned": ["r2"]
}

Obtiene la carga de trabajo de un entrevistador concreto en una campaña: los encuestados asignados y el estado de finalización de sus encuestas.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
interviewer_id string Sí — UUID del usuario entrevistador

Devuelve:

{
"campaign_id": "...",
"interviewer_id": "...",
"assigned_respondents": [
{"id": "...", "name": "...", "email": "...", "age": 35, "gender": "female", "location": "Berlin"}
],
"survey_status": {
"respondent_id": {"survey_id": "...", "status": "completed", "completed": true}
},
"statistics": {
"total_assigned": 10,
"completed": 3,
"in_progress": 2,
"not_started": 5,
"completion_rate": 0.3
}
}

Obtiene los encuestados de una campaña que aún no están asignados a ningún entrevistador.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña

Devuelve:

{
"campaign_id": "...",
"unassigned_count": 5,
"unassigned_respondents": [
{"id": "...", "name": "...", "email": "...", "age": 28, "gender": "male", "location": "Munich"}
]
}

Asigna un grupo de encuestados a una campaña. Vincula el grupo para que bulk_create_surveys pueda crear encuestas para todos los encuestados del grupo.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
pool_id string Sí — UUID del grupo de encuestados

Devuelve:

{
"campaign_id": "...",
"pool_id": "...",
"pool_name": "Urban Millennials",
"respondent_count": 200,
"previous_pool_id": null
}

Obtiene el grupo de encuestados asignado a una campaña.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña

Devuelve (con grupo asignado):

{
"campaign_id": "...",
"pool_id": "...",
"pool_name": "...",
"pool_description": "...",
"respondent_count": 200,
"respondent_ids": ["..."],
"source_type": "strategy",
"source_strategy_id": "...",
"quality_score": 0.95,
"has_pool": true
}

Devuelve (sin grupo): { campaign_id, pool_id: null, has_pool: false, message: "..." }


Envía los correos de invitación a la encuesta a los encuestados de la campaña. Envía correos reales con acceso mediante enlace mágico.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — UUID de la campaña
respondent_ids string[] No — Encuestados concretos a los que invitar
send_to_all_uninvited boolean No false Envía a todos los encuestados que aún no han sido invitados

Cada invitación se redacta en el idioma de su destinatario: el idioma preferido del encuestado cuando la campaña ofrece una traducción completa a ese idioma o, en caso contrario, el idioma de origen del cuestionario.

Devuelve:

{
"campaign_id": "...",
"results": {
"sent": [{"respondent_id": "...", "name": "...", "email": "...", "survey_id": "...", "survey_url": "..."}],
"skipped": [{"respondent_id": "...", "name": "...", "reason": "No email address"}],
"failed": [{"respondent_id": "...", "name": "...", "reason": "Email send failed: ..."}]
},
"summary": {"sent": 8, "skipped": 1, "failed": 1}
}

Cuando la campaña ofrece el asistente de IA, cada correo de invitación añade un párrafo que remite al encuestado a la opción de IA de su página de la encuesta, y cada entrada de sent incluye además connector_url, la dirección del conector del encuestado.

Requisitos de cada encuestado para recibir la invitación:

  • Debe tener una dirección de correo electrónico
  • notification_preference no debe ser "none"
  • La encuesta no debe estar ya completada ni en curso
  • La campaña debe aceptarlo. Invitar a alguien que la campaña nunca extrajo para su grupo requiere una campaña que admita voluntarios y que esté en pleno trabajo de campo: el mismo filtro de admisión por el que pasa un participante espontáneo. Su encuesta se registra entonces como de voluntario y no como un caso extraído, de modo que el conjunto de datos puede seguir distinguiendo ambos.

Motivos de omisión: "Respondent not found" (encuestado no encontrado), "No email address" (sin dirección de correo), "Opted out of notifications" (ha rechazado las notificaciones), "Survey already completed" (encuesta ya completada), "Survey already in_progress" (encuesta ya en curso), además de un rechazo que indica cuál de las dos condiciones del filtro de admisión no se cumplió: la campaña no acepta participantes espontáneos o no está en trabajo de campo en ese momento.


Dos de las secuencias anteriores también están disponibles como una sola llamada. No son atajos que se salten nada: cada paso es la misma herramienta documentada en esta página, de modo que se escriben los mismos registros, se generan los mismos eventos de auditoría y cualquier rechazo que daría una herramienta individual se devuelve aquí sin cambios, más stopped_at_step, que indica de qué paso procede la detención. No se deshace nada, así que una cadena que se detiene a medias conserva lo que construyeron los pasos anteriores y usted continúa con las herramientas individuales.

Una cadena comprueba sus derechos de uso para cada paso antes de construir nada. Si su suscripción no cubre un paso posterior, se rechaza de antemano en lugar de entregarle un trabajo de campo a medio preparar.

Ejecuta toda la cadena de preparación del trabajo de campo de una campaña: crea la estrategia de muestreo, genera el grupo de encuestados, asigna el grupo a la campaña, publica (y fija) la versión del cuestionario que usará la campaña y crea las encuestas.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — Campaña que se prepara. Debe tener ya asignado el cuestionario que se pretende usar
admits_volunteers boolean Sí ninguno La política de admisión de voluntarios de este trabajo de campo, indicada explícitamente. No hay valor predeterminado y debe coincidir con la configuración de la propia campaña; si no es la correcta, cámbiela antes con update_campaign
strategy_name string Sí — Nombre de la estrategia de muestreo que crea esta ejecución
target_size integer Sí — El tamaño solicitado de la extracción del grupo: encuestados que se extraen, antes del sobremuestreo (> 0). Se pasa a la extracción como requested_size y se guarda en el grupo
factors object[] No [] Factores de distribución demográfica con los que la estrategia evalúa el ajuste
selection_algorithm string No "greedy" Algoritmo de selección para la extracción del grupo ("greedy" o "random_constrained")
oversample_factor number No 1.0 Multiplicador de sobremuestreo para la extracción del grupo (≥ 1)
quality_metric string No "rmse" Métrica con la que la estrategia evalúa el ajuste: "rmse", "mae", "chi_square" o "max_deviation". Cualquier otro valor se rechaza antes de construir nada
require_email boolean No false La extracción del grupo solo admite encuestados que tengan dirección de correo electrónico
pool_name string No — Nombre del grupo generado; por defecto, una etiqueta derivada de la estrategia

La estrategia que crea esta ejecución solo contiene factors y quality_metric. Los ajustes de selección (target_size, oversample_factor, selection_algorithm, require_email) pasan al paso del grupo y se guardan en el grupo, exactamente como los guardaría una llamada directa a generate_pool_from_strategy.

Devuelve: ready_to_invite, el strategy_id, pool_id, pool_respondent_count, qml_version_id, los offered_languages que pueden elegir los encuestados para esa versión (como en get_campaign) y los surveys_created / surveys_skipped que produjo, más next_step. Si se detiene: stopped_at_step con el error y el detail del paso que lo rechazó, y todo lo que los pasos anteriores ya habían construido.

Por qué importa el paso de publicación. Una cadena montada a mano suele olvidar la publicación, y una campaña sin versión fijada resuelve la versión más reciente del cuestionario en el momento de la lectura, de modo que una edición hecha en pleno trabajo de campo cambia en silencio el instrumento para encuestados que ya han respondido.

Volver a ejecutarla extrae de nuevo. Cada ejecución crea una estrategia y un grupo nuevos y vuelve a vincular la campaña a ellos (un grupo es de un solo uso); después recorre el nuevo grupo y omite a los encuestados que ya tienen una encuesta en esta campaña. Con una lista de encuestados mayor que target_size, una segunda ejecución añade por tanto encuestados recién extraídos en lugar de sustituir a nadie.


Crea las encuestas de la campaña y después genera respuestas sintéticas sobre ellas. Consulte mass_fill_surveys para saber qué hace cada modo de distribución y cada perfil de persona.

Parámetro Tipo Obligatorio Predeterminado Descripción
campaign_id string Sí — Campaña cuyas encuestas se crean y después se rellenan
distribution string No "realistic" "realistic", "random" o "llm"
max_surveys integer No — Límite de encuestas de la campaña que se rellenan
profiles string[] No ["random"] Nombres de los perfiles de persona que se asignan de forma rotativa a los encuestados
concurrency integer No 1 Paralelismo del bucle interno del relleno

Devuelve: surveys_created / surveys_skipped, y un task_id para el relleno con status: "pending". Consúltelo con get_task_status exactamente igual que una ejecución de mass_fill_surveys. Si se detiene: stopped_at_step con el error y el detail del paso que lo rechazó, y task_id: null.


Situación Respuesta
Campaña no encontrada {"error": "Campaign {id} not found"}
Entrevistador no asignado a la campaña {"error": "Interviewer {id} is not assigned to this campaign"}
Sin cuestionario/grupo {"error": "Campaign has no questionnaire assigned"}

La mayoría de las herramientas de campaña que aceptan listas de ID devuelven resultados estructurados en lugar de fallar por elementos individuales:

{
"added": ["id1"],
"already_present": ["id2"],
"skipped": [{"id": "id3", "reason": "User not found"}],
"total_added": 1
}

Este patrón se aplica a: add_interviewers_to_campaign, remove_interviewers_from_campaign, assign_respondents_to_interviewer, unassign_respondents_from_interviewer y send_campaign_invitations.

Cada elemento omitido o fallido incluye un campo reason que explica por qué se excluyó de la operación.