Ir al contenido
Base de conocimiento

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.

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 }


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


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.

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

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


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


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": [
{"id": "...", "name": "John Smith", "email": "[email protected]", "project_id": "..."}
]
}

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.


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.


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": "...",
"email": "[email protected]",
"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.


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 }


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}"}
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"}