API Topics (v1)¶

API REST pour l'intégration programmatique de Hotline CRM avec des systèmes externes.

Obtenez des informations sur les dialogues et envoyez des messages aux sujets du groupe backend.

Fonctionnalité payante

L'utilisation des Webhooks et de l'API REST n'est disponible que pour les utilisateurs premium Hotline. Pour acheter la version payante du système, contactez notre service d'assistance.

Capacités de l'API¶

Obtenir des informations sur le sujet — données du dialogue, statut, informations sur l'utilisateur ou le chat
Envoyer des messages aux sujets — envoyer des messages aux sujets pour les opérateurs par user_id spécifié

Point d'Accès¶

https://n8n.production.hotline.tg/webhook/topic_action

Exigences :

	Description
Méthode de requête	`POST`
En-tête HTTP	`X-API-KEY` avec le jeton d'accès du propriétaire des connexions (délivré par le service d'assistance)
Corps :	JSON avec les champs `instance` et `api_key` de la connexion spécifique (obtenus dans le bot de configuration)

Méthode : Obtenir les Informations du Sujet¶

La méthode info_by_topic renvoie des informations complètes sur le dialogue par identifiants de sujet.

Exemple de requête POST

{
  "action": "info_by_topic",
  "group_id": "2101424779",
  "topic_id": 5343,
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Extraction d'ID à partir du lien

Lien du sujet : https://t.me/c/2101424779/5343
→ group_id : 2101424779
→ topic_id : 5343

Exemple de réponse pour un sujet utilisateur

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5343,

  "frontend_type": "private",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "chat_id": -1002101424779,
  "thread_id": 5602541568,

  "topic_last_date": "2025-10-09 00:24:55",
  "topic_status": "user_answered",
  "topic_title": "John Doe",

  "user_id": 987654321,
  "user_name": "John Doe",
  "user_first_name": "John",
  "user_last_name": "Doe",
  "user_username": "john1991",
  "user_lang": "en",
  "user_phone": "+12125550123"
}

Exemple de réponse pour un sujet de chat

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5344,

  "frontend_type": "group",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "frontend_chat_id": -1001234567890,

  "topic_last_date": "2025-10-09 00:30:00",
  "topic_status": "support_answered",
  "topic_title": "Somebiz Proposal Chat"
}

Connexions multiples

Si plusieurs frontends sont liés au système, vous pouvez utiliser n'importe lequel d'entre eux pour obtenir des informations
La réponse indiquera à quelle connexion appartient le sujet spécifique

Méthode : Envoyer un Message au Sujet¶

La méthode incoming_in_topic crée un message pour les opérateurs dans le sujet avec le dialogue de l'utilisateur spécifié.

Exemple de requête

{
  "action": "incoming_in_topic",
  "user_id": 987654321,
  "message": "Statut de l'utilisateur modifié : TRANSACTION CONFIRMÉE",
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Exemple de réponse

{
  "result": "message_sent",
  "topic_link": "https://t.me/c/2101424779/5343",
  "message": "Statut de l'utilisateur modifié : TRANSACTION CONFIRMÉE",
  "chat_id": "-1002101424779",
  "thread_id": 5602541568
}

Recommandations¶

Stockez x-api-key et api_key dans un endroit sécurisé (variables d'environnement, secrets)
Utilisez HTTPS pour toutes les requêtes API
Enregistrez toutes les requêtes API pour l'audit
Implémentez une logique de nouvelle tentative avec backoff exponentiel
Définissez un délai d'expiration de requête d'au moins 10 secondes
Considérez la limitation du taux de fréquence lors d'opérations en masse
Taille maximale du message — 4096 caractères (limitation Telegram)

Obtention de l'Accès¶

Pour obtenir le jeton x-api-key et connecter l'API Topics :

Écrivez au service d'assistance
Décrivez brièvement votre scénario d'utilisation de l'API
Recevez le jeton d'accès x-api-key et une consultation technique