Desarrollo de bots

Referencia de la Bot API

Todos los métodos que acepta la Bot API HTTP de Pabal, los objetos que intercambia y sus errores, sin omitir nada. Compatible con la Bot API de Telegram.

La Bot API HTTP de Pabal usa el mismo formato de direcciones, peticiones, respuestas y errores que la Bot API de Telegram. Este documento recoge solo lo que Pabal acepta de verdad. Los métodos que no aparecen aquí devuelven 404 Not Found: method not found. Si es tu primera vez, empieza por el tutorial para crear un bot.

Enviar peticiones

https://pabal.me/bot<token>/<método>

• Método HTTP: se admiten tanto GET como POST.
• Hay cuatro formas de enviar los parámetros: cadena de consulta (?chat_id=1&text=hi), application/x-www-form-urlencoded, application/json y, cuando subes archivos, multipart/form-data. Se pueden combinar.
• Los parámetros de tipo objeto (reply_markup, commands, allowed_updates) van tal cual, como objeto o array, en un cuerpo JSON, y como cadena JSON en formularios y cadenas de consulta.
• El nombre del método no distingue entre mayúsculas y minúsculas (sendMessage = sendmessage).
• El tamaño del cuerpo puede llegar a 12 MB (por encima, 413).
• La descarga de archivos usa otra dirección: https://pabal.me/file/bot<token>/<file_path> (getFile).

Respuestas y errores

La respuesta siempre es JSON. Si todo va bien, llega un HTTP 200 con result; si falla, llega el estado HTTP correspondiente, un error_code igual a ese estado y una description legible para personas.

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

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

Pabal todavía no aplica un límite de frecuencia al conjunto de las peticiones, pero los métodos de voz tienen un límite por hora y pueden devolver 429 Too Many Requests: retry after N (Llamadas de voz). Prepara tu código para que, si recibe un 429, espere parameters.retry_after segundos antes de volver a enviar.

Recibir actualizaciones

Se usa uno de estos dos modos. No se pueden usar los dos a la vez.

getUpdates

POST/bot<token>/getUpdates

Recoge las actualizaciones pendientes (long polling). Si hay un webhook configurado, 409.

Devuelve: Array of Update

setWebhook

POST/bot<token>/setWebhook

Recibe las actualizaciones en una dirección HTTPS. La explicación detallada está en el documento Webhooks.

Devuelve: True

deleteWebhook

POST/bot<token>/deleteWebhook

Elimina el webhook y vuelve a getUpdates. Tiene éxito aunque no haya webhook.

Devuelve: True

getWebhookInfo

GET/bot<token>/getWebhookInfo

Estado del webhook. Sin parámetros. Si no hay webhook, url es una cadena vacía.

Devuelve: WebhookInfo

Métodos

getMe

GET/bot<token>/getMe

Sirve para comprobar que el token es correcto. Sin parámetros.

Devuelve: User. En el caso de un bot se añaden can_join_groups (true), can_read_all_group_messages (true), supports_inline_queries (false), can_connect_to_business (false) y has_main_web_app (false).

sendMessage

POST/bot<token>/sendMessage

Devuelve: el Message enviado

