Herramientas de encuestados — Referencia de herramientas MCP
Las herramientas de encuestados gestionan los destinatarios de las encuestas: crear, actualizar y eliminar encuestados, generarlos en bloque para pruebas y enviar invitaciones a encuestas. Los encuestados no son usuarios de la plataforma; acceden a las encuestas mediante enlaces mágicos, sin autenticación.
list_respondents
Sección titulada «list_respondents»Lista los encuestados con filtros opcionales.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
source_system |
string |
No | — | Filtra por origen (p. ej., "crm", "panel_provider") |
project_id |
string |
No | — | Filtra por proyecto |
name |
string |
No | — | Coincidencia por subcadena, sin distinguir mayúsculas y minúsculas |
limit |
integer |
No | 100 |
Número máximo de resultados que se devuelven |
Devuelve: { items: [...], count, limit }
get_respondent
Sección titulada «get_respondent»Obtiene un encuestado por su ID.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
respondent_id |
string |
Sí | — | UUID del encuestado |
Devuelve: el objeto del encuestado o { error }.
create_respondent
Sección titulada «create_respondent»Crea un único encuestado con atributos demográficos.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
name |
string |
Sí | — | Nombre visible |
project_id |
string |
No | — | ID del proyecto |
email |
string |
No | — | Correo electrónico para las invitaciones |
external_id |
string |
No | — | ID en un sistema externo (CRM, panel) |
source_system |
string |
No | — | Nombre del sistema de origen (p. ej., "crm") |
age |
integer |
No | — | Edad |
gender |
string |
No | — | Género |
location |
string |
No | — | Ubicación |
preferred_language |
string |
No | — | Idioma preferido (en, es, fr, de o hu), o null para ninguno. Determina el idioma de la invitación y el idioma preseleccionado en la primera página de la encuesta, cuando la campaña lo ofrece; el encuestado puede elegir otro igualmente |
custom_attributes |
object |
No | {} |
Pares clave-valor personalizados para la segmentación |
Devuelve: el objeto del encuestado creado.
Atributos demográficos
Sección titulada «Atributos demográficos»Los encuestados admiten estos campos demográficos para el ajuste a las estrategias de muestreo y el análisis de encuestas:
| Atributo | Tipo | Lo usa |
|---|---|---|
age |
integer | Factores de muestreo por edad, ponderación de perfiles de mass_fill_surveys |
gender |
string | Factores de muestreo por género |
location |
string | Factores de muestreo geográficos |
custom_attributes |
object | Segmentación y selección personalizadas |
update_respondent
Sección titulada «update_respondent»Actualiza la información de un encuestado (actualización parcial: solo cambian los campos proporcionados).
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
respondent_id |
string |
Sí | — | UUID del encuestado |
name |
string |
No | — | Nuevo nombre |
email |
string |
No | — | Nuevo correo electrónico |
age |
integer |
No | — | Nueva edad |
gender |
string |
No | — | Nuevo género |
location |
string |
No | — | Nueva ubicación |
external_id |
string |
No | — | Nuevo ID externo |
source_system |
string |
No | — | Nuevo sistema de origen |
preferred_language |
string |
No | — | Nuevo idioma preferido; omítalo para conservar el valor guardado o envíe null para borrarlo |
custom_attributes |
object |
No | — | Nuevos atributos personalizados (sustituyen a los existentes) |
Devuelve: el objeto del encuestado actualizado. Si no se detectan cambios: { message: "No changes detected", respondent: {...} }.
delete_respondent
Sección titulada «delete_respondent»Elimina un encuestado.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
respondent_id |
string |
Sí | — | UUID del encuestado |
Devuelve: { deleted: true, respondent_id, respondent_info: { name, email, external_id, source_system } }
bulk_create_respondents
Sección titulada «bulk_create_respondents»Crea varios encuestados con datos demográficos ficticios realistas. Solo para datos de prueba: no lo use con datos de producción.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
count |
integer |
Sí | — | Número que se crea (1–100) |
project_id |
string |
No | — | ID del proyecto |
name_prefix |
string |
No | "Test" |
Prefijo de los nombres generados |
source_system |
string |
No | "bulk_generate" |
Nombre del sistema de origen |
generate_demographics |
boolean |
No | true |
Genera datos demográficos realistas con Faker |
preferred_language |
string |
No | — | Un mismo idioma preferido para todos los encuestados creados |
Devuelve:
{ "created": 50, "project_id": "...", "source_system": "bulk_generate", "respondents": [ ]}Datos demográficos generados
Sección titulada «Datos demográficos generados»Cuando generate_demographics es true (valor predeterminado), Faker genera:
| Campo | Método de generación |
|---|---|
name |
faker.name() |
email |
faker.email() |
age |
Entero aleatorio entre 18 y 75 |
gender |
Aleatorio: "male", "female" u "other" |
location |
"{city}, {country}" |
external_id |
"bulk-{random_hex}" |
Cuando generate_demographics es false, genera nombres secuenciales ("Test Respondent 1") y correos electrónicos sin datos demográficos.
generate_survey_access_token
Sección titulada «generate_survey_access_token»Genera un token de enlace mágico para que un encuestado acceda a su encuesta sin autenticación.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
respondent_id |
string |
Sí | — | UUID del encuestado (debe coincidir con el encuestado de la encuesta) |
expiration_hours |
integer |
No | 168 |
Horas hasta que caduca el token (predeterminado: 7 días) |
Devuelve:
{ "token": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "survey_id": "...", "respondent_id": "...", "expiration_hours": 168}Cuando la campaña de la encuesta ofrece el asistente de IA, el resultado incluye además connector_url, la dirección del conector para encuestados (https://portor.<tenant>.askalot.io/respond/mcp), de modo que una invitación que usted transmita a mano pueda indicar ambas vías de acceso. El código de emparejamiento en sí nunca se devuelve aquí: el encuestado lo obtiene en su propia página de la encuesta. Consulte Autoentrevista asistida por IA.
send_survey_invitation
Sección titulada «send_survey_invitation»Envía a un encuestado un correo electrónico de invitación a la encuesta con un enlace mágico. Envía un correo electrónico real.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
survey_id |
string |
Sí | — | UUID de la encuesta |
respondent_id |
string |
Sí | — | UUID del encuestado (debe coincidir con el encuestado de la encuesta) |
expiration_hours |
integer |
No | 168 |
Horas hasta que caduca el enlace (predeterminado: 7 días) |
subject |
string |
No | — | Asunto personalizado del correo. Predeterminado: "You're invited to complete: {questionnaire_name}" |
body_template |
string |
No | — | Cuerpo personalizado con marcadores: {name}, {url}, {expiration}, {questionnaire} |
Devuelve:
{ "status": "sent", "survey_id": "...", "respondent_id": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "message_id": "...", "message_bus_used": true}El correo se redacta en el idioma de la encuesta: el que ya se haya elegido; si no, el idioma preferido del encuestado cuando la campaña ofrece una traducción completa a ese idioma; y, en otro caso, el idioma de origen del cuestionario. Un subject y un body_template personalizados se envían tal como están escritos.
Cuando la campaña de la encuesta ofrece el asistente de IA, el correo añade un párrafo que indica al encuestado que puede abrir el enlace y elegir responder la encuesta con su propio asistente de IA, y el resultado incluye además connector_url.
bulk_delete_respondents
Sección titulada «bulk_delete_respondents»Elimina varios encuestados según criterios de filtro. Sigue un flujo en dos pasos: llame primero con dry_run=true para previsualizar lo que se eliminará y vuelva a llamar con dry_run=false para ejecutarlo.
Debe indicarse al menos un filtro para evitar eliminaciones masivas accidentales.
| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|---|
source_system |
string |
No | — | Filtra por sistema de origen (p. ej., "bulk_generate", "mcp_review") |
project_id |
string |
No | — | Filtra por ID de proyecto |
orphans_only |
boolean |
No | false |
Afecta solo a encuestados sin proyecto (se combina con los demás filtros) |
dry_run |
boolean |
No | true |
Modo de previsualización: devuelve el recuento y una muestra sin eliminar nada |
La simulación devuelve:
{ "dry_run": true, "count": 50, "sample": [{"id": "...", "name": "...", "source_system": "bulk_generate", "project_id": null}], "message": "Would delete 50 respondents. Call again with dry_run=False to execute."}La ejecución devuelve: { dry_run: false, deleted: 50 }
Gestión de errores
Sección titulada «Gestión de errores»Errores comunes
Sección titulada «Errores comunes»| Situación | Respuesta |
|---|---|
| Encuestado no encontrado | {"error": "Respondent {id} not found"} |
| Encuesta no encontrada | {"error": "Survey {id} not found"} |
| El encuestado no coincide | {"error": "Respondent is not the respondent for this survey"} |
| Sin dirección de correo electrónico | {"error": "Respondent has no email address"} |
| Ha desactivado las notificaciones | {"error": "Respondent has opted out of notifications"} |
| Falló el envío del correo | {"error": "Failed to send email: {details}"} |
Límites de la creación masiva
Sección titulada «Límites de la creación masiva»| Situación | Respuesta |
|---|---|
| El recuento supera 100 | {"error": "Maximum 100 respondents per request"} |
| El recuento es inferior a 1 | {"error": "Count must be at least 1"} |