Développement de bots

Référence de la Bot API

Toutes les méthodes acceptées par la Bot API HTTP de Pabal, les objets échangés et les erreurs, sans exception. Compatible avec la Bot API de Telegram.

La Bot API HTTP de Pabal utilise le même format d'adresse, de requêtes, de réponses et d'erreurs que la Bot API de Telegram. Cette page ne décrit que ce que Pabal accepte réellement. Une méthode qui n'y figure pas renvoie 404 Not Found: method not found. Si vous débutez, commencez par le tutoriel de création de bot.

Envoyer une requête

https://pabal.me/bot<jeton>/<méthode>

• Méthode HTTP : GET et POST fonctionnent tous les deux.
• Quatre façons d'envoyer les paramètres : chaîne de requête (?chat_id=1&text=hi), application/x-www-form-urlencoded, application/json, et multipart/form-data pour envoyer des fichiers. Vous pouvez les combiner.
• Les paramètres de type objet (reply_markup, commands, allowed_updates) se passent tels quels (objet ou tableau) dans un corps JSON, et sous forme de chaîne JSON dans un formulaire ou une chaîne de requête.
• Les noms de méthode ne tiennent pas compte de la casse (sendMessage = sendmessage).
• La taille du corps est limitée à 12 Mo (au-delà : 413).
• Le téléchargement de fichiers se fait à part, via https://pabal.me/file/bot<jeton>/<file_path> (getFile).

Réponses et erreurs

La réponse est toujours du JSON. En cas de succès : HTTP 200 et result ; en cas d'échec : un error_code égal au statut HTTP et une description lisible par un humain.

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

Pabal n'impose pas encore de limite de débit (429 Too Many Requests), mais cela pourrait venir : prévoyez dès maintenant qu'en cas de 429, votre code attende parameters.retry_after secondes avant de renvoyer la requête.

Recevoir les mises à jour

Utilisez l'une des deux méthodes. Il est impossible d'utiliser les deux en même temps.

getUpdates

POST/bot<jeton>/getUpdates

Récupère les mises à jour en attente (long polling). Si un webhook est configuré : 409.

Renvoie : Array of Update

setWebhook

POST/bot<jeton>/setWebhook

Reçoit les mises à jour sur une adresse HTTPS. Tous les détails sont dans la page Webhooks.

Renvoie : True

deleteWebhook

POST/bot<jeton>/deleteWebhook

Supprime le webhook et revient à getUpdates. Réussit même s'il n'y a pas de webhook.

Renvoie : True

getWebhookInfo

GET/bot<jeton>/getWebhookInfo

État du webhook. Aucun paramètre. S'il n'y a pas de webhook, url est une chaîne vide.

Renvoie : WebhookInfo

Méthodes

getMe

GET/bot<jeton>/getMe

Sert à vérifier que le jeton est correct. Aucun paramètre.

Renvoie : User — pour un bot, s'y ajoutent can_join_groups (true), can_read_all_group_messages (true), supports_inline_queries (false), can_connect_to_business (false) et has_main_web_app (false).

sendMessage

POST/bot<jeton>/sendMessage

Renvoie : le Message envoyé

