Skip to content

README.md

Latest commit

 

History

History
188 lines (139 loc) · 4.78 KB

README.md

File metadata and controls

188 lines (139 loc) · 4.78 KB
Raw

telegram-mtproto-ruby

🚀 Pure Ruby MTProto 2.0 implementation for Telegram API

A complete, production-ready Ruby implementation of Telegram's MTProto 2.0 protocol with full support for:

  • ✅ Complete DH Handshake - Secure key exchange with Telegram servers
  • ✅ AES-IGE Encryption/Decryption - Full MTProto 2.0 cryptography
  • ✅ TL Schema Parser - Dynamic parsing of Telegram Type Language
  • ✅ auth.sendCode & auth.signIn - Full authentication flow
  • ✅ contacts.getContacts - Retrieve user contacts
  • ✅ messages.sendMessage - Send messages to users
  • ✅ updates.getDifference - Receive incoming messages
  • ✅ Background Polling - Continuous message reception

Installation

Add this line to your application's Gemfile:

gem 'telegram-mtproto-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install telegram-mtproto-ruby

Quick Start

1. Get Telegram API Credentials

  1. Go to https://my.telegram.org/apps
  2. Login with your Telegram account
  3. Create a new app and get your api_id and api_hash

2. Basic Authentication

require 'telegram_mtproto'

# Initialize client
client = TelegramMtproto.new(
  api_id,      # Your API ID (integer)
  api_hash,    # Your API Hash (string)
  phone_number # Your phone number with country code (e.g., "+1234567890")
)

# Send verification code
result = client.send_code
if result[:success]
  puts "✅ Code sent! Check your Telegram app"
  phone_code_hash = result[:phone_code_hash]
  
  # Sign in with PIN code
  print "Enter PIN: "
  pin_code = gets.chomp
  
  auth_result = client.sign_in(phone_code_hash, pin_code)
  if auth_result[:success]
    puts "🎉 Successfully authenticated!"
  else
    puts "❌ Authentication failed: #{auth_result[:error]}"
  end
else
  puts "❌ Failed to send code: #{result[:error]}"
end

3. Send Messages

# Get contacts
contacts = client.get_contacts
if contacts[:success]
  puts "📋 Found #{contacts[:users].length} contacts"
  
  # Send message to first contact
  first_user = contacts[:users].first
  result = client.send_message(
    first_user[:id], 
    "Hello from telegram-mtproto-ruby! 🚀"
  )
  
  if result[:success]
    puts "✅ Message sent successfully!"
  end
end

4. Receive Messages

# Start polling for incoming messages
client.start_updates_polling do |message|
  puts "📥 New message: '#{message[:message]}' from user #{message[:from_id]}"
end

# Keep the script running
sleep(60)

# Stop polling
client.stop_updates_polling

Features

Core MTProto 2.0 Support

  • Diffie-Hellman Handshake: Complete implementation matching Telethon
  • AES-IGE Encryption: Full MTProto 2.0 cryptographic support
  • Message ID Generation: Proper timing and monotonicity
  • Salt Management: Automatic bad_server_salt handling
  • Connection Management: TCP Full connection with CRC32

Telegram API Methods

Method Description Status
auth.sendCode Send verification code to phone ✅
auth.signIn Authenticate with PIN code ✅
contacts.getContacts Get user contact list ✅
messages.sendMessage Send message to user ✅
updates.getDifference Get incoming updates ✅

TL Schema Support

  • Dynamic parsing of api.tl and mtproto.tl
  • Type-safe serialization of all Telegram objects
  • Automatic parameter validation
  • Zero hardcoded values - everything uses official TL schemas

Advanced Usage

Error Handling

result = client.send_code
case result[:error]
when "PHONE_NUMBER_INVALID"
  puts "Invalid phone number format"
when "API_ID_INVALID"
  puts "Check your API credentials"
when "FLOOD_WAIT_X"
  puts "Rate limited, wait #{result[:error].match(/\d+/)[0]} seconds"
end

2FA Support

auth_result = client.sign_in(phone_code_hash, pin_code)
if auth_result[:requires_2fa]
  print "Enter 2FA password: "
  password = gets.chomp
  # TODO: Implement auth.checkPassword
end

Background Message Processing

client.start_updates_polling do |message|
  # Process message in background
  Thread.new do
    process_message(message)
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mikefluff/telegram-mtproto-ruby.

License

The gem is available as open source under the terms of the MIT License.

Credits

This implementation was inspired by Telethon and follows Telegram's official MTProto documentation.