Présentation des connecteurs

TelegramWhatsAppMessengerInstagramDiscordKakaoTalk

Les connecteurs reçoivent les événements d'une plateforme de messagerie externe, normalisent le texte ou l'audio pris en charge, exécutent le même agent de site et renvoient une réponse adaptée au canal. Chaque utilisateur externe dispose d'un historique de conversation propre au canal, visible dans Conversations.

La connexion d'un nouveau canal nécessite l'offre Operate ou Scale. Les connexions existantes continuent de fonctionner avec l'offre Launch.

Matrice des fonctionnalités#

« Voix entrante » signifie qu'un message vocal ou audio pris en charge est téléchargé puis transcrit. « Voix sortante » nécessite un fournisseur de synthèse vocale opérationnel et l'option Répondre par message vocal du connecteur. Les pièces jointes non prises en charge, telles que les images et les localisations, sont ignorées et ne sont pas interprétées comme des instructions pour l'agent.

Avant de connecter#

1. Testez l'agent concerné dans le tableau de bord. Un connecteur en brouillon peut déjà répondre.
2. Vous n'avez pas besoin de clé de modèle : la plateforme fournit les modèles. Les clés de fournisseur sont facultatives et réservées à l'offre Scale ; consultez Clés de fournisseur.
3. Créez une application, un bot, un numéro ou un canal dédié chez le fournisseur externe. Ne réutilisez pas un identifiant appartenant à une intégration de production sans rapport.
4. Vérifiez que votre déploiement dispose d'une URL de base de connecteur publique en HTTPS. Les webhooks des fournisseurs ne peuvent pas être livrés à localhost sans tunnel de développement sécurisé.
5. Ouvrez la page Canaux de l'agent et choisissez le canal.

Lors de l'enregistrement, Make Agent Fast appelle le fournisseur pour valider l'identifiant soumis. Le libellé « connecté » signifie que la validation de l'identifiant et tout provisionnement automatique ont abouti ; il ne prouve pas qu'une étape manuelle dans la console Meta, Discord ou Kakao a été réalisée.

Gestion des identifiants#

Les formulaires de connecteur n'acceptent les identifiants du fournisseur que depuis le tableau de bord authentifié ou l'API publique côté serveur. Les secrets sont chiffrés au repos et ne sont jamais renvoyés dans les réponses de liste des connecteurs. Traitez les valeurs suivantes comme des mots de passe :

• Jeton de bot Telegram
• Jetons d'accès Meta et secret de l'application
• Jeton de bot Discord
• Clé d'API REST Kakao et secret du bot

Ne les placez pas dans du JavaScript côté navigateur, des captures d'écran, des tickets de support ou un dépôt de code source. L'URL du webhook et le jeton de vérification Meta sont des valeurs de configuration destinées à être copiées dans la console du fournisseur correspondant ; elles ne remplacent pas les identifiants du fournisseur.

Se connecter via l'API#

Utilisez une clé d'API MAF conservée côté serveur avec le scope connectors:write. L'objet credentials propre à chaque canal est en écriture seule. La réponse omet les secrets en clair et inclut l'URL du webhook nécessaire à la configuration manuelle chez le fournisseur.

curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'

reply_with_voice et le champ facultatif display_label sont des champs de premier niveau, et non des éléments d'un objet config. Enregistrer à nouveau le même bot ou le même compte met à jour son identifiant et ses paramètres tout en conservant son jeton de routage. Pour Telegram et Instagram, un bot ou un compte différent ajoute une nouvelle connexion (jusqu'à cinq par agent) ; sur les autres canaux, l'enregistrement remplace la connexion existante. Consultez Authentification de l'API, Scopes et erreurs et la référence de l'API pour les règles d'intégration en production.

Tester et surveiller#

Utilisez un utilisateur de test du fournisseur et une question réaliste qui dépend des connaissances de l'agent. Vérifiez chacun des points suivants :

• Le fournisseur accepte ou vérifie le point de terminaison du webhook.
• Un message parvient à l'agent et reçoit la réponse attendue.
• Dernier message change sur la carte du connecteur.
• Le fil apparaît dans Conversations avec le bon canal.
• Toute restriction du fournisseur liée à la validation ou au mode développement est bien comprise avant le lancement public.
• La voix est testée séparément du texte lorsque le canal la prend en charge.

La carte du connecteur affiche la dernière erreur du fournisseur ou de livraison. Les tableaux de bord des fournisseurs conservent également des journaux de livraison ; comparez les horodatages et les identifiants d'événements lorsqu'un seul côté signale la requête.

Désactiver, renouveler ou supprimer#

Désactiver interrompt le traitement tout en conservant l'enregistrement du connecteur. Le webhook Telegram reste enregistré tant que la connexion est désactivée (Make Agent Fast n'appelle pas deleteWebhook) et les messages entrants sont ignorés ; la réactivation enregistre à nouveau le webhook. Les abonnements du fournisseur configurés dans la console restent en place et doivent aussi être suspendus côté fournisseur si nécessaire. Supprimer supprime le connecteur Make Agent Fast et tente, dans la mesure du possible, de démanteler la configuration chez le fournisseur, mais ne supprime pas l'application externe, ne révoque pas son identifiant et n'efface pas l'historique de conversation existant.

Pour un renouvellement, créez le nouveau jeton chez le fournisseur, mettez à jour le connecteur, testez-le, puis révoquez l'ancien jeton. Si un identifiant a été exposé, révoquez-le d'abord chez le fournisseur et traitez la période concernée comme un incident de sécurité.

Problèmes courants#

Poursuivez avec le guide du canal concerné pour connaître les champs exacts du fournisseur et la séquence à suivre dans sa console.