Aller au contenu
Base de connaissances

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.

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 }


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


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

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

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


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


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

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.


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.


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


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 }


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}"}
Cas Réponse
Nombre supérieur à 100 {"error": "Maximum 100 respondents per request"}
Nombre inférieur à 1 {"error": "Count must be at least 1"}