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 sur l'ensemble des requêtes, mais les méthodes vocales ont une limite horaire et peuvent renvoyer 429 Too Many Requests: retry after N (Appels vocaux). Prévoyez 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 écrit au bot en premier (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)

sendDocument

POST/bot<jeton>/sendDocument

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

Le format (mime_type) est déduit de l'extension du nom de fichier. Un fichier envoyé depuis une application peut atteindre 2 Go, mais ce qu'un bot téléverse ou télécharge en HTTP est limité à 20 Mo, comme chez Telegram.

sendLocation

POST/bot<jeton>/sendLocation

Renvoie : le Message envoyé (avec une Location dans location)

sendVenue

POST/bot<jeton>/sendVenue

Renvoie : le Message envoyé (avec un Venue dans venue, et le même point dans location)

Sans title ou address : 400 Bad Request: title and address are required.

sendContact

POST/bot<jeton>/sendContact

Renvoie : le Message envoyé (avec un Contact dans contact)

Une fiche de contact envoyée par un bot ne porte jamais de user_id, même quand le numéro appartient à un compte Pabal — un bot n'a pas de contacts, et renseigner ce champ lui permettrait de découvrir à qui appartient un numéro en envoyant une fiche par numéro. Sans phone_number ou first_name : 400 Bad Request: phone_number and first_name are required.

editMessageLiveLocation

POST/bot<jeton>/editMessageLiveLocation

Renvoie : le Message modifié

