Webhooks¶

Recevez des événements des dialogues Hotline sous forme de requêtes POST au format JSON pour l'intégration avec vos systèmes.

Capacités¶

Le module Webhooks permet de :

• Suivre les événements du système — création, fermeture et réouverture de dialogues, réception et envoi de messages.
• Traiter les commandes personnalisées — aussi bien les commandes standard /mark, /info, que vos propres /invoice, /user et toutes autres.
• Retourner des réponses aux sujets — les résultats d'exécution des commandes peuvent être affichés directement dans les sujets clients.

Configuration¶

Les Webhooks sont configurés via le bot de configuration @hotlinetg_bot dans le paramètre de connexion WEBHOOKS.

Format de configuration : objet JSON où les clés sont les URL de vos scripts et les valeurs sont des tableaux d'événements à suivre :

Exemple de Configuration JSON¶

{
  "https://someapiserver.com/webhooks/test-hook1": [
    "dialog_created",
    "dialog_reopened", 
    "dialog_closed",
    "message_received",
    "message_sent",
    "message_intercepted"
  ],
  "https://someapiserver.com/webhooks/test-hook2": [
    "/mark", "/info",
    "/invoice", "/client"
  ]
}

Événements Système¶

Notifications automatiques sur les événements de dialogue. Envoyées sans attendre de réponse de votre serveur.

Événements de Dialogue Disponibles¶

Événements de Message Disponibles¶

Scénarios d'Utilisation¶

• Envoi de messages automatiques par temporisation après le début du dialogue
• Surveillance du temps de réponse de l'opérateur aux demandes
• Vérification de la conformité des messages à la politique de l'entreprise
• Collecte de données pour l'analyse externe
• Enregistrement des dialogues pour l'entraînement des modèles d'IA
• Duplication des messages vers la base de données d'entreprise

Exemple de Requête : Réouverture de Dialogue¶

{
  "event_type": "dialog_reopened",
  "timestamp": "2025-10-09 00:24:55",
  "instance_id": "13209946874612345",
  "data": {
    "chat_id": -1002146012345,
    "thread_id": 5602541568,
    "topic_id": 5343,
    "topic_link": "https://t.me/c/2146012345/5343",
    "user_id": 5339212345,
    "frontend_chat_id": 5339212345,
    "frontend_topic_id": null,
    "frontend_topic_link": null,
    "frontend_user_id": 6406751371,
    "chat_type": "private",
    "title": "Some User Name",
    "department": "default"
  },
  "api_key": "pQTngMZLh0NmAh"
}

Exemple de Requête : Message Envoyé¶

{
  "event_type": "message_sent",
  "timestamp": "2025-10-09 00:21:57",
  "instance_id": "132099468746812345",
  "data": {
    "backend_chat_id": -1002146012345,
    "backend_thread_id": 5602541568,
    "backend_message_id": 6171918336,
    "sender_user_id": 5339212345,
    "frontend_user_id": 640675123,
    "frontend_message_id": 3260022784,
    "text": "message test",
    "content_type": "messageText",
    "department": "default",
    "backend_reply_message_id": 0
  },
  "api_key": "pQTngMZLh0NmAh"
}

Commandes Personnalisées¶

Événements sur les appels de commandes par les opérateurs. Votre serveur peut enregistrer l'événement correspondant et retourner une réponse qui sera affichée dans le sujet du dialogue.

• Spécifiez les commandes système standard dans la configuration JSON : /info, /mark, /close
• Définissez vos propres commandes : /invoice, /client, /order
• Retournez le résultat d'exécution sous forme de texte ou JSON si nécessaire

Scénarios d'Utilisation¶

• Extension de /info avec des informations supplémentaires sur les clients provenant d'un autre CRM
• Enregistrement des changements de statut via /mark pour l'analyse
• Création de facture avec la commande /invoice avec retour de lien
• Obtention des données client depuis la base de données par /user
• Automatisation des processus métier par déclencheur de commande

Exemple de Requête : Commande /mark¶

{
  "event_type": "/mark",
  "timestamp": "2025-10-08 20:41:20",
  "instance_id": "132099468746812345",
  "data": {
    "command_data": "deal",
    "chat_id": -1002146012345,
    "topic_id": 5,
    "topic_link": "https://t.me/c/2146012345/5",
    "message_id": 5850,
    "reply_message_id": null,
    "sender_user_id": 123456,
    "user_id": 7890123,
    "frontend_chat_id": 7890123,
    "frontend_thread_id": null
  },
  "api_key": "pQTngMZLh0NmAh"
}

Format de Réponse¶

Votre serveur peut retourner le résultat sous forme de texte brut ou JSON avec des nœuds message ou error.

Exécution réussie :

{
  "message": "Transaction créée : http://internal.domain.com/crm/deals/76238",
  "status": "ok"
}

Erreur d'exécution :

{
  "error": "Utilisateur 12345678 introuvable dans notre base de données"
}

Réponse texte :

Vous pouvez retourner simplement du texte avec support Markdown v2 :

✅ Facture №12345 créée
Total : 1500
Lien : https://intranet.example.com/invoice/12345

Sécurité¶

Toutes les requêtes de Hotline contiennent le champ api_key de la connexion correspondante pour la vérification de l'expéditeur.

• Vérifiez api_key de votre côté
• Configurez le filtrage par adresse IP du serveur proxy Hotline
• Utilisez HTTPS pour l'URL des Webhooks

Scénarios Pratiques¶

Conseils de Débogage¶

1. Utilisez des services pour tester les Webhooks : postman.com, requestbin.com
2. Enregistrez toutes les requêtes entrantes sur votre serveur
3. Retournez le statut de réponse HTTP correct (devrait être 200 OK)
4. Surveillez le délai d'expiration — la réponse devrait arriver rapidement (recommandé jusqu'à 3 secondes)
5. Gérez les erreurs avec élégance et retournez des messages compréhensibles

Limitations¶

• Délai d'expiration de réponse de commande — recommandé pas plus de 3 secondes
• Taille de réponse — jusqu'à 4096 caractères (limitation Telegram)
• Tentatives de nouvelle tentative — si votre serveur n'est pas disponible, la requête peut être réessayée
• Limites de taux — avec un flux d'événements important, considérez les capacités de votre serveur

Support¶

Pour toute question sur la configuration des webhooks, la connexion d'abonnement payant, contactez le service d'assistance @hotlinetg_support