Connector-Übersicht

TelegramWhatsAppMessengerInstagramDiscordKakaoTalk

Connectors empfangen Ereignisse von einer externen Messaging-Plattform, normalisieren Text oder unterstützte Audiodateien, führen denselben Website-Agent aus und senden eine für den jeweiligen Channel passende Antwort zurück. Jeder externe Nutzer erhält einen Channel-spezifischen Gesprächsverlauf, der unter Konversationen sichtbar ist.

Für das Verbinden eines neuen Channels ist der Tarif Operate oder Scale erforderlich. Bestehende Verbindungen funktionieren im Tarif Launch weiterhin.

Funktionsmatrix#

„Sprache eingehend“ bedeutet, dass eine unterstützte Sprach- oder Audionachricht heruntergeladen und transkribiert wird. „Sprache ausgehend“ erfordert einen funktionierenden Sprachanbieter und die Option Mit Sprache antworten des Connectors. Nicht unterstützte Anhänge wie Bilder und Standorte werden ignoriert und nicht als Anweisungen an den Agent interpretiert.

Vor dem Verbinden#

1. Testen Sie den vorgesehenen Agent im Dashboard. Auch ein Connector im Entwurfsstatus kann bereits antworten.
2. Sie benötigen keinen Modellschlüssel: Die Plattform stellt die Modelle bereit. Anbieterschlüssel sind optional und nur im Tarif Scale verfügbar; siehe Anbieterschlüssel.
3. Erstellen Sie beim externen Anbieter eine eigene App, einen eigenen Bot, eine eigene Nummer oder einen eigenen Channel. Verwenden Sie keine Zugangsdaten wieder, die zu einer anderen Produktivintegration gehören.
4. Stellen Sie sicher, dass Ihre Bereitstellung über eine öffentliche HTTPS-Basis-URL für Connectors verfügbar ist. Webhooks von Anbietern können ohne einen sicheren Entwicklungstunnel nicht an localhost zugestellt werden.
5. Öffnen Sie die Seite Channels des Agents und wählen Sie den Channel aus.

Beim Speichern ruft Make Agent Fast den Anbieter auf, um die übermittelten Zugangsdaten zu validieren. Die Anzeige „Verbunden“ bedeutet, dass die Validierung der Zugangsdaten und eine eventuelle automatische Bereitstellung abgeschlossen wurden; sie beweist nicht, dass ein manueller Schritt in der Meta-, Discord- oder Kakao-Konsole durchgeführt wurde.

Umgang mit Zugangsdaten#

Connector-Formulare akzeptieren Zugangsdaten von Anbietern ausschließlich aus dem authentifizierten Dashboard oder der serverseitigen Public API. Geheimnisse werden im Ruhezustand verschlüsselt und niemals in Antworten der Connector-Liste zurückgegeben. Behandeln Sie die folgenden Werte wie Passwörter:

• Telegram-Bot-Token
• Meta-Zugriffstoken und App-Secret
• Discord-Bot-Token
• Kakao-REST-API-Schlüssel und Bot-Secret

Legen Sie sie nicht in Browser-JavaScript, Screenshots, Support-Tickets oder der Versionsverwaltung ab. Die Webhook-URL und das Meta-Verify-Token sind Konfigurationswerte, die in die entsprechende Konsole des Anbieters kopiert werden sollen; sie ersetzen nicht die Zugangsdaten des Anbieters.

Verbindung über die API#

Verwenden Sie einen serverseitig gespeicherten MAF-API-Schlüssel mit connectors:write. Das channelspezifische Objekt credentials ist ausschließlich schreibbar. Die Antwort enthält keine Geheimnisse im Klartext, aber die Webhook-URL, die für die manuelle Einrichtung beim Anbieter benötigt wird.

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 und das optionale Feld display_label sind Felder auf oberster Ebene und befinden sich nicht in einem config-Objekt. Wenn Sie denselben Bot oder dasselbe Konto erneut speichern, werden dessen Zugangsdaten und Einstellungen aktualisiert, während das Routing-Token erhalten bleibt. Bei Telegram und Instagram fügt ein anderer Bot oder ein anderes Konto eine neue Verbindung hinzu (bis zu fünf pro Agent); bei den anderen Channels ersetzt das Speichern die bestehende Verbindung. Beachten Sie für Produktivintegrationen API-Authentifizierung, Scopes und Fehler sowie die API-Referenz.

Testen und überwachen#

Verwenden Sie einen Testnutzer des Anbieters und eine realistische Frage, die vom Wissen des Agents abhängt. Prüfen Sie alle folgenden Punkte:

• Der Anbieter akzeptiert oder verifiziert den Webhook-Endpunkt.
• Eine Nachricht erreicht den Agent und erhält die erwartete Antwort.
• Letzte Nachricht ändert sich auf der Connector-Karte.
• Der Thread erscheint unter Konversationen mit dem richtigen Channel.
• Etwaige Einschränkungen durch die Prüfung des Anbieters oder den Entwicklungsmodus sind vor dem öffentlichen Start bekannt.
• Sprache wird getrennt vom Text getestet, sofern der Channel sie unterstützt.

Die Connector-Karte zeigt den letzten Fehler des Anbieters oder der Zustellung an. Auch die Dashboards der Anbieter bewahren Zustellprotokolle auf; vergleichen Sie Zeitstempel und Ereignis-IDs, wenn nur eine Seite die Anfrage meldet.

Deaktivieren, rotieren oder entfernen#

Deaktivieren beendet die Verarbeitung, behält aber den Connector-Datensatz bei. Der Telegram-Webhook bleibt registriert, solange die Verbindung deaktiviert ist (Make Agent Fast ruft deleteWebhook nicht auf), und eingehende Nachrichten werden ignoriert; beim Aktivieren wird der Webhook erneut registriert. In der Konsole konfigurierte Abonnements beim Anbieter bleiben bestehen und sollten bei Bedarf auch dort pausiert werden. Entfernen löscht den Connector in Make Agent Fast und versucht, die Einrichtung beim Anbieter nach bestem Bemühen zurückzubauen, löscht aber weder die externe App noch widerruft es deren Zugangsdaten oder löscht den bestehenden Gesprächsverlauf.

Für eine Rotation erstellen Sie zunächst das neue Token beim Anbieter, aktualisieren den Connector, testen ihn und widerrufen dann das alte Token. Wurden Zugangsdaten offengelegt, widerrufen Sie sie zuerst beim Anbieter und behandeln Sie den Zeitraum als Sicherheitsvorfall.

Häufige Fehler#

Die genauen Felder des Anbieters und die Abfolge in der Konsole finden Sie in der jeweiligen Channel-Anleitung.