API Reference

Complete reference for Telegem's API client and available methods.

API Client

The Telegem::API::Client handles all communication with Telegram's Bot API.

Initialization

client = Telegem::API::Client.new(token, **options)

Parameters:
- token (String): Bot token
- options (Hash):
- logger (Logger): Logger instance
- timeout (Integer): Request timeout in seconds (default: 30)

Methods

call(method, params = {})

Make a synchronous API call.

result = client.call('sendMessage', {
  chat_id: 123,
  text: 'Hello'
})

call!(method, params = {}, &callback)

Make an asynchronous API call with callback.

client.call!('sendMessage', { chat_id: 123, text: 'Hello' }) do |result, error|
  if error
    puts "Error: #{error.message}"
  else
    puts "Message sent: #{result['message_id']}"
  end
end

upload(method, params)

Upload files with multipart/form-data.

client.upload('sendPhoto', {
  chat_id: 123,
  photo: File.open('image.jpg'),
  caption: 'Photo'
})

download(file_id, destination_path = nil)

Download files from Telegram.

# Download to memory
content = client.download('file_id')

# Download to file
client.download('file_id', '/path/to/file.jpg')

get_updates(options = {})

Get updates (used internally by polling).

updates = client.get_updates(
  offset: 123,
  limit: 100,
  timeout: 30,
  allowed_updates: ['message']
)

Available API Methods

Sending Messages

sendMessage

bot.api.call('sendMessage', {
  chat_id: chat_id,
  text: 'Hello world',
  parse_mode: 'Markdown',  # 'Markdown' or 'HTML'
  disable_web_page_preview: true,
  reply_to_message_id: 123,
  reply_markup: keyboard_markup
})

sendPhoto

bot.api.call('sendPhoto', {
  chat_id: chat_id,
  photo: 'file_id_or_url',
  caption: 'Photo caption',
  parse_mode: 'Markdown',
  reply_markup: keyboard
})

sendDocument

bot.api.call('sendDocument', {
  chat_id: chat_id,
  document: file,
  caption: 'Document caption',
  parse_mode: 'Markdown'
})

sendAudio

bot.api.call('sendAudio', {
  chat_id: chat_id,
  audio: file,
  caption: 'Audio caption',
  title: 'Song title',
  performer: 'Artist name',
  duration: 180
})

sendVideo

bot.api.call('sendVideo', {
  chat_id: chat_id,
  video: file,
  caption: 'Video caption',
  duration: 60,
  width: 1920,
  height: 1080
})

sendVoice

bot.api.call('sendVoice', {
  chat_id: chat_id,
  voice: file,  # OGG format required
  caption: 'Voice message',
  duration: 10
})

sendLocation

bot.api.call('sendLocation', {
  chat_id: chat_id,
  latitude: 37.7749,
  longitude: -122.4194
})

sendContact

bot.api.call('sendContact', {
  chat_id: chat_id,
  phone_number: '+1234567890',
  first_name: 'John',
  last_name: 'Doe'
})

sendPoll

bot.api.call('sendPoll', {
  chat_id: chat_id,
  question: 'What\'s your favorite color?',
  options: ['Red', 'Blue', 'Green'],
  is_anonymous: true,
  allows_multiple_answers: false
})

Editing Messages

editMessageText

bot.api.call('editMessageText', {
  chat_id: chat_id,
  message_id: 123,
  text: 'Updated text',
  parse_mode: 'Markdown'
})

editMessageCaption

bot.api.call('editMessageCaption', {
  chat_id: chat_id,
  message_id: 123,
  caption: 'New caption'
})

editMessageReplyMarkup

bot.api.call('editMessageReplyMarkup', {
  chat_id: chat_id,
  message_id: 123,
  reply_markup: new_keyboard
})

Deleting Messages

deleteMessage

bot.api.call('deleteMessage', {
  chat_id: chat_id,
  message_id: 123
})

Chat Management

getChat

chat = bot.api.call('getChat', chat_id: chat_id)

getChatAdministrators

admins = bot.api.call('getChatAdministrators', chat_id: chat_id)

getChatMembersCount

count = bot.api.call('getChatMembersCount', chat_id: chat_id)

kickChatMember

bot.api.call('kickChatMember', {
  chat_id: chat_id,
  user_id: user_id,
  until_date: future_timestamp,
  revoke_messages: true
})

banChatMember

bot.api.call('banChatMember', {
  chat_id: chat_id,
  user_id: user_id,
  until_date: future_timestamp,
  revoke_messages: true
})

unbanChatMember

bot.api.call('unbanChatMember', {
  chat_id: chat_id,
  user_id: user_id,
  only_if_banned: true
})

restrictChatMember

bot.api.call('restrictChatMember', {
  chat_id: chat_id,
  user_id: user_id,
  permissions: {
    can_send_messages: false,
    can_send_media_messages: false
  },
  until_date: future_timestamp
})

promoteChatMember

bot.api.call('promoteChatMember', {
  chat_id: chat_id,
  user_id: user_id,
  can_change_info: true,
  can_delete_messages: true,
  can_invite_users: true,
  can_restrict_members: true,
  can_pin_messages: true,
  can_promote_members: false
})

Message Management

pinChatMessage

bot.api.call('pinChatMessage', {
  chat_id: chat_id,
  message_id: 123,
  disable_notification: false
})

unpinChatMessage

bot.api.call('unpinChatMessage', {
  chat_id: chat_id,
  message_id: 123
})

unpinAllChatMessages

bot.api.call('unpinAllChatMessages', chat_id: chat_id)

