API/Webhooks

• Discord
• Telegram

Discord

Discord permet la création de Webhooks pour permettre d'interagir avec un serveur/canal avec des requêtes HTTPs. Une utilisation commune et simple de ces Webhooks est d'envoyer des messages automatisés à partir d'un autre système. On peut penser ici à un système de surveillance qui fera parvenir des alertes à un canal Discord auquel plusieurs techniciens pourraient souscrire pour réagir à différentes situations telles que des pannes réseau ou des évènements de sécurité.

Création du Webhook

Création d'un serveur Discord

Un API/Webhook doit évidemment être lié à un canal, il faut donc tout d'abord créer un serveur. Un serveur peut contenir plusieurs canaux et chaque clé de Webhook est associé à un canal comme il sera abordé plus tard. Ceci peut être utile pour trier les alertes par systèmes ou catégories. Créez tout d'abord un serveur.

Pour avoir un serveur avec le moins d'options préconfigurées, sélectionnez "Create My Own" et créez le "pour un club ou une communauté". Vous pourrez ajouter vos collègues ou tout autre acteur ayant besoin de consulter ces alertes.

Une fois le modèle de canal sélectionné, il vous sera demandé de nommer votre serveur. Ce nom est un nom d'affichage seulement et n'a donc pas besoin d'être unique sur toute la plate-forme. Le code pour le Webhook sera unique et lié à un identifiant unique situé derrière le serveur.

Configuration de la clé d'API permettant l'interaction avec le Webhook

À fin de permettre l'interaction avec le serveur et plus spécifiquement un canal, il faudra créer une intégration pour votre serveur. Dirigez-vous dans "Server Settings" puis dans ""

Le menu d'intégrations vous permettera de créer un nouveau Webhook. Un nom aléatoire lui sera accordé mais celui-ci peut être changé pour accomoder vos besoins, qu'il s'agisse de trier par système ou par catégorie d'alertes. Plusieurs Webhooks peuvent être créés et chaque Webhook peut être assigné au canal de votre choix. Plusieurs Webhooks peuvent être assignés à chaque canal dans votre serveur.

En cliquant sur le Webhook créé, vous pourrezl e renommer et sélectionner le canal auquel vous désirez l'assigner.

En copiant l'URL du Webhook, vous serez dorénavant prêts à envoyer des messages dans votre canal à partir de requêtes HTTPS.

Utilisation du Webhook

Le concept d'un Webhook plutôt qu'un API est que l'on présente tout simplement l'information au serveur et on le laisse l'interpréter sans plus d'interaction. Un API est plus souvent utilisé pour demander une information. Chaque plate-forme nécessitera une formule différente pour faire parvenir un message au serveur.

Envoi d'un message dans un canal

Pour envoyer un message dans un canal, il faudra envoyer un objet JSON comprenant le contenu du message par méthode POST au serveur. Ceci peut être facilement effectué à l'aide de la commande cURL.

Le contenu de l'object peut être aussi simple que le suivant :

{"content": "message"}

La structure de la commande cURL devra mentionner le format de réponse que l'on peut interpréter, le type de contenu qui sera envoyé au serveur ainsi que les données contenues dans le POST de la requête.

curl -i -H "Accept: application/json" -H "Content-Type:application/json" -X POST -d '{"content": "message"}' https://discord.com/api/webhooks/[server ID]/[api key]

Les options de la commande peuvent être décortiquées comme tel :

• -i permet d'afficher les en-têtes lors de la réception de la réponse
• -H permet d'envoyer une option d'en-tête avec notre requête
  • La première option mentionne le format de contenu que l'on acceptera
  • La deuxième option indique au serveur le format de données qu'on lui acheminera
• -X stipule la méthode de transfert de données, dans ce cas-ci, le contenu du message sera acheminé par POST
• -d contient les données qui seront envoyées au serveur. Dans ce cas-ci, il s'agit de l'objet JSON contenant notre message.

L'URL contacté par la commande cURL est le lien qui est copié lorsque l'on clique sur "Copy Webhook URL".

Telegram