Para escribir a una persona, esa persona tiene que haber escrito antes al bot (403 Forbidden: bot can't initiate conversation with a user). Para escribir en un grupo, el bot tiene que ser miembro de ese grupo.

sendPhoto

POST/bot<token>/sendPhoto

Devuelve: el Message enviado (con un file_id nuevo en photo)

sendDocument

POST/bot<token>/sendDocument

Devuelve: el Message enviado (con un file_id nuevo en document)

El formato (mime_type) se deduce de la extensión del nombre del archivo. Los archivos enviados desde la aplicación pueden llegar a 2 GB, pero lo que el bot sube y descarga por HTTP tiene un límite de 20 MB, igual que en Telegram.

sendLocation

POST/bot<token>/sendLocation

Devuelve: el Message enviado (con una Location en location)

sendVenue

POST/bot<token>/sendVenue

Devuelve: el Message enviado (con un Venue en venue y el mismo punto en location)

Sin title o address obtienes 400 Bad Request: title and address are required.

sendContact

POST/bot<token>/sendContact

Devuelve: el Message enviado (con un Contact en contact)

Una tarjeta de contacto enviada por un bot nunca lleva user_id, aunque el número pertenezca a una cuenta de Pabal: un bot no tiene contactos, y si se rellenara, el bot podría averiguar de quién es un número enviando una tarjeta por número. Sin phone_number o first_name obtienes 400 Bad Request: phone_number and first_name are required.

editMessageLiveLocation

POST/bot<token>/editMessageLiveLocation

Devuelve: el Message editado

Una ubicación en tiempo real que ya terminó —detenida o con el periodo agotado— no se puede mover ni revivir ampliando su periodo (400 Bad Request: message can't be edited). Lo mismo vale para un mensaje que no es una ubicación en tiempo real.

Un movimiento hecho menos de 10 segundos después del último que se aplicó, o de menos de 10 m, se deja pasar sin guardarlo. Detenerla y cambiar el periodo o el radio de alerta siempre se aplican. Cuando se deja pasar un movimiento, el Message devuelto muestra la última posición aplicada, así que no pasa nada por enviar uno cada pocos segundos.

stopMessageLiveLocation

POST/bot<token>/stopMessageLiveLocation

Parámetros: chat_id, message_id y reply_markup (opcional). Detiene la ubicación en tiempo real donde estaba por última vez. Su periodo se reduce al tiempo que de verdad pasó, así que todas las aplicaciones la muestran como terminada. Si ya estaba detenida o terminada, 400 Bad Request: message is not modified: …. Devuelve: el Message editado.

editMessageText

POST/bot<token>/editMessageText

Devuelve: el Message editado. El cambio se refleja al instante en la aplicación, y los mensajes que edita una persona le llegan al bot como edited_message.

Si el texto y los botones son idénticos a los anteriores, 400 Bad Request: message is not modified: …; si intentas editar un mensaje ajeno, 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<token>/editMessageCaption

Parámetros: chat_id, message_id, caption (de 0 a 1.024 caracteres; si lo omites, se borra el pie) y reply_markup. Devuelve: el Message editado.

editMessageReplyMarkup

POST/bot<token>/editMessageReplyMarkup

Deja el texto como está y cambia solo los botones. Parámetros: chat_id, message_id y reply_markup (si lo omites, se borran los botones). Devuelve: el Message editado.

deleteMessage

POST/bot<token>/deleteMessage

Parámetros: chat_id y message_id. Borra el mensaje para ambas partes del chat. Si el mensaje no existe, 400 Bad Request: message to delete not found. Devuelve: True.

answerCallbackQuery

POST/bot<token>/answerCallbackQuery

Responde a un botón pulsado por una persona (CallbackQuery). Solo se puede responder en menos de 10 segundos y una sola vez.

Devuelve: True. Si es demasiado tarde o ya se respondió, 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<token>/sendChatAction

Se acepta por compatibilidad y devuelve True, pero por ahora la aplicación no muestra «escribiendo…».

getChat

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

Parámetro: chat_id (numérico). Si es una persona, esa persona; si es un grupo, solo los grupos de los que el bot es miembro. Devuelve: Chat. Si no existe o no se puede ver, 400 Bad Request: chat not found.

getFile

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

Obtiene la ruta de descarga de una foto recibida a partir de su file_id. Devuelve: File. Después se descarga desde esta dirección.

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

El file_id es también el derecho a obtener esa foto. Si el valor no es válido, 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

Devuelve: True. Si el menú no cumple las reglas, no se guarda nada: 400 Bad Request: BOT_COMMAND_INVALID (un comando), BOT_COMMAND_DESCRIPTION_INVALID (una descripción vacía o de más de 256 caracteres), BOT_COMMANDS_TOO_MUCH (más de 100).

getMyCommands

GET/bot<token>/getMyCommands

Parámetro: language_code (opcional). Devuelve: Array of BotCommand.

deleteMyCommands

POST/bot<token>/deleteMyCommands

Parámetro: language_code (opcional). Vacía esa lista. Devuelve: True.

logOut · close

En Telegram son métodos que se usan al pasar a un servidor local de la Bot API. En Pabal no hay adónde pasar, así que solo se aceptan y devuelven True. Para invalidar un token, usa /revoke de BotFather.

Objetos

opcional junto a un campo significa que puede no aparecer. Pabal no envía los demás campos de Telegram que no figuran aquí.

Update

Una actualización. Contiene update_id y uno de los campos siguientes.

User

Chat

Message

MessageEntity

El servidor las detecta en el texto y las añade automáticamente. Todavía no hay entidades de formato como negrita o cursiva.

PhotoSize

Document

Location

Una ubicación en tiempo real que comparte una persona vuelve a llegar como edited_message cada vez que el servidor aplica un movimiento.

Venue

Contact

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard: Array of Array of InlineKeyboardButton. El array exterior son las filas y cada array interior, los botones de una fila. Como máximo 100 filas y 100 botones por mensaje.

InlineKeyboardButton

Otros tipos como switch_inline_query, web_app, login_url o pay todavía no existen (400).

ReplyKeyboardMarkup

KeyboardButton

Una cadena, o un objeto con text y los campos opcionales request_contact (enviar mi contacto) y request_location (enviar mi ubicación), de tipo Boolean.

ReplyKeyboardRemove

{"remove_keyboard": true}: oculta el panel de botones. selective es opcional.

ForceReply

{"force_reply": true}: la aplicación abre el campo de texto en modo de respuesta a este mensaje. selective e input_field_placeholder son opcionales.

BotCommand

WebhookInfo

Llamadas de voz

Estos métodos solo existen en Pabal. Un bot de voz es un bot al que se llama desde la aplicación y cuyas llamadas atiende un modelo de voz de IA; con estos métodos se configura ese modelo y se gestionan las llamadas. Lo que tiene que estar activado, cómo activarlo y los ejemplos están en la guía Bots de voz. Los métodos existen también en un servidor con la voz desactivada, así que se pueden leer los ajustes, pero un bot con la voz desactivada o que el operador aún no ha autorizado no puede cambiar sus ajustes salvo para desactivar o borrar (403 VOICE_NOT_AVAILABLE).

setVoiceCallSettings

POST/bot<token>/setVoiceCallSettings

Cambia los ajustes de voz del bot. Solo cambia lo que envías; el servidor lo revisa todo y lo escribe de una vez, o lo rechaza entero. 30 veces por hora por bot (sumando @BotFather).

Devuelve: True

getVoiceCallSettings

GET/bot<token>/getVoiceCallSettings

Sin parámetros. Los ajustes actuales; si el bot puede recibir llamadas ahora (available, unavailable_reason); los límites del servidor; la lista de voces e idiomas; adónde irían las consultas de herramienta y la transcripción; y el estado de la clave propia, el modo stream y los servidores MCP. Las claves y los secretos nunca aparecen, solo sus huellas. Los campos están en Bots de voz — Ver los ajustes actuales.

Devuelve: VoiceCallSettings (objeto)

endVoiceCall

POST/bot<token>/endVoiceCall

Devuelve: True. Si no es una llamada en curso de este bot: 400 VOICE_CALL_NOT_FOUND.

sendVoiceCallContext

POST/bot<token>/sendVoiceCallContext

Devuelve: True. Antes de la conexión: VOICE_CALL_NOT_ACTIVE; llamada en modo stream: VOICE_CONTEXT_NOT_SUPPORTED; demasiado larga: VOICE_CONTEXT_TOO_LONG; más de 10 por minuto en una llamada: 429.

getVoiceCallUsage

GET/bot<token>/getVoiceCallUsage

Devuelve: period, from_date, to_date, calls, seconds, missed, refused (busy·budget·unavailable), platform_seconds, own_key_seconds, remaining_seconds_today (bot·owner) y, en un bot que alguna vez activó las llamadas, outbound (today·limits); los días se cuentan según la zona horaria del servidor

startVoiceCall

POST/bot<token>/startVoiceCall

El bot llama a una persona. Solo puede hacerlo un bot cuyo propietario lo activó en @BotFather y que el operador revisó, y solo a quienes permitieron que ese bot les llame. Las respuestas y cómo se evalúan las peticiones están en Bots de voz — Llamar.

Devuelve: {"voice_call_id": "…"}; solo significa que se recibió la petición: si sonó y si contestaron llega en actualizaciones voice_call. Rechazos: 403 VOICE_OUTBOUND_OFF: <motivo>, 403 USER_UNAVAILABLE (siempre el mismo cuerpo), 429, 503 VOICE_UNAVAILABLE. No se puede llamar desde la respuesta de un webhook.

answerVoiceCallToolQuery

POST/bot<token>/answerVoiceCallToolQuery

Devuelve: True. La primera respuesta es la última. Si llega tarde: 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable; ID desconocido: TOOL_QUERY_ID_INVALID; respuesta rechazada: TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <código>. Al POST de una consulta de herramienta recibido por webhook también se puede responder en el cuerpo de la respuesta.

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<token>/setVoiceCallApiKey

Devuelve: True; la clave solo se guarda tras pasar una sesión de prueba de la pasarela. API_KEY_INVALID, API_KEY_NO_REALTIME_ACCESS, 503 API_KEY_CHECK_UNAVAILABLE (no se guarda), 403 VOICE_OWN_KEY_NOT_AVAILABLE (este servidor no acepta claves propias). deleteVoiceCallApiKey no lleva parámetros y siempre devuelve True. Ninguno de los dos métodos se puede llamar con bots.sendCustomRequest, y setVoiceCallApiKey tampoco en una respuesta de webhook. Más detalles en Clave de modelo propia.

Métodos de los servidores MCP

auth y los secretos se envían solo en el cuerpo de la petición. En un servidor sin MCP: 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server. Más detalles en Bots de voz — Servidores MCP.

Para recibir actualizaciones de voz

voice_call, voice_call_tool_query y voice_call_transcript solo llegan si las pides por su nombre: ponlas en el allowed_updates de getUpdates o de setWebhook. Con una lista vacía no llegan, y lo que ocurrió antes de pedirlas no se acumula. Una consulta de herramienta llega por un POST aparte si hay webhook, o al principio del siguiente getUpdates si se llamó a getUpdates en los últimos 15 segundos.

VoiceCall

VoiceCall no tiene ningún campo que indique si quien llama eligió «Guardar conversación». Es intencionado: ese texto pertenece a quien llama y no va al bot. Por eso, en un servidor con «Guardar conversación» activado, el ended de todas las llamadas que no son de modo stream espera lo mismo, y el número del mensaje siguiente al registro de la llamada es, en todas las llamadas, al menos 31 mayor que el del registro (los números se reservan de antemano).

VoiceCallToolQuery

VoiceCallTranscript

Solo llega por la Bot API HTTP. La llamada completa está en el campo transcript del voice_call de fin de llamada.

Modo stream (mode=stream)

En modo stream, el audio de la llamada va al servidor del propietario del bot en lugar del modelo de IA de Pabal. Si envías a setVoiceCallSettings mode=stream, stream_url=wss://… y stream_secret=… (de 32 a 128 caracteres ASCII imprimibles, solo en el cuerpo de la petición), la pasarela de Pabal intenta conectarse una vez a esa dirección (sondeo) y, si lo consigue, se activa. Hacen falta las condiciones para propietarios de bots y una compilación de la aplicación con la pantalla de confirmación del modo stream. Configuración, resultados del sondeo y ejemplos: Bots de voz — Modo stream.

• Conexión: TLS 1.2 o superior, certificado público que coincida con el nombre de la URL, subprotocolo pabal.voice.v1, sin compresión, hasta 64 KiB por mensaje y 4 KiB por texto, sin redirecciones.
• Firma: 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 es el host de la URL que diste. Comprueba los 300 segundos, el nonce de un solo uso, la comparación byte a byte y que start.call_id sea igual a call (más detalles).
• Audio: los mensajes de texto son eventos JSON, y los binarios, PCM16 little-endian, mono, 24 kHz. La voz de quien llama llega en trozos de 20 ms (960 bytes).
• Pabal → bot: start (una vez) · live (terminó el aviso de IA) · audio · mark · cleared · buffer_full · stop (→ cierre 1000).
• Bot → Pabal: ready (en los 3 segundos siguientes a start, lo primero de todo) · audio (después de live) · clear · mark · hangup.

La forma de cada mensaje está en la tabla de Bots de voz — Especificación.

Errores de los métodos de voz

Los códigos de error de los métodos de voz y su significado están reunidos en Bots de voz — Errores. Un 403 tiene la forma Forbidden: <código>: <descripción> (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 siempre es exactamente Forbidden: USER_UNAVAILABLE, sin descripción, y si se supera el límite por hora llega 429 con retry_after.

Diferencias con la Bot API de Telegram

• Tipos de actualización: solo llegan message, edited_message, callback_query y los tipos de bots de voz propios de Pabal (voice_call, voice_call_tool_query, voice_call_transcript). No hay publicaciones de canal, consultas inline, pagos, encuestas, cambios de miembros (my_chat_member), etc.
• Formato: parse_mode y entities se ignoran y el texto se envía tal cual. Solo los comandos, las menciones, las URL y los hashtags se marcan automáticamente.
• Tipos de chat: solo chats uno a uno y grupos básicos. No hay canales, supergrupos ni temas de foro.
• Multimedia: solo fotos, archivos (sendDocument), ubicaciones, ubicaciones en tiempo real, lugares y contactos. No hay mensajes que se reproduzcan como vídeo o como voz, ni stickers, álbumes (sendMediaGroup), encuestas o envío mediante URL. Lo que se sube y se descarga por HTTP tiene un límite de 20 MB.
• Ubicaciones: la alerta de proximidad de una ubicación en tiempo real (proximity_alert_radius) solo se guarda, nunca se envía. Los movimientos a menos de 10 segundos o de 10 m del último aplicado se dejan pasar, y una tarjeta de contacto enviada por un bot no lleva user_id.
• Bots en grupos: no hay modo de privacidad, así que reciben todos los mensajes del grupo.
• Cola: las actualizaciones no recogidas se guardan en memoria, hasta las 1.000 más recientes por bot, y se pierden al reiniciar el servidor (Telegram las conserva 24 horas).
• Webhooks: las actualizaciones se envían de una en una y en orden (max_connections solo se guarda), no se aceptan certificados autofirmados y no hay restricción de puerto.
• IDs: los IDs de usuario, de mensaje y de archivo solo tienen sentido dentro de este servidor. Como no hay canales ni supergrupos, tampoco hay IDs con la forma -100….
• Métodos inexistentes: los que no están en la lista de arriba (forwardMessage, copyMessage, sendVideo, sendPoll, getChatMember, banChatMember, answerInlineQuery …) devuelven 404 Not Found: method not found.