forwardMessage

bot.api.call('forwardMessage', {
  chat_id: destination_chat_id,
  from_chat_id: source_chat_id,
  message_id: 123,
  disable_notification: false
})

copyMessage

bot.api.call('copyMessage', {
  chat_id: destination_chat_id,
  from_chat_id: source_chat_id,
  message_id: 123,
  caption: 'Copied message'
})

Bot Commands

setMyCommands

bot.api.call('setMyCommands', {
  commands: [
    { command: 'start', description: 'Start the bot' },
    { command: 'help', description: 'Get help' }
  ]
})

getMyCommands

commands = bot.api.call('getMyCommands')

deleteMyCommands

bot.api.call('deleteMyCommands')

Webhook Management

setWebhook

bot.api.call('setWebhook', {
  url: 'https://example.com/webhook',
  max_connections: 40,
  allowed_updates: ['message', 'callback_query'],
  secret_token: 'secret_token'
})

deleteWebhook

bot.api.call('deleteWebhook')

getWebhookInfo

info = bot.api.call('getWebhookInfo')

File Operations

getFile

file_info = bot.api.call('getFile', file_id: file_id)
file_path = file_info['file_path']

Inline Queries

answerInlineQuery

bot.api.call('answerInlineQuery', {
  inline_query_id: query_id,
  results: [result_objects],
  cache_time: 300,
  next_offset: '20'
})

Callback Queries

answerCallbackQuery

bot.api.call('answerCallbackQuery', {
  callback_query_id: callback_id,
  text: 'Button pressed!',
  show_alert: false,
  url: 'https://example.com',
  cache_time: 5
})

Chat Actions

sendChatAction

bot.api.call('sendChatAction', {
  chat_id: chat_id,
  action: 'typing'  # typing, upload_photo, upload_video, etc.
})

Games

sendGame

bot.api.call('sendGame', {
  chat_id: chat_id,
  game_short_name: 'my_game'
})

setGameScore

bot.api.call('setGameScore', {
  user_id: user_id,
  score: 100,
  chat_id: chat_id,
  message_id: 123
})

Payments

sendInvoice

bot.api.call('sendInvoice', {
  chat_id: chat_id,
  title: 'Product',
  description: 'Description',
  payload: 'order_id',
  provider_token: 'payment_token',
  currency: 'USD',
  prices: [{ label: 'Price', amount: 1000 }]
})

answerShippingQuery

bot.api.call('answerShippingQuery', {
  shipping_query_id: query_id,
  ok: true,
  shipping_options: [shipping_option]
})

answerPreCheckoutQuery

bot.api.call('answerPreCheckoutQuery', {
  pre_checkout_query_id: query_id,
  ok: true
})

Stickers

sendSticker

bot.api.call('sendSticker', {
  chat_id: chat_id,
  sticker: sticker_file_id
})

getStickerSet

sticker_set = bot.api.call('getStickerSet', name: 'sticker_set_name')

Profile Management

setMyProfilePhoto

bot.api.call('setMyProfilePhoto', {
  photo: photo_file
})

removeMyProfilePhoto

bot.api.call('removeMyProfilePhoto')

Business Features

sendBusinessMessage

bot.api.call('sendBusinessMessage', {
  business_connection_id: connection_id,
  chat_id: chat_id,
  text: 'Business message'
})

Context Methods

Convenience methods available on the context object.

Message Sending

ctx.reply(text, **options)
ctx.photo(file, **options)
ctx.document(file, **options)
ctx.audio(file, **options)
ctx.video(file, **options)
ctx.voice(file, **options)
ctx.sticker(file_id, **options)
ctx.location(lat, lng, **options)
ctx.contact(phone, first_name, **options)

Message Editing

ctx.edit_message_text(text, **options)
ctx.edit_message_caption(caption, **options)
ctx.edit_message_reply_markup(keyboard, **options)
ctx.delete_message(message_id)

Chat Management

ctx.kick_chat_member(user_id, **options)
ctx.ban_chat_member(user_id, **options)
ctx.unban_chat_member(user_id, **options)
ctx.restrict_chat_member(user_id, **options)
ctx.promote_chat_member(user_id, **options)

Utilities

ctx.answer_callback_query(**options)
ctx.answer_inline_query(results, **options)
ctx.send_chat_action(action, **options)
ctx.download_file(file_id, path)

Error Handling

API calls raise Telegem::API::APIError on failure.

begin
  result = bot.api.call('sendMessage', params)
rescue Telegem::API::APIError => e
  puts "API Error: #{e.message}"
  puts "Error code: #{e.code}" if e.code
end

Common Error Codes

400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid token)
403 - Forbidden (bot blocked by user)
404 - Not Found (chat/user not found)
429 - Too Many Requests (rate limited)

Rate Limits

Telegram imposes rate limits on bot API calls:

30 messages per second for broadcasting
20 callback query answers per second
60 API calls per minute for other methods

Implement rate limiting middleware for high-traffic bots.

File Upload Limits

Photos: 10 MB
Documents: 50 MB
Videos: 50 MB (upload), 20 MB (via URL)
Other files: 50 MB

Best Practices

Use appropriate timeouts for your use case
Handle API errors gracefully with retries
Implement rate limiting to avoid hitting limits
Validate parameters before API calls
Use webhooks for production deployments
Log API calls for debugging
Cache file IDs to avoid re-uploading

The Telegram Bot API is extensive. Refer to the official documentation for complete method reference.
/home/slick/telegem/docs/api.md