> ## Documentation Index
> Fetch the complete documentation index at: https://revolai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Messenger-Integrationen

> Verbinden Sie Telegram, WhatsApp, Instagram und Facebook Messenger

## Unterstuetzte Messenger

| Messenger              | Authentifizierung | Eingehend | Ausgehend | Tools |
| ---------------------- | ----------------- | --------- | --------- | ----- |
| **Telegram**           | Bot-Token         | Ja        | Ja        | 6     |
| **WhatsApp Business**  | Meta OAuth        | Ja        | Ja        | 6     |
| **Instagram DM**       | Meta OAuth        | Ja        | Ja        | 6     |
| **Facebook Messenger** | Meta OAuth        | Ja        | Ja        | 6     |

## Telegram

Telegram ist die einfachste Integration — kein OAuth, keine SDK-Abhaengigkeiten. Nur ein Bot-Token von BotFather.

### Einrichtung

<Steps>
  <Step title="Einen Bot erstellen">
    Oeffnen Sie [@BotFather](https://t.me/BotFather) in Telegram, senden Sie `/newbot` und folgen Sie den Anweisungen. Sie erhalten ein **Bot-Token** wie `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`.
  </Step>

  <Step title="Integration hinzufuegen">
    Gehen Sie zu **Integrationen** → **Integration hinzufuegen** → waehlen Sie **Telegram** aus der Kategorie Messenger.
  </Step>

  <Step title="Token eingeben">
    Waehlen Sie ein Unternehmen, benennen Sie die Integration und fuegen Sie Ihr Bot-Token ein.
  </Step>

  <Step title="Verifizieren und speichern">
    Revol ruft die Telegram Bot API auf, um das Token zu verifizieren, und richtet den Webhook automatisch ein. Ihr Bot beginnt sofort, Nachrichten zu empfangen.
  </Step>
</Steps>

### Agenten-Tools

| Tool               | Beschreibung                                                                            |
| ------------------ | --------------------------------------------------------------------------------------- |
| `send_message`     | Eine Textnachricht senden (HTML- oder Markdown-Formatierung) mit optionaler Antwort-auf |
| `send_file`        | Ein Foto, Dokument, Audio oder Video per oeffentlicher URL senden                       |
| `get_chat_history` | Aktuelle Nachrichten aus einem Chat abrufen                                             |
| `get_chat_info`    | Chat-/Benutzer-Metadaten abrufen (Name, Bio, Mitgliederzahl)                            |
| `edit_message`     | Eine zuvor gesendete Bot-Nachricht bearbeiten                                           |
| `delete_message`   | Eine Nachricht aus dem Chat loeschen                                                    |

***

## WhatsApp Business

Die WhatsApp Business API wird ueber Metas Graph API aufgerufen. Erfordert ein Meta Business-Konto mit WhatsApp Business API-Zugang.

### Einrichtung

<Steps>
  <Step title="Meta Business-Setup">
    Erstellen Sie ein [Meta Business-Konto](https://business.facebook.com/) und richten Sie den WhatsApp Business API-Zugang ein.
  </Step>

  <Step title="Integration hinzufuegen">
    Gehen Sie zu **Integrationen** → **Integration hinzufuegen** → waehlen Sie **WhatsApp Business**.
  </Step>

  <Step title="OAuth">
    Klicken Sie auf "Mit Meta verbinden" — Sie werden zum Meta-Zustimmungsbildschirm weitergeleitet. Autorisieren Sie den Zugriff auf Ihr WhatsApp Business-Konto.
  </Step>

  <Step title="Konfigurieren">
    Geben Sie Ihre Telefonnummer-ID und Ihr App-Geheimnis ein. Revol tauscht den OAuth-Code gegen ein langlebiges Token (\~60 Tage).
  </Step>
</Steps>

<Note>
  WhatsApp hat ein **24-Stunden-Nachrichtenfenster**. Sie koennen Freitext-Nachrichten nur innerhalb von 24 Stunden nach der letzten Kundennachricht senden. Ausserhalb dieses Fensters verwenden Sie `send_template_message` mit vorab genehmigten Vorlagen.
</Note>

### Agenten-Tools

| Tool                    | Beschreibung                                                                    |
| ----------------------- | ------------------------------------------------------------------------------- |
| `send_message`          | Eine Textnachricht innerhalb des 24-Stunden-Fensters senden                     |
| `send_template_message` | Eine vorab genehmigte Vorlage senden (funktioniert ausserhalb des 24h-Fensters) |
| `send_media`            | Ein Bild, Dokument, Video oder Audio per URL senden                             |
| `get_message_history`   | Konversationsnachrichten abrufen                                                |
| `get_contact_info`      | Kontaktprofilinformationen abrufen                                              |
| `mark_as_read`          | Lesebestaetigungen fuer eine Nachricht senden                                   |

***

## Instagram DM

Instagram Direct Messages werden ueber Metas Graph API mit demselben OAuth-Flow wie WhatsApp aufgerufen.

### Einrichtung

<Steps>
  <Step title="Facebook-Seite verbinden">
    Ihr Instagram Business-Konto muss mit einer Facebook-Seite verknuepft sein.
  </Step>

  <Step title="Integration hinzufuegen">
    Gehen Sie zu **Integrationen** → **Integration hinzufuegen** → waehlen Sie **Instagram**.
  </Step>

  <Step title="OAuth">
    Klicken Sie auf "Mit Meta verbinden" und autorisieren Sie den Zugriff auf Ihr Instagram-Konto.
  </Step>

  <Step title="Konfigurieren">
    Geben Sie Ihr App-Geheimnis und Ihr Verifizierungs-Token ein.
  </Step>
</Steps>

### Agenten-Tools

| Tool                  | Beschreibung                                            |
| --------------------- | ------------------------------------------------------- |
| `send_message`        | Eine Direktnachricht an einen Instagram-Benutzer senden |
| `send_media`          | Einen Medienanhang per DM senden                        |
| `get_message_history` | DM-Thread-Nachrichten abrufen                           |
| `get_profile`         | Oeffentliche Instagram-Profilinformationen abrufen      |
| `get_comments`        | Kommentare zu einem bestimmten Beitrag abrufen          |
| `reply_to_comment`    | Eine verschachtelte Antwort auf einen Kommentar posten  |

***

## Facebook Messenger

Facebook Messenger verbindet sich ueber Ihre Facebook-Seite. Derselbe Meta OAuth-Flow wie WhatsApp und Instagram.

### Einrichtung

<Steps>
  <Step title="Facebook-Seite">
    Sie benoetigen eine Facebook-Seite, die mit Ihrem Meta Business-Konto verknuepft ist.
  </Step>

  <Step title="Integration hinzufuegen">
    Gehen Sie zu **Integrationen** → **Integration hinzufuegen** → waehlen Sie **Facebook Messenger**.
  </Step>

  <Step title="OAuth">
    Klicken Sie auf "Mit Meta verbinden" und autorisieren Sie den Zugriff auf Ihre Seite.
  </Step>

  <Step title="Konfigurieren">
    Geben Sie Ihr App-Geheimnis und Ihr Verifizierungs-Token ein.
  </Step>
</Steps>

### Agenten-Tools

| Tool                    | Beschreibung                                                            |
| ----------------------- | ----------------------------------------------------------------------- |
| `send_message`          | Eine Textnachricht an einen Facebook-Benutzer senden                    |
| `send_template_message` | Eine strukturierte Vorlage senden (Schaltflaechen, Generisch, Quittung) |
| `send_media`            | Ein Bild, Video, Audio oder eine Datei senden                           |
| `get_message_history`   | Konversationsthread abrufen                                             |
| `get_profile`           | Benutzerprofil anhand der seitenbezogenen ID abrufen                    |
| `send_buttons`          | Schnellantwort-Optionen an den Benutzer senden                          |

***

## Nachrichtenfluss

Unabhaengig vom Messenger ist der Verarbeitungsfluss identisch:

<Steps>
  <Step title="Eingehende Nachricht">
    Die Messenger-Plattform sendet einen Webhook an Revol mit dem Nachrichteninhalt und Absenderinformationen.
  </Step>

  <Step title="An Agenten weiterleiten">
    Revol identifiziert den Kanal, findet den zugewiesenen KI-Agenten und erstellt oder setzt eine Konversationssitzung fort. Derselbe Absender erhaelt immer denselben Konversationsthread.
  </Step>

  <Step title="KI-Verarbeitung">
    Die Nachricht wird durch den Workflow des Agenten verarbeitet — LLM-Knoten, RAG-Wissensdatenbank-Abfrage, Tool-Aufrufe und Bedingungen.
  </Step>

  <Step title="Ausgehende Antwort">
    Die Antwort des Agenten wird ueber dieselbe Messenger-API zurueckgesendet. Der Benutzer sieht die Antwort in seinem Chat.
  </Step>
</Steps>

<Tip>
  Messenger-Nachrichten werden asynchron ueber einen Hintergrund-Job verarbeitet. Dies stellt sicher, dass der Webhook eine schnelle 200-Antwort zurueckgibt und Timeouts sowie Wiederholungen von der Messenger-Plattform verhindert werden.
</Tip>

## Tools in Workflow-Knoten verwenden

Messenger-Tools funktionieren wie jedes andere Agenten-Tool:

1. Verbinden Sie die Integration und verifizieren Sie die Zugangsdaten
2. Im **Tools**-Tab des Agenten sehen Sie die bereitgestellten Tools
3. Fuegen Sie Tools zu **benutzerdefinierten Knoten** im Workflow-Editor hinzu
4. Das LLM entscheidet basierend auf dem Konversationskontext, wann sie verwendet werden

**Beispiel:** Ein Kunde fragt "Senden Sie mir die Broschuere auf WhatsApp". Der Agent verwendet `send_media`, um ein PDF-Dokument zu senden, und bestaetigt dann die Zustellung im Chat.

## Webhook-Sicherheit

| Messenger | Validierung                                                          |
| --------- | -------------------------------------------------------------------- |
| Telegram  | Geheimes Token in der Webhook-URL (SHA-256-Hash des Bot-Tokens)      |
| WhatsApp  | HMAC-SHA256-Signatur (`X-Hub-Signature-256`-Header mit `app_secret`) |
| Instagram | HMAC-SHA256-Signatur (`X-Hub-Signature-256`-Header mit `app_secret`) |
| Facebook  | HMAC-SHA256-Signatur (`X-Hub-Signature-256`-Header mit `app_secret`) |

Alle Messenger-Webhooks sind auf **120 Anfragen pro Minute** pro Kanal ratenbegrenzt.