Documentation développeur

Cette page décrit tout ce qu'un développeur doit savoir pour intégrer un agent Aya Mind : le widget, les points d'entrée publics, les outils appelés pendant la conversation, les serveurs MCP et les webhooks reçus après l'appel.

Un agent se crée dans la plateforme, à l'adresse /platform/agents. Retenez son identifiant : il apparaît dans l'URL de l'éditeur et dans l'onglet Widget.

Un agent doit être en statut actif pour répondre en dehors de la plateforme. Un agent en brouillon ne fonctionne que dans le panneau de test.

Les trois identifiants à ne pas confondre

Le widget est un script autonome à coller avant la fermeture de la balise </body>. Il crée un bouton flottant et gère lui-même le micro, la connexion vocale et l'affichage de la transcription. Il s'isole dans un Shadow DOM : il n'hérite pas du CSS de votre site et ne le modifie pas.

<script
  src="https://www.aya-mind.com/widget/agentic-widget.js"
  data-agent-id="VOTRE_AGENT_ID"
  data-server-url="https://www.aya-mind.com"
  data-position="bottom-right"
  data-color="#6B2362"
  defer
></script>

Ce que le widget demande au navigateur

À la première prise de parole, le navigateur demande l'autorisation du microphone. Cette autorisation exige une page servie en HTTPS. Sur une page en HTTP, l'appel échoue avec une erreur de périphérique.

Le widget vérifie le domaine appelant. Si la liste blanche de l'agent n'est pas vide et que votre domaine n'y figure pas, la configuration est refusée avec un code 403.

Chaque agent actif dispose d'une page publique, sans intégration à faire :

https://www.aya-mind.com/share/VOTRE_AGENT_ID

Cette page affiche le nom de l'agent, son message d'accueil, la transcription en direct et les commandes d'appel. Elle est utile pour un test client, une campagne ou un QR code affiché en boutique.

Une conversation n'utilise jamais de clé d'API côté navigateur. Le déroulé est le suivant :

1. Le widget demande la configuration publique de l'agent.
2. Il demande une URL de session signée, valable quelques minutes.
3. Il ouvre une connexion WebSocket sécurisée vers le moteur vocal avec cette URL.
4. À la fin de l'appel, il envoie la durée et la transcription pour l'historique.

La signature est générée côté serveur. Une URL signée interceptée expire rapidement et ne donne accès à aucun autre agent.

Ces trois points d'entrée ne demandent pas d'authentification, mais contrôlent le domaine appelant. Ils servent au widget et aux intégrations personnalisées.

curl https://www.aya-mind.com/api/widget/AGENT_ID/config \
  -H "Origin: https://votre-site.com"

{
  "name": "Assistante Aya",
  "firstMessage": "Bonjour, comment puis-je vous aider ?",
  "config": { "position": "bottom-right", "primaryColor": "#6B2362", "showTranscript": true },
  "chatEnabled": false
}

Enregistrer un appel mené par votre propre interface

curl -X POST https://www.aya-mind.com/api/widget/AGENT_ID/store-call \
  -H "Content-Type: application/json" \
  -d '{
    "startedAt": "2026-09-22T10:14:02Z",
    "endedAt": "2026-09-22T10:17:06Z",
    "durationSeconds": 184,
    "callerDomain": "votre-site.com",
    "messages": [
      { "role": "agent", "text": "Bonjour." },
      { "role": "user", "text": "Bonjour, une question sur ma commande." }
    ]
  }'

Un outil est une URL que l'agent appelle au milieu de la conversation. Vous le déclarez dans l'onglet Outils de l'agent : nom, description, URL, méthode. La description est déterminante : c'est elle qui indique au modèle quand appeler l'outil.

{
  "name": "verifier_commande",
  "description": "Retourne l'état d'une commande à partir de son numéro. Utiliser dès que le client donne un numéro de commande.",
  "url": "https://erp.votre-entreprise.ma/api/commandes/{numero}",
  "method": "GET",
  "headers": { "X-API-Key": "..." }
}

Règles à respecter côté votre API

• Répondez en moins de deux à trois secondes. Au-delà, le silence s'entend dans la conversation.
• Retournez du JSON court et lisible : l'agent le lit à voix haute après reformulation.
• Gérez l'erreur proprement, avec un message exploitable plutôt qu'une page HTML d'erreur.
• N'exposez que les champs nécessaires : tout ce que l'outil retourne peut être prononcé.

Un outil qui écrit (créer un ticket, annuler une commande) doit être idempotent quand c'est possible : un client peut répéter sa demande, et l'agent peut rappeler l'outil.

Le protocole MCP expose les outils d'un système entier avec un seul connecteur. Vous enregistrez le serveur une fois dans l'onglet Outils, puis vous l'activez sur les agents concernés.

Côté serveur MCP, nommez vos outils dans la langue des instructions de l'agent et décrivez-les précisément. Un outil nommé rechercher_client avec une bonne description sera mieux utilisé qu'un query générique.

Les variables permettent de personnaliser l'appel sans changer les instructions : nom du client, numéro de dossier, enseigne appelée. Vous les déclarez dans l'onglet Personnalité, puis vous les utilisez dans le prompt avec deux accolades.

Tu réponds pour {{nom_entreprise}}.
Le client s'appelle {{nom_client}} et son dossier porte le numéro {{numero_dossier}}.

La valeur saisie dans la plateforme sert de valeur par défaut. Une intégration peut fournir une valeur différente au démarrage de la session.

L'onglet Metrics sert à deux choses distinctes, selon le type choisi :

Les valeurs extraites apparaissent dans l'historique de l'appel et sont incluses dans la charge utile envoyée à vos webhooks.

Après chaque appel, Aya Mind peut envoyer un résumé complet à l'URL de votre choix. C'est le moyen le plus fiable d'alimenter un CRM sans interroger l'API en boucle.

POST /votre-endpoint
{
  "conversation_id": "conv_8f2c...",
  "agent": "Assistante Aya",
  "started_at": "2026-09-22T10:14:02Z",
  "duration_seconds": 184,
  "language": "fr",
  "sentiment": "positive",
  "summary": "Le client demande le statut de la facture 4412.",
  "transcript": [
    { "role": "agent", "text": "Bonjour, Aya Mind à votre écoute." },
    { "role": "user",  "text": "Bonjour, c'est au sujet de ma facture." }
  ],
  "data_collection": { "numero_facture": "4412" }
}

Bonnes pratiques de réception

• Répondez 200 rapidement, puis traitez en tâche de fond.
• Traitez les doublons : un même appel peut être notifié deux fois en cas de réessai.
• Vérifiez l'origine de la requête avant d'écrire dans votre système.

Un agent peut répondre dans Telegram. Vous créez un bot avec BotFather, vous collez son jeton dans l'onglet Telegram de l'agent, et la plateforme enregistre l'adresse de réception auprès de Telegram.

Les messages vocaux reçus sont transcrits, la réponse est renvoyée en audio. Les mêmes outils et la même base de connaissances s'appliquent.

Aucune clé d'API n'est exposée au navigateur, quelle que soit l'intégration. Si une intégration vous demande de publier une clé côté client, c'est une erreur de conception.