Pour écrire à une personne, il faut que celle-ci ait parlé au bot la première (403 Forbidden: bot can't initiate conversation with a user). Pour écrire dans un groupe, le bot doit être membre de ce groupe.

sendPhoto

POST/bot<jeton>/sendPhoto

Renvoie : le Message envoyé (avec un nouveau file_id dans photo)

editMessageText

POST/bot<jeton>/editMessageText

Renvoie : le Message modifié. La modification apparaît aussitôt dans l'application ; un message modifié par une personne arrive au bot sous forme d'edited_message.

Si le texte et les boutons sont identiques à avant : 400 Bad Request: message is not modified: … ; si vous tentez de modifier le message de quelqu'un d'autre : 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<jeton>/editMessageCaption

Paramètres : chat_id, message_id, caption (0 à 1 024 caractères ; sans ce paramètre, la légende est supprimée), reply_markup. Renvoie : le Message modifié.

editMessageReplyMarkup

POST/bot<jeton>/editMessageReplyMarkup

Change seulement les boutons, sans toucher au texte. Paramètres : chat_id, message_id, reply_markup (sans ce paramètre, les boutons sont supprimés). Renvoie : le Message modifié.

deleteMessage

POST/bot<jeton>/deleteMessage

Paramètres : chat_id, message_id. Supprime le message des deux côtés de la conversation. Si le message n'existe pas : 400 Bad Request: message to delete not found. Renvoie : True.

answerCallbackQuery

POST/bot<jeton>/answerCallbackQuery

Répond au bouton sur lequel une personne a appuyé (CallbackQuery). On ne peut répondre que dans les 10 secondes, et une seule fois.

Renvoie : True. Trop tard ou déjà répondu : 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<jeton>/sendChatAction

Acceptée par souci de compatibilité, elle renvoie True, mais n'affiche pas encore « en train d'écrire… » dans l'application.

getChat

GET/bot<jeton>/getChat?chat_id=…

Paramètre : chat_id (nombre). Pour une personne, cette personne ; pour un groupe, uniquement un groupe dont le bot est membre. Renvoie : Chat. Inexistant ou non visible : 400 Bad Request: chat not found.

getFile

GET/bot<jeton>/getFile?file_id=…

Obtient le chemin de téléchargement à partir du file_id d'une photo reçue. Renvoie : File. Téléchargez ensuite à cette adresse :

https://pabal.me/file/bot<jeton>/<file_path>

Le file_id vaut aussi droit de récupérer cette photo. Valeur incorrecte : 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<jeton>/setMyCommands

Renvoie : True. Si les commandes ne respectent pas les règles : 400 Bad Request: BOT_COMMAND_INVALID.

getMyCommands

GET/bot<jeton>/getMyCommands

Paramètre : language_code (facultatif). Renvoie : Array of BotCommand.

deleteMyCommands

POST/bot<jeton>/deleteMyCommands

Paramètre : language_code (facultatif). Vide la liste correspondante. Renvoie : True.

logOut · close

Chez Telegram, ces méthodes servent à migrer vers un serveur Bot API local. Pabal n'ayant nulle part où migrer, il les accepte simplement et renvoie True. Pour invalider un jeton, utilisez /revoke auprès de BotFather.

Objets

La mention facultatif à côté d'un champ signifie qu'il peut être absent. Les autres champs de Telegram qui ne figurent pas ici ne sont pas envoyés par Pabal.

Update

Une nouveauté. Contient update_id et un seul des trois champs ci-dessous.

User

Chat

Message

MessageEntity

Le serveur les détecte et les ajoute automatiquement à partir du texte. Les entités de mise en forme comme le gras ou l'italique n'existent pas encore.

PhotoSize

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard : Array of Array of InlineKeyboardButton — le tableau externe contient les rangées, chaque tableau interne les boutons d'une rangée. Au maximum 100 rangées et 100 boutons par message.

InlineKeyboardButton

Les autres types, comme switch_inline_query, web_app, login_url ou pay, n'existent pas encore (400).

ReplyKeyboardMarkup

KeyboardButton

Une simple chaîne, ou un objet avec text et les champs facultatifs request_contact (envoyer mon contact) et request_location (envoyer ma position), de type Boolean.

ReplyKeyboardRemove

{"remove_keyboard": true} — masque le pavé de boutons. selective facultatif.

ForceReply

{"force_reply": true} — l'application ouvre le champ de saisie en mode réponse à ce message. selective et input_field_placeholder facultatifs.

BotCommand

WebhookInfo

Différences avec la Bot API de Telegram

• Types de mises à jour : seuls message, edited_message et callback_query arrivent. Pas de publications de canal, de requêtes inline, de paiements, de sondages, de changements de membres (my_chat_member), etc.
• Mise en forme : parse_mode et entities sont ignorés et le texte est envoyé tel quel. Seuls les commandes, mentions, URL et hashtags sont mis en évidence automatiquement.
• Types de conversation : 1:1 et groupes simples uniquement. Pas de canaux, de supergroupes ni de sujets de forum.
• Médias : photos uniquement. Pas de documents, vidéos, audio, stickers ni albums, et pas d'envoi par URL.
• Bots dans les groupes : il n'y a pas de mode confidentialité, le bot reçoit donc tous les messages du groupe.
• File d'attente : les mises à jour non récupérées sont gardées en mémoire, jusqu'aux 1 000 plus récentes par bot, et perdues au redémarrage du serveur (Telegram les conserve 24 heures).
• Webhooks : envoi d'une requête à la fois, dans l'ordre (max_connections est seulement conservé), pas de certificats auto-signés, aucune restriction de port.
• ID : les ID d'utilisateur, de message et de fichier n'ont de sens que sur ce serveur. Comme il n'y a ni canaux ni supergroupes, il n'existe pas non plus d'ID de la forme -100….
• Méthodes absentes : celles qui ne figurent pas dans la liste ci-dessus (forwardMessage, copyMessage, sendDocument, sendPoll, getChatMember, banChatMember, answerInlineQuery …) renvoient 404 Not Found: method not found.