Pour utiliser des Webhooks avec Telegram, il est nécessaire de créer un Bot. Celui-ci nous permet une panoplie d'interactions avec leur API mais il nous permet entre autres d'envoyer de simples requêtes Webhooks pour automatiser l'envoi de messages dans une discussion ou dans un groupe.

Création d'un bot

Pour créer un bot sous Telegram, démarrez une conversation avec @BotFather. Ce bot-ci est celui qui est utilisé pour gérer tout "bot" ou "API" disponible sous Telegram. Cliquez sur "Start" pour démarrer votre interaction

La commande "/newbot" vous permettera de créer une clé d'API qui vous permettera d'interagir avec une conversation ou un groupe Telegram comme par exemple pour envoyer un message.

Il vous sera ensuite demandé de nommer votre "bot". Le nom de celui-ci doit être unique sur toute la plate-forme et doit se terminer par "bot". Il est possible qu'il soit difficile de trouver un nom disponible mais peu importe ce nom, le nom d'affichage du bot pourra être modifié par un alias/nom d'affichage dans une conversation.

Lorsque votre bot sera créé, vous pourrez consulter son état avec une requête HTTPS à l'URL "https://api.telegrma.org/bot[votre token d'API]/getUpdates".

Création d'un canal/conversation

De façon générale, un groupe ou une conversation sera créé auquel le bot sera joint. S'il s'agit d'un groupe, il serait possible d'ajouter tous les membres de votre équipe d'administrateurs de systèmes pour que vos équipiers puissent consulter les alertes.

Cliquez sur l'icône de crayon pour composer un nouveau message. Il vous sera offert de composer un message privé, créer un groupe ou créer un canal. Un bot peut interagir avec tous ces types de conversations. Dans l'exemple suivant, créons un groupe.

Il vous sera ensuite demandé d'ajouter des membres à votre groupe. Vous devrez saisir le nom complet du bot pour qu'il s'affiche dans les suggestions. Vous pourrez ensuite sélectionner le bot et l'ajouter comme membre du groupe.

Vous pourrez ensuite confirmer la création de votre groupe à l'aide de la fèche en bas à droite de la page.

Félicitations! Vous avez dorénavant un groupe dans lequel votre bot pourra dorénavant interagir.

Utilisation du Webhook

Récupérer l'état du bot

Tout comme vu précédemment, la requête /getUpdates sur l'URL de notre bot nous permet de récupérer son état et ses nouvelles telles que les groupes auxquels notre bot a été ajouté et les messages que le bot a pu observer. Dans la capture suivante, on peut observer que le bot a observé son ajout au chat ID "-4729377648".

Nous pourrions ensuite "tagger" notre bot dans un message et on observerait ensuite dans l'objet JSON qui nous est retourné que note bot a vu notre message passer.

Envoyer un message

Tout comme pour Discord, lorsque nous avons l'identifiant de la discussion ainsi que la clé D'API de notre bot, nous pourrons dorénavant interagir avec ce groupe en soumettant des requêtes HTTP à l'URL d'API de Telegram!

Pour envoyer un message via un bot Telegram, il suffit de soumettre une requête HTTP par méthode POST et de mentionner les variables POST "chat_id" et "text"

La requête cURL suivante serait donc suffisante pour envoyer un message :

curl -s -X POST https://api.telegram.org/bot[API KEY]/sendMessage -F chat_id='[identifiant du chat]' -F text="[message à envoyer]"

Les options de la commande peuvent être décortiquées comme tel :

• -s permet d'exécuter silencieusement la requête
• -X stipule la méthode de transfert de données, dans ce cas-ci, le contenu du message sera acheminé par POST
• -F spécifie une variable de formulaire soumise par POST ainsi que sa valeur associée
  • chat_id=[identifiant du chat] spécifie à Telegram dans quel canal envoyer le message
  • text=[message] spécifie à Telegram le contenu du message à envoyer

L'URL contacté par la commande cURL est composée de "https://api.telegram.org/bot" suivi de la clé d'API que BotFather vous a spécifié et se termine par /sendMessage dans ce cas pour la commande d'envoyer un message. Nous avons aussi utilisé précédemment /getUpdates pour récupérer l'état du bot.