Outils de répondant — référence des outils MCP
Les outils de répondant gèrent les destinataires des enquêtes : création, mise à jour et suppression de répondants, génération en masse pour les tests et envoi d’invitations à répondre. Les répondants ne sont pas des utilisateurs de la plateforme : ils accèdent aux enquêtes par un lien magique, sans authentification.
list_respondents
Section intitulée « list_respondents »Liste les répondants, avec des filtres facultatifs.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
source_system |
string |
Non | — | Filtre par source (par ex. "crm", "panel_provider") |
project_id |
string |
Non | — | Filtre par projet |
name |
string |
Non | — | Correspondance de sous-chaîne, insensible à la casse |
limit |
integer |
Non | 100 |
Nombre maximal de résultats renvoyés |
Renvoie : { items: [...], count, limit }
get_respondent
Section intitulée « get_respondent »Récupère un répondant par son identifiant.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
respondent_id |
string |
Oui | — | UUID du répondant |
Renvoie : l’objet répondant ou { error }.
create_respondent
Section intitulée « create_respondent »Crée un seul répondant, avec ses attributs démographiques.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
string |
Oui | — | Nom affiché |
project_id |
string |
Non | — | Identifiant du projet |
email |
string |
Non | — | Adresse e-mail pour les invitations |
external_id |
string |
Non | — | Identifiant dans un système externe (CRM, panel) |
source_system |
string |
Non | — | Nom du système source (par ex. "crm") |
age |
integer |
Non | — | Âge |
gender |
string |
Non | — | Sexe |
location |
string |
Non | — | Localisation |
preferred_language |
string |
Non | — | Langue préférée (en, es, fr, de ou hu), ou null pour aucune. Détermine la langue de l’invitation et la langue présélectionnée sur la première page de l’enquête, si la campagne la propose ; le répondant peut toujours en choisir une autre |
custom_attributes |
object |
Non | {} |
Paires clé-valeur personnalisées pour le ciblage |
Renvoie : l’objet répondant créé.
Attributs démographiques
Section intitulée « Attributs démographiques »Les répondants disposent des champs démographiques suivants, utilisés pour la correspondance avec les stratégies d’échantillonnage et pour l’analyse des enquêtes :
| Attribut | Type | Utilisé par |
|---|---|---|
age |
integer | Facteurs d’échantillonnage par âge, pondération des personas de mass_fill_surveys |
gender |
string | Facteurs d’échantillonnage par sexe |
location |
string | Facteurs d’échantillonnage géographiques |
custom_attributes |
object | Ciblage et segmentation personnalisés |
update_respondent
Section intitulée « update_respondent »Met à jour les informations d’un répondant (mise à jour partielle : seuls les champs fournis changent).
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
respondent_id |
string |
Oui | — | UUID du répondant |
name |
string |
Non | — | Nouveau nom |
email |
string |
Non | — | Nouvelle adresse e-mail |
age |
integer |
Non | — | Nouvel âge |
gender |
string |
Non | — | Nouveau sexe |
location |
string |
Non | — | Nouvelle localisation |
external_id |
string |
Non | — | Nouvel identifiant externe |
source_system |
string |
Non | — | Nouveau système source |
preferred_language |
string |
Non | — | Nouvelle langue préférée ; omettez-la pour conserver la valeur enregistrée, envoyez null pour l’effacer |
custom_attributes |
object |
Non | — | Nouveaux attributs personnalisés (remplacent les existants) |
Renvoie : l’objet répondant mis à jour. Si aucune modification n’est détectée : { message: "No changes detected", respondent: {...} }.
delete_respondent
Section intitulée « delete_respondent »Supprime un répondant.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
respondent_id |
string |
Oui | — | UUID du répondant |
Renvoie : { deleted: true, respondent_id, respondent_info: { name, email, external_id, source_system } }
bulk_create_respondents
Section intitulée « bulk_create_respondents »Crée plusieurs répondants dotés de données démographiques fictives mais réalistes. Réservé aux données de test — ne l’utilisez pas pour des données de production.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
count |
integer |
Oui | — | Nombre de répondants à créer (1–100) |
project_id |
string |
Non | — | Identifiant du projet |
name_prefix |
string |
Non | "Test" |
Préfixe des noms générés |
source_system |
string |
Non | "bulk_generate" |
Nom du système source |
generate_demographics |
boolean |
Non | true |
Génère des données démographiques réalistes avec Faker |
preferred_language |
string |
Non | — | Une langue préférée unique pour tous les répondants créés |
Renvoie :
{ "created": 50, "project_id": "...", "source_system": "bulk_generate", "respondents": [ ]}Données démographiques générées
Section intitulée « Données démographiques générées »Lorsque generate_demographics vaut true (valeur par défaut), Faker génère :
| Champ | Méthode de génération |
|---|---|
name |
faker.name() |
email |
faker.email() |
age |
Entier aléatoire entre 18 et 75 |
gender |
Au hasard : "male", "female" ou "other" |
location |
"{city}, {country}" |
external_id |
"bulk-{random_hex}" |
Lorsque generate_demographics vaut false, l’outil génère des noms séquentiels ("Test Respondent 1") et des adresses e-mail, sans aucune donnée démographique.
generate_survey_access_token
Section intitulée « generate_survey_access_token »Génère un jeton de lien magique qui permet à un répondant d’accéder à son enquête sans authentification.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
survey_id |
string |
Oui | — | UUID de l’enquête |
respondent_id |
string |
Oui | — | UUID du répondant (doit correspondre au répondant de l’enquête) |
expiration_hours |
integer |
Non | 168 |
Nombre d’heures avant l’expiration du jeton (par défaut : 7 jours) |
Renvoie :
{ "token": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "survey_id": "...", "respondent_id": "...", "expiration_hours": 168}Lorsque la campagne de l’enquête propose l’assistant IA, le résultat comporte aussi connector_url, l’adresse du connecteur du répondant (https://portor.<tenant>.askalot.io/respond/mcp) : une invitation que vous transmettez vous-même peut ainsi indiquer les deux façons d’accéder à l’enquête. Le code d’association n’est jamais renvoyé ici : le répondant l’obtient sur sa propre page d’enquête. Voir Auto-entretien assisté par l’IA.
send_survey_invitation
Section intitulée « send_survey_invitation »Envoie à un répondant un e-mail d’invitation contenant un lien magique. Envoie un véritable e-mail.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
survey_id |
string |
Oui | — | UUID de l’enquête |
respondent_id |
string |
Oui | — | UUID du répondant (doit correspondre au répondant de l’enquête) |
expiration_hours |
integer |
Non | 168 |
Nombre d’heures avant l’expiration du lien (par défaut : 7 jours) |
subject |
string |
Non | — | Objet personnalisé de l’e-mail. Par défaut : "You're invited to complete: {questionnaire_name}" |
body_template |
string |
Non | — | Corps personnalisé, avec les variables : {name}, {url}, {expiration}, {questionnaire} |
Renvoie :
{ "status": "sent", "survey_id": "...", "respondent_id": "...", "survey_url": "https://sirway.dev.askalot.io/s/{token}", "message_id": "...", "message_bus_used": true}L’e-mail est rédigé dans la langue de l’enquête : celle déjà choisie, sinon la langue préférée du répondant si la campagne propose une traduction complète dans cette langue, sinon la langue source du questionnaire. Un subject et un body_template personnalisés sont envoyés tels quels.
Lorsque la campagne de l’enquête propose l’assistant IA, l’e-mail ajoute un paragraphe indiquant au répondant qu’il peut ouvrir le lien et choisir de répondre à l’enquête avec son propre assistant IA, et le résultat comporte aussi connector_url.
bulk_delete_respondents
Section intitulée « bulk_delete_respondents »Supprime plusieurs répondants selon des critères de filtre. L’outil fonctionne en deux temps : appelez-le d’abord avec dry_run=true pour voir ce qui sera supprimé, puis rappelez-le avec dry_run=false pour exécuter la suppression.
Au moins un filtre doit être indiqué, afin d’éviter une suppression massive accidentelle.
| Paramètre | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
source_system |
string |
Non | — | Filtre par système source (par ex. "bulk_generate", "mcp_review") |
project_id |
string |
Non | — | Filtre par identifiant de projet |
orphans_only |
boolean |
Non | false |
Ne cible que les répondants sans projet (se combine avec les autres filtres) |
dry_run |
boolean |
Non | true |
Mode aperçu : renvoie le nombre et un échantillon, sans rien supprimer |
En mode aperçu, renvoie :
{ "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."}En exécution, renvoie : { dry_run: false, deleted: 50 }
Gestion des erreurs
Section intitulée « Gestion des erreurs »Erreurs courantes
Section intitulée « Erreurs courantes »| Cas | Réponse |
|---|---|
| Répondant introuvable | {"error": "Respondent {id} not found"} |
| Enquête introuvable | {"error": "Survey {id} not found"} |
| Répondant ne correspondant pas | {"error": "Respondent is not the respondent for this survey"} |
| Aucune adresse e-mail | {"error": "Respondent has no email address"} |
| Désinscription | {"error": "Respondent has opted out of notifications"} |
| Échec de l’envoi de l’e-mail | {"error": "Failed to send email: {details}"} |
Limites de la création en masse
Section intitulée « Limites de la création en masse »| Cas | Réponse |
|---|---|
| Nombre supérieur à 100 | {"error": "Maximum 100 respondents per request"} |
| Nombre inférieur à 1 | {"error": "Count must be at least 1"} |