Une position en direct déjà terminée — arrêtée, ou dont la durée est écoulée — ne peut plus être déplacée ni ranimée en prolongeant sa durée (400 Bad Request: message can't be edited). Il en va de même pour un message qui n'est pas une position en direct.

Un déplacement effectué moins de 10 secondes après le dernier déplacement pris en compte, ou de moins de 10 m, est laissé de côté sans être enregistré. L'arrêt et un changement de durée ou de rayon d'alerte sont toujours pris en compte. Quand un déplacement est laissé de côté, le Message renvoyé montre la dernière position prise en compte : vous pouvez donc envoyer des déplacements toutes les quelques secondes.

stopMessageLiveLocation

POST/bot<jeton>/stopMessageLiveLocation

Paramètres : chat_id, message_id, reply_markup (facultatif). Arrête la position en direct là où elle se trouvait en dernier. Sa durée de partage est ramenée au temps réellement écoulé, si bien que toutes les applications l'affichent comme terminée. Si elle est déjà arrêtée ou terminée : 400 Bad Request: message is not modified: …. Renvoie : le Message modifié.

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. S'il est trop tard ou si une réponse a déjà été donnée : 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 autorisation 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 le menu ne respecte pas les règles, rien n'est enregistré : 400 Bad Request: BOT_COMMAND_INVALID (une commande), BOT_COMMAND_DESCRIPTION_INVALID (une description vide ou de plus de 256 caractères), BOT_COMMANDS_TOO_MUCH (plus de 100).

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 mise à jour. Contient update_id et un seul des 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

Document

Location

Une position en direct partagée par une personne arrive de nouveau sous forme d'edited_message chaque fois que le serveur prend en compte un déplacement.

Venue

Contact

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

Appels vocaux

Ces méthodes n'existent que dans Pabal. Un bot vocal est un bot que l'on appelle depuis l'application et dont les appels sont pris par un modèle vocal d'IA ; ces méthodes servent à régler ce modèle et à gérer les appels. Ce qui doit être activé, la façon d'activer et des exemples se trouvent dans le guide Bots vocaux. Les méthodes existent aussi sur un serveur où la voix est désactivée, ce qui permet de lire les réglages, mais un bot dont la voix est désactivée ou que l'opérateur n'a pas encore autorisé ne peut modifier ses réglages que pour désactiver ou effacer (403 VOICE_NOT_AVAILABLE).

setVoiceCallSettings

POST/bot<jeton>/setVoiceCallSettings

Modifie les réglages vocaux du bot. Seul ce que vous envoyez change ; le serveur vérifie l'ensemble puis écrit tout d'un coup, ou refuse tout. 30 fois par heure et par bot (en comptant @BotFather).

Renvoie : True

getVoiceCallSettings

GET/bot<jeton>/getVoiceCallSettings

Sans paramètre. Les réglages actuels ; si le bot peut prendre des appels en ce moment (available, unavailable_reason) ; les limites du serveur ; la liste des voix et des langues ; où iraient les requêtes d'outil et la transcription ; l'état de la clé propre, du mode flux et des serveurs MCP. Les clés et les secrets n'apparaissent jamais, seulement leurs empreintes. Les champs sont décrits dans Bots vocaux — Voir les réglages actuels.

Renvoie : VoiceCallSettings (objet)

endVoiceCall

POST/bot<jeton>/endVoiceCall

Renvoie : True. Si ce n'est pas un appel en cours de ce bot : 400 VOICE_CALL_NOT_FOUND.

sendVoiceCallContext

POST/bot<jeton>/sendVoiceCallContext

Renvoie : True. Avant la connexion : VOICE_CALL_NOT_ACTIVE ; appel en mode flux : VOICE_CONTEXT_NOT_SUPPORTED ; trop long : VOICE_CONTEXT_TOO_LONG ; plus de 10 par minute et par appel : 429.

getVoiceCallUsage

GET/bot<jeton>/getVoiceCallUsage

Renvoie : period, from_date, to_date, calls, seconds, missed, refused (busy·budget·unavailable), platform_seconds, own_key_seconds, remaining_seconds_today (bot·owner), et outbound (today·limits) pour un bot qui a déjà activé les appels — les limites de dates suivent le fuseau horaire du serveur

startVoiceCall

POST/bot<jeton>/startVoiceCall

Le bot appelle une personne. Seul un bot dont le propriétaire a activé cette fonction dans @BotFather et que l'opérateur a examiné peut appeler, et seulement les personnes qui l'ont autorisé. Les réponses et l'examen des demandes sont décrits dans Bots vocaux — Appeler.

Renvoie : {"voice_call_id": "…"} — cela veut seulement dire que la demande est prise en compte ; si cela a sonné et si la personne a répondu arrive dans des mises à jour voice_call. Refus : 403 VOICE_OUTBOUND_OFF: <raison>, 403 USER_UNAVAILABLE (toujours le même corps), 429, 503 VOICE_UNAVAILABLE. Impossible à appeler depuis une réponse de webhook.

answerVoiceCallToolQuery

POST/bot<jeton>/answerVoiceCallToolQuery

Renvoie : True. La première réponse est la dernière. Trop tard : 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable ; identifiant inconnu : TOOL_QUERY_ID_INVALID ; réponse refusée : TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <code>. À un POST de requête d'outil reçu par webhook, on peut aussi répondre dans le corps de la réponse.

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<jeton>/setVoiceCallApiKey

Renvoie : True — la clé n'est conservée qu'après avoir passé une session de test de la passerelle. API_KEY_INVALID, API_KEY_NO_REALTIME_ACCESS, 503 API_KEY_CHECK_UNAVAILABLE (clé non conservée), 403 VOICE_OWN_KEY_NOT_AVAILABLE (ce serveur n'accepte pas de clé propre). deleteVoiceCallApiKey ne prend aucun paramètre et renvoie toujours True. Aucune des deux méthodes ne peut être appelée par bots.sendCustomRequest, et setVoiceCallApiKey ne peut pas non plus l'être dans une réponse de webhook. Détails dans Votre propre clé de modèle.

Méthodes des serveurs MCP

auth et les secrets s'envoient uniquement dans le corps de la requête. Sur un serveur sans MCP : 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server. Détails dans Bots vocaux — Serveurs MCP.

Recevoir les mises à jour vocales

voice_call, voice_call_tool_query et voice_call_transcript n'arrivent que si vous les demandez par leur nom — indiquez-les dans le allowed_updates de getUpdates ou de setWebhook. Elles n'arrivent pas avec une liste vide, et ce qui s'est produit avant votre demande n'est pas mis de côté. Une requête d'outil arrive par un POST séparé s'il y a un webhook, ou en tête du prochain getUpdates si getUpdates a été appelé dans les 15 dernières secondes.

VoiceCall

VoiceCall n'a aucun champ indiquant si l'appelant a choisi « Garder la conversation ». C'est voulu — ce texte appartient à l'appelant et ne va pas au bot. C'est pourquoi, sur un serveur où « Garder la conversation » est activé, le ended de tous les appels hors mode flux attend le même temps, et le numéro du message qui suit le message d'appel est, pour tous les appels, supérieur d'au moins 31 à celui du message d'appel (les numéros sont réservés à l'avance).

VoiceCallToolQuery

VoiceCallTranscript

N'arrive que par la Bot API HTTP. La transcription complète de l'appel se trouve dans le champ transcript du voice_call de fin.

Mode flux (mode=stream)

En mode flux, l'audio de l'appel va au serveur du propriétaire du bot au lieu du modèle d'IA de Pabal. Si vous envoyez à setVoiceCallSettings mode=stream, stream_url=wss://… et stream_secret=… (de 32 à 128 caractères ASCII imprimables, uniquement dans le corps de la requête), la passerelle de Pabal essaie une fois de se connecter à cette adresse (la sonde) et, si elle y parvient, le mode s'active. Il faut les conditions du propriétaire de bot et une version de l'application qui contient l'écran de confirmation du mode flux. Réglage, résultats de la sonde et exemples : Bots vocaux — Mode flux.

• Connexion : TLS 1.2 ou plus, certificat public correspondant au nom de l'URL, sous-protocole pabal.voice.v1, pas de compression, 64 Kio par message et 4 Kio par texte au plus, pas de redirection.
• Signature : X-Pabal-Voice-Signature: t=…,nonce=…,call=…,v1=HMAC-SHA256(stream_secret, "pabal-voice-stream/1\n<t>\n<nonce>\n<call>\n<host>\n<path?query>"). host est l'hôte de l'URL que vous avez donnée. Vérifiez les 300 secondes, le nonce à usage unique, la comparaison octet par octet, et que start.call_id est égal à call (détails).
• Audio : les messages texte sont des événements JSON, les binaires du PCM16 little-endian, mono, 24 kHz. La voix de l'appelant arrive par blocs de 20 ms (960 octets).
• Pabal → bot : start (une fois) · live (l'annonce sur l'IA est finie) · audio · mark · cleared · buffer_full · stop (→ fermeture 1000).
• Bot → Pabal : ready (dans les 3 secondes après start, en tout premier) · audio (après live) · clear · mark · hangup.

La forme de chaque message est donnée dans le tableau de Bots vocaux — Spécification.

Erreurs des méthodes vocales

Les codes d'erreur des méthodes vocales et leur signification sont regroupés dans Bots vocaux — Erreurs. Un 403 prend la forme Forbidden: <code>: <description> (VOICE_RULES_NOT_ACCEPTED, VOICE_NOT_AVAILABLE, VOICE_SUSPENDED, VOICE_OWNER_TERMS_NOT_ACCEPTED, VOICE_OWN_KEY_NOT_AVAILABLE, VOICE_STREAM_NOT_AVAILABLE, VOICE_OUTBOUND_OFF) ; USER_UNAVAILABLE est toujours exactement Forbidden: USER_UNAVAILABLE, sans description. Un dépassement de la limite horaire donne 429 avec retry_after.

Différences avec la Bot API de Telegram

• Types de mises à jour : seuls message, edited_message, callback_query et les types propres aux bots vocaux de Pabal (voice_call, voice_call_tool_query, voice_call_transcript) 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, fichiers (sendDocument), positions, positions en direct, lieux et contacts uniquement. Pas de messages vidéo ou vocaux qui se lisent dans l'application, pas de stickers, d'albums (sendMediaGroup) ni de sondages, et pas d'envoi par URL. Le téléversement et le téléchargement en HTTP sont limités à 20 Mo.
• Positions : l'alerte de proximité d'une position en direct (proximity_alert_radius) est seulement enregistrée, jamais envoyée. Les déplacements de moins de 10 secondes ou de 10 m sont laissés de côté sans être pris en compte, et une fiche de contact envoyée par un bot ne porte pas de user_id.
• 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, sendVideo, sendPoll, getChatMember, banChatMember, answerInlineQuery …) renvoient 404 Not Found: method not found.