Before a call is ready, some preliminary actions have to be performed. The calling party needs to contact the party to be called and check whether it is ready to accept the call. Besides that, the parties have to negotiate the protocols to be used, learn the IP addresses of each other or of the Telegram relay servers to be used (so-called reflectors), and generate a one-time encryption key for this voice call with the aid of Diffie--Hellman key exchange. All of this is accomplished in parallel with the aid of several Telegram API methods and related notifications. This document covers details related to key generation, encryption and security.
-
Key Generation
-
The Diffie-Hellman key exchange, as well as the whole protocol used to create a new voice call, is quite similar to the one used for Secret Chats. We recommend studying the linked article before proceeding.
-
However, we have introduced some important changes to facilitate the key verification process. Below is the entire exchange between the two communicating parties, the Caller (A) and the Callee (B), through the Telegram servers (S).
-
-
A executes messages.getDhConfig to find out the 2048-bit Diffie-Hellman prime p and generator g. The client is expected to check whether p is a safe prime and perform all the security checks necessary for secret chats.
-
A chooses a random value of a, 1 < a < p-1, and computes g_a:=power(g,a) mod p (a 256-byte number) and g_a_hash:=SHA256(g_a) (32 bytes long).
-
A invokes (sends to server S) phone.requestCall, which has the field g_a_hash:bytes, among others. For this call, this field is to be filled with g_a_hash, notg_a itself.
-
The Server S performs privacy checks and sends an updatePhoneCall update with a phoneCallRequested constructor to all of B's active devices. This update, apart from the identity of A and other relevant parameters, contains the g_a_hash field, filled with the value obtained from A.
-
B accepts the call on one of their devices, stores the received value of g_a_hash for this instance of the voice call creation protocol, chooses a random value of b, 1 < b < p-1, computes g_b:=power(g,b) mod p, performs all the required security checks, and invokes the phone.acceptCall method, which has a g_b:bytes field (among others), to be filled with the value of g_b itself (not its hash).
-
The Server S sends an updatePhoneCall with the phoneCallDiscarded constructor to all other devices B has authorized, to prevent accepting the same call on any of the other devices. From this point on, the server S works only with that of B's devices which has invoked phone.acceptCall first.
-
The Server S sends to A an updatePhoneCall update with phoneCallAccepted constructor, containing the value of g_b received from B.
-
A performs all the usual security checks on g_b and a, computes the Diffie--Hellman key key:=power(g_b,a) mod p and its fingerprint key_fingerprint:long, equal to the lower 64 bits of SHA1(key), the same as with secret chats. Then A invokes the phone.confirmCall method, containing g_a:bytes and key_fingerprint:long.
-
The Server S sends to B an updatePhoneCall update with the phoneCall constructor, containing the value of g_a in g_a_or_b:bytes field, and key_fingerprint:long
-
At this point B receives the value of g_a. It checks that SHA256(g_a) is indeed equal to the previously received value of g_a_hash, performs all the usual Diffie-Hellman security checks, and computes the key key:=power(g_a,b) mod p and its fingerprint, equal to the lower 64 bits of SHA1(key). Then it checks that this fingerprint equals the value of key_fingerprint:long received from the other side, as an implementation sanity check.
-
-
At this point, the Diffie--Hellman key exchange is complete, and both parties have a 256-byte shared secret key key which is used to encrypt all further exchanges between A and B.
-
It is of paramount importance to accept each update only once for each instance of the key generation protocol, discarding any duplicates or alternative versions of already received and processed messages (updates).
-
Encryption
-
-
This document describes encryption in voice and video calls as implemented in Telegram apps with versions 7.0 and above. See this document for details on encryption used in voice calls in app versions released before August 14, 2020.
-
-
The Telegram Voice and Video Call Library uses an optimized version of MTProto 2.0 to send and receive packets, consisting of one or more end-to-end encrypted messages of various types (icecandidates list, video formats, remote video status, audio stream data, video stream data, message ack or empty).
-
This document describes only the encryption process, leaving out encoding and network-dependent parts.
-
The library starts working with:
-
-
An encryption keykey shared between the parties, as generated above.
-
Information whether the call is outgoing or incoming.
-
Two data transfer channels: signaling, offered by the Telegram API, and transport based on WebRTC.
-
-
Both data transfer channels are unreliable (messages may get lost), but signaling is slower and more reliable.
-
Encrypting Call Data
-
The body of a packet (decrypted_body) consists of several messages and their respective seq numbers concatenated together.
Each decrypted_body is unique because no two seq numbers of the first message can be the same. If only old messages need to be re-sent, an empty message with new unique seq is added to the packet first.
-
The encryption keykey is used to compute a 128-bit msg_key and then a 256-bit aes_key and a 128-bit aes_iv:
x depends on whether the call is outgoing or incoming and on the connection type:
-
-
x = 0 for outgoing + transport
-
x = 8 for incoming + transport
-
x = 128 for outgoing + signaling
-
x = 136 for incoming + signaling
-
-
This allows apps to decide which packet types will be sent to which connections and work in these connections independently (with each having its own seq counter).
-
The resulting aes_key and aes_iv are used to encrypt decrypted_body:
The packet that gets sent consists of msg_key and encrypted_body:
-
-
packet_bytes = msg_key + encrypted_body
-
-
When received, the packet gets decrypted using key and msg_key, after which msg_key is checked against the relevant SHA256 substring. If the check fails, the packet must be discarded.
-
Protecting Against Replay Attacks
-
Each of the peers maintains its own 32-bit monotonically increasing counter for outgoing messages, seq, starting with 1. This seq counter is prepended to each sent message and increased by 1 for each new message. No two seq numbers of the first message in a packet can be the same. If only old messages need to be re-sent, an empty message with a new unique seq is added to the packet first. When the seq counter reaches 2^30, the call must be aborted. Each peer stores seq values of all the messages it has received (and processed) which are larger than max_received_seq - 64, where max_received_seq is the largest seq number received so far.
-
If a packet is received, the first message of which has a seq that is smaller or equal to max_received_seq - 64 or its seq had already been received, the message is discarded. Otherwise, the seq values of all incoming messages are memorized and max_received_seq is adjusted. This guarantees that no two packets will be processed twice.
-
Key Verification
-
To verify the key, and ensure that no MITM attack is taking place, both parties concatenate the secret key key with the value g_a of the Caller ( A ), compute SHA256 and use it to generate a sequence of emoticons. More precisely, the SHA256 hash is split into four 64-bit integers; each of them is divided by the total number of emoticons used (currently 333), and the remainder is used to select specific emoticons. The specifics of the protocol guarantee that comparing four emoticons out of a set of 333 is sufficient to prevent eavesdropping (MiTM attack on DH) with a probability of 0.9999999999.
-
This is because instead of the standard Diffie-Hellman key exchange which requires only two messages between the parties:
-
-
A->B : (generates a and) sends g_a := g^a
-
B->A : (generates b and true key (g_a)^b, then) sends g_b := g^b
-
A : computes key (g_b)^a
-
-
we use a three-message modification thereof that works well when both parties are online (which also happens to be a requirement for voice calls):
-
-
A->B : (generates a and) sends g_a_hash := hash(g^a)
B : checks hash(g_a) == g_a_hash, then computes key (g_a)^b
-
-
The idea here is that A commits to a specific value of a (and of g_a) without disclosing it to B. B has to choose its value of b and g_b without knowing the true value of g_a, so that it cannot try different values of b to force the final key (g_a)^b to have any specific properties (such as fixed lower 32 bits of SHA256(key)). At this point, B commits to a specific value of g_b without knowing g_a. Then A has to send its value g_a; it cannot change it even though it knows g_b now, because the other party B would accept only a value of g_a that has a hash specified in the very first message of the exchange.
-
If some impostor is pretending to be either A or B and tries to perform a Man-in-the-Middle Attack on this Diffie--Hellman key exchange, the above still holds. Party A will generate a shared key with B -- or whoever pretends to be B -- without having a second chance to change its exponent a depending on the value g_b received from the other side; and the impostor will not have a chance to adapt his value of b depending on g_a, because it has to commit to a value of g_b before learning g_a. The same is valid for the key generation between the impostor and the party B.
-
The use of hash commitment in the DH exchange constrains the attacker to only one guess to generate the correct visualization in their attack, which means that using just over 33 bits of entropy represented by four emoji in the visualization is enough to make a successful attack highly improbable.
This article is about Perfect Forward Secrecy in cloud chats, see also PFS in Secret Chats.
-
-
-
Telegram supports Perfect Forward Secrecy (PFS).
-
To make this possible, the client generates a permanent authorization key using p_q_inner_data and a temporary key using p_q_inner_data_temp. (See Creating an Authorization Key for more info.) These 2 operations may be done in parallel and even using the same connection. The client must save an expires_at unix timestamp expires_at = time + expires_in.
-
Important: in order to achieve PFS, the client must never use the permanent auth_key_id directly. Every message that is sent to MTProto, must be encrypted by a temp_auth_key_id, that was bound to the perm_auth_key_id.
-
An unbound temp_auth_key_id may only be used with the following methods:
In order to bind a temporary authorization key to the permanent key the client creates a special binding message and executes the auth.bindTempAuthKey method using temp_auth_key. Once auth.bindTempAuthKey has been executed successfully, the client may signUp / signIn using other auth.* methods and continue using the API as usual; the client must also rewrite client info using initConnection after each binding. Each permanent key may only be bound to one temporary key at a time, binding a new temporary key overwrites the previous one.
-
Once the temporary key expires, the client needs to generate a new temporary key using p_q_inner_data_temp. Then it needs to re-bind that new temporary key to the initial permanent key. A new key can also be generated in advance, so that the client has a new key ready by the time the old one has expired.
-
For additional security, the client can store the temporary authorization key in RAM only and never save it in persistent storage.
-
A temporary authorization key may expire at any moment before expires_at, since such keys are also stored only in the RAM on the server-side. Be prepared to handle resulting MTProto errors correctly (non-existent auth_key_id results in a 404 error).
The specified message or media will be added to a server-side schedule queue for the current chat, and will be automatically sent at the specified time.
-The method call generates the following updates:
-
-
Immediately, an updateNewScheduledMessage, with ID equal to the ID of the message in the schedule queue for the current chat (each PM, chat, supergroup and channel has its own schedule queue and ID sequence).
-
At schedule_date, an updateNewMessage or updateNewChannelMessage with the from_scheduled flag set, indicating to the sender that the specified scheduled message was sent.
-
At schedule_date, an updateDeleteScheduledMessages, indicating that the message was flushed from the schedule queue.
-
-
If the schedule_date is less than 10 seconds in the future, the message will be sent immediately, generating a normal updateNewMessage/updateNewChannelMessage .
When using messages.search or messages.searchGlobal, a certain message filter may be applied.
-This allows the server to filter messages based on a text query, and even on their type, and this feature is often used by graphical clients to implement features like the chat gallery, chat profile pictures and more.
-Available filters:
-
-
inputMessagesFilterPhotos - Returns only photos, used for implementing the chat photo gallery, and when scrolling left or right while viewing a photo
-
inputMessagesFilterVideo - Returns only videos, used for implementing the chat video gallery, and when scrolling left or right while viewing a video
inputMessagesFilterVoice - Return only voice messages, used for implementing the chat voice message gallery, and to consecutively play voice messages in a chat
-
inputMessagesFilterMusic - Return only music files, used for implementing the chat music gallery
-
inputMessagesFilterChatPhotos - Return only chat photos, used to allow scrolling through the profile picture history of a group
inputMessagesFilterMyMentions - Return only messages mentioning me, can be used to display the mention history or, combined with another filter or query, return only messages that satisfy a certain criteria, and contain a mention.
The returned messages.Messages constructors contain parameters for pagination, the messages themselves and two offset_id_offset/count parameters that can be used to display a progress/total counter like photo 134 of 200.
-For example, when displaying the chat photo gallery, we could display a photo ${offset_id_offset} of ${count} indicator on top.
When the user clicks on keyboardButtonUrlAuth, messages.requestUrlAuth should be called, providing the button_id of the button and the ID and peer of the container message.
-The returned urlAuthResultRequest object will contain more details about the authorization request:
-
-
The domain parameter will contain the domain name of the website on which the user will log in (example: comments.app).
-
The bot parameter will contain info about the bot which will be used for user authorization (example: DiscussBot).
-
The request_write_access will be set if the bot would like to send messages to the user.
-
-
The info should be shown in a prompt:
-
-
-
-
If the user agrees to login to the URL, messages.acceptUrlAuth should be called (eventually setting the write_allowed if the permission was requested and the user consented).
-The result will be a urlAuthResultAccepted with the final URL to open, which will include a query string with the requested info and a hash that must be verified upon receival by the service.
-
urlAuthResultDefault could also be returned, instead, in which case the url of the keyboardButtonUrlAuth must be opened, instead.
-The same must be done if the user opens the link while refusing the authorization request.
Beyond sending commands in private messages or groups, users can interact with your bot via inline queries. If inline queries are enabled, users can call your bot by typing its username and a query in the text input field in any chat. The query is sent to your bot in an update. This way, people can request content from your bot in any of their chats, groups, or channels without sending any messages at all.
-
-
-
-
-
-
To enable this option, send the /setinline command to @BotFather and provide the placeholder text that the user will see in the input field after typing your bot’s name.
-
-
See the Bot API Manual for the relevant methods and objects.
-
-
Inline results
-
Inline bots support all types of content available in Telegram (20 in all). They are capable of sending stickers, videos, music, locations, documents and more.
-
-
-
-
-
Clients can display the results with vertical or horizontal scrolling, depending on the type of content:
-
-
-
-
-
-
-
-
-
-
As soon as the user taps on an item, it's immediately sent to the recipient, and the input field is cleared.
-
Switching inline/PM modes
-
Some inline bots can benefit from an initial setup process, like connecting them to an account on an external service (e.g., YouTube). We've added an easy way of switching between the private chat with a bot and whatever chat the user wants to share inline results in.
-
-
-
-
-
You can display a special ‘Switch to PM’ button above the inline results (or instead of them). This button will open a private chat with the bot and pass a parameter of your choosing, so that you can prompt the user for the relevant setup actions. Once done, you can use an inline keyboard with a switch_inline_query button to send the user back to the original chat.
-
Sample bots @youtube – Shows a ‘Sign in to YouTube’ button, then suggests personalized results.
Inline bots can request location data from their users. Use the /setinlinegeo command with @BotFather to enable this. Your bot will ask the user for permission to access their location whenever they send an inline request.
-
Sample bot @foursquare – This bot will ask for permission to access the user's location, then provide geo-targeted results.
-
Spreading virally
-
Messages sent with the help of your bot will show its username next to the sender's name.
-
-
-
-
-
-
-
-
-
When a user taps on the bot username in the message header, the mention is automatically inserted into the input field. Entering the @ symbol in the input field brings up a list of suggestions, featuring recently used inline bots.
-
Collecting feedback
-
To know which of the provided results your users are sending to their chat partners, send @Botfather the /setinlinefeedback command. With this enabled, you will receive updates on the results chosen by your users.
-
Please note that this can create load issues for popular bots – you may receive more results than actual requests due to caching (see the cache_time parameter in answerInlineQuery). For these cases, we recommend adjusting the probability setting to receive 1/10, 1/100 or 1/1000 of the results.
-
Inline bot samples
-
Here are some sample inline bots, in case you’re curious to see one in action. Try any of these: @gif – GIF search @vid – Video search @pic – Yandex image search @bing – Bing image search @wiki – Wikipedia search @imdb – IMDB search @bold – Make bold, italic or fixed sys text
-
NEW @youtube - Connect your account for personalized results @music - Search and send classical music @foursquare – Find and send venue addresses @sticker – Find and send stickers based on emoji
We currently support two ways of processing bot updates, getUpdates and setWebhook. getUpdates is a pull mechanism, setwebhook is push. Although the concept of a webhook is fairly simple, the setup of the individual components has proven to be tricky for many. This guide provides some extra information for those of you brave enough to venture into the art of the webhook.
-
There are some advantages of using a webhook over getUpdates. As soon as an update arrives, we’ll kindly deliver it to your bot for processing.
-
This:
-
1. Avoids your bot having to ask for updates frequently.
-2. Avoids the need for some kind of polling mechanism in your code.
-
Other advantages may include saving some potential CPU cycles and an increase in response time, these things however depend heavily on the usage pattern of your bot.
-
Setting a webhook means you supplying Telegram with a location in the form of a URL, on which your bot listens for updates. We need to be able to connect and post updates to that URL.
-
To ensure that we can do that, there are some basic requirements:
-
The short version
-
You'll need a server that:
-
-
Supports IPv4, IPv6 is currently not supported for webhooks.
-
Accepts incoming POSTs from subnets 149.154.160.0/20 and 91.108.4.0/22 on port 443, 80, 88, or 8443.
-
Is able to handle TLS1.2(+) HTTPS-traffic.
-
Provides a supported, non-wildcard, verified or self-signed certificate.
-
Uses a CN or SAN that matches the domain you’ve supplied on setup.
-
Supplies all intermediate certificates to complete a verification chain.
-
-
That’s almost all there’s to it. If you decide to limit traffic to our specific range of addresses, keep an eye on this document whenever you seem to run into trouble. Our IP-range might change in the future.
-
The longer version
-
-
A domain name
-
Setting a webhook needs a URL for us to post to. For that you'll need a server with a domain name. If you don't have one, you'll need to obtain one first. Telegram currently doesn't offer hosting or domain name services. There are quite a few VPS/Web hosting providers around the internet, feel free to pick one to your liking. If you're using a self-signed certificate, you may use the IP as a CN, instead of the domain name. How do I get a server with a domain name?
-
-
An open port
-
A webhook needs an open port on your server. We currently support the following ports: 443, 80, 88 and 8443. Other ports are not supported and will not work. Make sure your bot is running on one of those supported ports, and that the bot is reachable via its public address.
-
If you want to limit access to Telegram only, please allow traffic from 149.154.167.197-233 (starting July 2019 please use: 149.154.160.0/20 and 91.108.4.0/22).
-Whenever something stops working in the future, please check this document again as
-the range might expand or change.
A webhook requires SSL/TLS encryption, no matter which port is used. It's not possible to use a plain-text HTTP webhook. You shouldn't want to either, for the sake of your bot and users. SSL/TLS, why do I have to handle this for a webhook?
-
-
Not all SSL/TLS is equal
-
We support any SSL/TLS version TLS1.2 and up for your webhook. This means that SSLV2/3/TLS1.0/TSL1.1 are NOT supported, due to security issues associated with those older versions. How do I check that I’m handling the right version?
-
-
SSL needs a certificate
-
The common name (CN) of your certificate (self-signed or verified) has to match the domain name where your bot is hosted. You may also use a subject alternative name (SAN), that matches the domain for your webhook. Server Name Indication (SNI)-routing is supported. If you're using a self-signed certificate, you may use the IP as a CN, instead of the domain name. A certificate, where do I get one, and how?
-
-
Verified or self-signed
-
A certificate can either be verified or self-signed. Setting a webhook with a self-signed certificate differs a little from setting a webhook with a verified certificate. Ensure you're using the correct setup for the type of certificate you've chosen for your webhook. How do I set a webhook for either type?
-
-
Supported certificates
-
Not all verified certificates are supported. Certificates are based on a network of trust and come in a chain. Trusting your verified certificate means we have to trust the provider of that certificate, the Certificate Authority (and hence its root certificate). Before you pick a certificate provider, Check this list to make sure that we actually trust their root certificate. What if my root certificate isn’t on that list?
-
-
An Untrusted root
-
Ok, so you already had a certificate installed and just discovered it’s not on our list. Start by ignoring it, and just try to set it. We occasionally add extra root certificates to keep up with popular demand, so the list isn't always exhaustive. Unlucky after all? We'll allow you to supply an unsupported root certificate when setting the webhook. This method is nearly identical to setting a self-signed certificate webhook. Instead of your self-signed certificate you'll be sending us the root certificate as inputFile. Setting a verified webhook with an untrusted root
-
-
Intermediate certificates
-
Some verified certificates require an intermediate certificate. In this construction the provider of your verified certificate has used their root certificate to sign an intermediate certificate. This intermediate certificate is then used to sign your verified certificate. You'll need to provide the intermediate certificate for us to be able to verify the chain of trust. CA's that use this type of chain supply an intermediate certificate. Supplying an intermediate certificate
-
-
More information
-
Since we know webhooks can be a tad overwhelming, we’re working on a little digital assistant that’ll try and help you with the most common problems, it's not nearly perfect, but you may try using @CanOfWormsBot to check if your chain of certificates is installed correctly before contacting support.
-
-
Testing your bot
-
We took the liberty of adding a set of example updates. They come in handy when testing your bot, no matter which method of getting updates you might be using.
-
-
Don't panic.
-
If by now you're looking for your fishing gear because we've mentioned ports and hooks or you're about to Google what kind of bait URL and TLS exactly are, this guide might not be completely for you. You’re quite likely still a brilliant bot programmer, don’t worry. Perhaps this whole webhook thing is just new to you, not all is lost. If you currently have a working getUpdates situation, it's a good idea to pick up this guide again on a rainy Sunday afternoon and take your time to read up on some subjects around the internet. This guide can only contain a finite amount of information after all.
-
-
-
The verbose version
-
How do I get a server with a domain name?
-
If you use a webhook, we have to deliver requests to your bot to a server we can reach. So yes, you need a server we can connect to. It can be anywhere in the galaxy, if you ensure we can reach the server by domain name (or at least via IP for a self-signed certificate), it will work just fine.
-
There are quite a few ways to get this done, as a novice however it's likely that you're not directly jumping at the chance of crafting this from scratch. Actually, as a novice, we recommend you don't. It's likely to be a complex and long ride.
-
If you got stuck here, make a choice:
-
-
You use getUpdates at the moment and it works, keep it that way. Especially if you're running your bot from a nice machine that does well. There is nothing wrong with using getUpdates.
-
-
Go with a hosted service and let a bunch of professionals worry about things like registering a domain, setting up DNS, a web server, securing it and so on.
-
-
-
If you're going with a hosted service, make sure to look for a hosting provider that
-not only supports your code’s needs, for example: support for your PHP version,
-but one that also handles SSL and allows you to create/deploy certificates.
-
-
Go crazy, dive on the internet and start reading. Once you’re confident that you’ve got all the basic theories down, find yourself a nice hosted VPS or roll your own machine at home and get back to us here.
-
-
How do I check for open ports or limit access to my bot?
-
So you have the hosting thing down and all is good so far, however, when you enter the address of your bot in your browser it seems unreachable.
-
Explaining every firewall or web server solution in detail isn't possible for us, which we hope you understand. If you’re running a hosted solution, you’re more likely to have a nice UI where you configure these settings. Head to your configuration panel and check all of them. If you’re on a Linux based VPS with shell access, we have some tips for you:
-
-
Make sure your bot process is indeed configured to listen on the port you're using. netstat –ln | grep portnumber Shows you if your bot is actually listening for incoming requests on the port you expect. sudo lsof -i | grep process name Is a simple way to check if that’s actually being listened on by the process your bot is using.
-
-
-
Make sure it’s listening correctly. Your bot has to listen on the address you’ve exposed to the outside (your public IP), it can also listen on all addresses (*: or 0.0.0.0). The netstat and lsof-commands mentioned above assist in checking this. If nothing shows up, it is time to check your configuration and fix it. Set the correct IP, make sure it’s listening on a supported port and fire away! Just use a Web Browser to check if you’re reachable. The problem can be in the configuration of your bot, your web server virtual host configuration, or the servers binding configuration.
-
-
-
If you still can’t reach your address, check your firewall. sudo iptables –L OR sudo ufw status verbose (Ubuntu) Gives you some insight in the current firewall settings.
-
-
If it looks like you’re blocking incoming traffic, let’s fix that. sudo iptables –A INPUT –p tcp –m tcp –dport portnumber -j ACCEPT OR sudo ufw allow portnumber/tcp Allows incoming traffic on all interfaces to the specified tcp port. sudo iptables –A INPUT –i interfacename –p tcp –m tcp –dport portnumber -j ACCEPT OR sudo ufw allow in on interfacename to any port portnumber proto tcp Allows incoming traffic to a specific interface and a specific port from everywhere. sudo ifconfig Helps you find the interface with the public address you’re going to use.
-
-
-
If you use iptables, make sure to actually SAVE after changing the configuration.
-On a Debian based system the iptables-persistent package is be a good option.
-RHEL/CentOS offers a service iptables save -command.
-A quick online search for "YOUROPERATINGSYSTEM save iptables" also helps.
-
-
If you’re just looking for some hints on how to limit incoming traffic: sudo iptables –A INPUT –i interfacename –p tcp –m iprange –src-range 149.154.167.197-149.154.167.233 –dport portnumber -j ACCEPT OR sudo ufw allow in on interfacename to any port portnumber proto tcp from 149.154.167.192/26 Allows incoming traffic to a specific interface and a specific port from a specific range of addresses. (ufw is using a subnet mask in the example, ranging from 192-255)
-
-
That’s all for our examples. More information on best practices for setting up your firewall, on whichever operating system you prefer for your bot, is best found on the internet.
-
SSL/TLS, what is it and why do I have to handle this for a webhook?
-
You’re already familiar with it in some form or another. Whenever you see that (nicely green) lock in your browser bar, you know it’s reasonably safe to assume that you’ve landed on the site you actually wanted to visit. If you see the green lock, that's SSL/TLS in action. If you want to learn more about how SSL/TLS works in general, it's best to search the internet.
-
The main difference between getUpdates and a webhook is the way the connection takes place. getUpdates means you'll connect to our server, a webhook means we'll be connecting to your server instead. Connecting to your server has to be done secure, we have to know for sure it's you we're talking to after all. This means you'll have to handle all that server side encryption stuff, virtually presenting us with a green lock. If you use a web server for us to post to, you need to support SSL/TLS handling on the port/virtual host of your choice. An online search for “YOURWEBSERVER enable HTTPS” will help you.
-
Not using a regular web server? Have a look at our example page, most examples there include code for handling SSL/TLS in a webhook setup.
-
How do I check that I’m handling the right version?
-
You just read up on the whole SSL/TLS stuff, figured out that it’s not all that bad to setup and we add some more requirements. Here are some tips to check if you’re indeed supporting at least TLS1.2.
-
-
Several online services exist that allow you to check your certificate installation, They give you an overview of your supported TLS versions/Cipher suites and other details. Search online for Symantec crypto report or Qualys ssl. Both supply tools to verify your setup.
-
-
Checking locally can also be done, in several ways, here are three options,
-
-
Go simple: Using Chrome as a browser? Open up the URL to your bot and inspect the certificate details. If you’re supporting TLS Chrome tells you so in the security overview tab. Other browsers are likely able to give you similar basic information.
-
-
Using curl: curl --tlsv1.2 -v -k https://yourbotdomain:yourbotport/ You can add --tlsv1.2 to force curl into using TLS1.2 when trying to connect. -k is optional and used to check against a self-signed certificate. yourbotdomain is the public hostname your webhook is running on. For local testing purposes you can also use the IP. yourbotport is the port you’re using.
-
-
Using OpenSSL openssl s_client -tls1_2 -connect yourbotdomain:yourbotport -servername yourbotdomain You can add -tls1_2 to force OpenSSL into using TLS1.2 when trying to connect. yourbotdomain is the public hostname your webhook is running on. For local testing purposes you can also use the IP. yourbotport is the port you’re using. Note that https:// isn’t used for OpenSSL. -servername is optional, and included here for some shared hosters, which use SNI to route traffic to the correct domain. When SNI is used you’ll notice that your server appears to be returning a certificate for a different domain than your own. Adding -servername yourbotdomain ensures that SNI negotiation is done, and the correct certificate is returned.
-
-
-
-
Some additional configuration pointers
-
-
Forcing TLS in your virtual host on Apache: SSLProtocol -all +TLSv1.2
-
Forcing TLS in your virtual host on Nginx: ssl_protocols TLSv1.2;
-
Force TLS for your Java virtual machine through system properties: -Dhttps.protocols=TLSv1.2 -Djdk.tls.client.protocols=TLSv1.2
-
Enabling ssl debug for your JVM: -Djavax.net.debug=ssl,handshake,record
Using a verified certificate means you already have, or will obtain, a certificate backed by a trusted certificate authority (CA). There are many ways to acquire a verified certificate, paid or free. Two popular examples of free suppliers are StartSSL and Let’s Encrypt. You’re welcome to pick another. Just make sure first the supplier is likely to be supported. Check this list before selecting a CA. Once you’ve picked a CA and validated your identity with them, you can craft your certificate. This frequently starts by generating a CSR (Certificate Signing Request). Generating a CSR is done either through your host machine, or online via the tools provided by the CA.
-
-
Here is an example (PEM format output).
-
-
Using OpenSSL: openssl req -newkey rsa:2048 -keyout yourprivatekey.key -out yoursigningrequest.csr
-
-
-
-
----
-Generating a 2048 bit RSA private keywriting new private key to yourprivatekey.key
-Enter PEM pass phrase: enter a password for your key here
-Verifying - Enter PEM pass phrase: confirm the entered password
------
-You are about to be asked to enter information that will be incorporated
-into your certificate request.
-What you are about to enter is what is called a Distinguished Name or a DN.
-There are quite a few fields but you can leave some blank
-For some fields there will be a default value,If you enter '.',
-the field will be left blank.-----
-Country Name (2 letter code) [AU]:
-State or Province Name (full name) [Some-State]:
-Locality Name (eg, city) []:
-Organization Name (eg, company) [Internet Widgits Pty Ltd]:
-Organizational Unit Name (eg, section) []:
-Common Name (e.g. server FQDN or YOUR name) []: yourbotdomainname
-Email Address []:
-Please enter the following 'extra' attributes
-to be sent with your certificate request
-A challenge password []:
-An optional company name []:
----
---
-Enter keystore password:
-Re-enter new password:
-What is your first and last name? [Unknown]: yourbotdomainname
-What is the name of your organizational unit? [Unknown]:
-What is the name of your organization? [Unknown]:
-What is the name of your City or Locality? [Unknown]:
-What is the name of your State or Province? [Unknown]:
-What is the two-letter country code for this unit? [Unknown]:
-Is CN=test.telegram.org, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
-[no]: yes
-Enter key password for yourbotdomainname
-(RETURN if same as keystore password):
----
-
This generates the initial keystore, from which you can then create a CSR like this:
To validate your certificate the Common Name (CN) has to match your webhook domain. Example, if you’re using https://www.example.com/example.php as a webhook address, the certificate CN has to be www.example.com. So you need an exact match of the FQDN you’re setting for the webhook
-
There is an exception, if you’re using a SAN (Subject Alternative Name) the webhook address can either match the CN of your certificate, OR one of the SANs provided in the certificate. In most cases you’ll be using the CN.
-
Create your CSR and supply the contents of the file to your CA. Most CA’s are kind enough to give you an example command of the input format they expect.
-
cat yoursigningrequest.csrorcat yourbotdomainname.csr Lets you have a look at the CSR we just generated:
-
-
-
-
-
That doesn’t seem to informative, but we can deduce that the file is in PEM format (ASCII base64 encoded) and contains a certificate signing request. Luckily it is possible to look at the human readable contents of the CSR. Use the following commands to double check if all fields are set correctly.
-
-
Using OpenSSL openssl req -text -noout -verify -in yoursigningrequest.csr
-
-
Using Java keytool keytool -printcertreq -v -file yourbotdomainname.csr
-
-
-
Verify your CSR and supply it to your CA to get a certificate. We’ll use StartSSL as an example here. StartSSL allows you to set up to 5 names (SAN), Their intermediate certificate is also needed for a webhook to work, which makes for a nice complete example.
-
Go to the certificates wizard, enter the required hostname(s) for your SSL certificate (this is the CN you’ve also set in the CSR and an optional SAN).
-
-
-
-
-
In the example above we’ve chosen to set a CN (test.telegram.org), but also a SAN (sanexample.telegram.org) The CN given has to match the CN used for generating the CSR. Set your CN (and optional SAN) and copy the contents of the yoursigningrequest.csr file.
-
-
-
-
-
Paste the contents, submit and you’re done.
-
-
-
-
-
Now you can download the created certificate directly. In the example used above you’ll receive a zip file with several PEM certificates. The root, intermediate and yourdomain certificate. You need the intermediate and yourdomain to set a webhook with a StartSSL certificate.
-
You can inspect the set of certificates you’ve just downloaded.
-
-
Here are some example commands:
-
-
Using OpenSSL: openssl x509 -in yourdomain.crt -text -noout
-
-
Using Java keytool: keytool -printcert -v -yourdomain.crt
-
-
Using Windows: StartSSL supplies certificates in PEM format with a .crt extension, on Windows you can view the contents of them with a quick double click. Extract the files or open the “Otherserver.zip” and double click each of the certificates for inspection. The details tab supplies you with extra information. Make sure you have a correct CN in the Subject-field of the yourdomain-certificate. If you're using a SAN, make sure that it is listed in the Subject Alternative Name-field.
-
-
-
-
-
-
-
-
-
With your fresh certificates at hand, you can now continue setting your webhook.
-
-
A self-signed certificate
-
Using a self-signed certificate means you’ll forfeit on the chain of trust backed by a CA. Instead you are the CA. For this to work, a slight difference in setup is required. Because Telegram will have no chain of trust to verify your certificate, you have to use the generated public certificate as an input file when setting the webhook. Keep in mind that the certificate file has to be uploaded as multipart/form data in PEM encoded (ASCII BASE64) format.
-
-
First let’s generate some certificates:
-
-
Using OpenSSL: openssl req -newkey rsa:2048 -sha256 -nodes -keyout YOURPRIVATE.key -x509 -days 365 -out YOURPUBLIC.pem -subj "/C=US/ST=New York/L=Brooklyn/O=Example Brooklyn Company/CN=YOURDOMAIN.EXAMPLE" You’ll end up with 2 files, a private key and the public certificate file. Use YOURPUBLIC.PEM as input file for setting the webhook.
What is your first and last name?
-[test.telegram.org]:
-What is the name of your organizational unit?
-[Unknown]:
-What is the name of your organization?
-[Unknown]:
-What is the name of your City or Locality?
-[Unknown]:
-What is the name of your State or Province?
-[Unknown]:
-What is the two-letter country code for this unit?
-[Unknown]:
-Is CN=test.telegram.org, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?
-[no]: yes
-
Once done you’ll need 2 more commands to export the public certificate file from the generated store (you’ll be using the store for your JVM and the PEM for setting the webhook)
-
-
Convert the JKS to pkcs12 (intermediate step for conversion to PEM): keytool -importkeystore -srckeystore YOURJKS.jks -destkeystore YOURPKCS.p12 -srcstoretype jks -deststoretype pkcs12
Using Windows: Creating a self-signed certificate using Windows native utilities is also possible, although OpenSSL binaries for Windows are available online. certreq -new TEMPLATE.txt RequestFileOut generates a CSR.
-
-
TEMPLATE.txt example file:
-
[NewRequest]
-; At least one value must be set in this section
-Subject = "CN=DOMAIN.EXAMPLE"
-KeyLength = 2048
-KeyAlgorithm = RSA
-HashAlgorithm = sha256
-;MachineKeySet = true
-RequestType = Cert
-UseExistingKeySet=false ;generates a new private key (for export)
-Exportable = true ;makes the private key exportable with the PFX
-
-
-
-
-
A self-signed certificate is generated and installed, to use the certificate for a self-signed webhook you'll have to export it in PEM format.
-
-
Windows continued:
-
-
You can have a look at the certificates in your store with: certutil -store -user my
-
-
To export the installed certificate in DER format (intermediate step for conversion to PEM): certutil -user -store -split my SERIALNUMBER YOURDER.der
-
-
Now you can convert the certificate to PEM: certutil -encode YOURDER.der YOURPEM.pem Remember that only the public certificate is needed as input for the self-signed webhook certificate parameter. certmgr.msc can also be used as a GUI to export the public part of self-signed certificate to PEM.
-
-
-
-
-
After following the above you'll end up with a nice self-signed certificate. You’ll still have to set the webhook, and handle SSL correctly.
-
How do I set a webhook for either type?
-
The setWebhook method is needed for both types. For a verified certificate with a trusted root CA, it’s enough to use the setWebhook method with just the URL parameter.
-
-
A curl example for a verified certificate: curl -F "url=https://<YOURDOMAIN.EXAMPLE>/<WEBHOOKLOCATION>" https://api.telegram.org/bot<YOURTOKEN>/setWebhook
-
-
For a self-signed certificate an extra parameter is needed, certificate, with the public certificate in PEM format as data.
-
-
A curl example for a self-signed certificate: curl -F "url=https://<YOURDOMAIN.EXAMPLE>/<WEBHOOKLOCATION>" -F "certificate=@<YOURCERTIFICATE>.pem" https://api.telegram.org/bot<YOURTOKEN>/setWebhook
-
-
The -F means we’re using the multipart/form-data-type to supply the certificate, the type of the certificate parameter is inputFile. Make sure that you’re supplying the correct type.
-
Both parameters for the setWebhook method are classed as optional. Calling the method with an empty URL parameter can be used to clear a previously set webhook.
-
-
A curl example to clear a previous webhook : curl -F "url=" https://api.telegram.org/bot<YOURTOKEN>/setWebhook
-
-
Keep in mind that the URL parameter starts with https:// when setting a webhook. By default that means we’re knocking at your door on port 443. If you want to use another port (80,88 or 8443), you’ll have to specify the port in the URL parameter.
If you already have a verified certificate and our servers don’t trust your root CA, we have an alternative way for you to set a webhook. Instead of using the setWebhook method without the certificate parameter, you can use the self-signed method. Your CA's root certificate has to be used as an inputFile for the certificate parameter.
-
-
A curl example to supply an untrusted root certificate: curl -F "url=https://<YOURDOMAIN.EXAMPLE>" -F "certificate=@<YOURCAROOTCERTIFICATE>.pem" https://api.telegram.org/bot<YOURTOKEN>/setWebhook Before you can do this, you need the root certificate of your certificate’s CA. Most CA’s supply their root certificates in several different formats (PEM/DER/etc.). Visit your CA’s website, and download the Root certificate indicated for your verified certificate.
-
-
You can use these commands to quickly convert a DER formatted root certificate to PEM:
-
-
Using OpenSSL: openssl x509 -inform der -in root.cer -out root.pem
-
-
Using Java keytool: keytool -import -alias Root -keystore YOURKEYSTORE.JKS -trustcacerts -file ROOTCERT.CER The root certificate needs to be imported in your keystore first: keytool -exportcert -alias Root -file <YOURROOTPEMFILE.PEM> -rfc -keystore YOURKEYSTORE.JKS
-
-
-
Once done, set your webhook with the root-pem-file and you’ll be good to go. If you need more pointers, have a look at the self-signed part of this guide.
-
Supplying an intermediate certificate
-
Once you’ve crafted your certificate, your CA might present you with a nice bundle. Most bundles contain a root certificate, your public certificate and sometimes an intermediate certificate. StartSSL is one of many CA’s that’ll supply such an intermediate beast. This certificate has to be supplied in the chain of certificates you’re presenting to us when we connect to your server. If an intermediate was used to sign your certificate but isn’t supplied to our servers, we won’t be able to verify the chain of trust and your webhook will not work.
-
If your webhook isn’t working and you’re wondering if the chain is complete:
-
-
Check with your certificate provider if you need an intermediate certificate.
-
Verify your certificate chain.
Search online for Symantec crypto report or Qualys ssl.
-Both supply tools to verify your setup.
-
-
-
Here’s an example of a complete chain, note that in this case 2 intermediate certificates have been supplied.
-
-
-
-
-
Even though your browser might not complain when visiting your page, an incomplete chain will not work for your webhook. If your chain is incomplete we have some tips to add them to your current setup:
-
-
Apache: Add the intermediate certificate to the end of the file configured in the SSLCertificateFile directive of your virtual host configuration. If you’re using an older version than Apache 2.4.8, you may use the SSLCertificateChainFile directive instead.
-
-
Nginx: Add the intermediate certificate to the end of the file configured in the ssl_certificate_key directive of your virtual host configuration.
-
-
A quick command for doing this correctly: cat your_domain_name.pem intermediate.pem >> bundle.pem Make sure the order is correct, expect failure otherwise.
The end result of all this is a complete certificate chain, backed by either a root certificate we trust or, in the case of an untrusted root, a root certificate you're supplying to us. Make sure to verify your setup again after adding the intermediate, once done, you're good to go!
-
Testing your bot with updates
-
-
Update examples A set of example updates, which comes in handy for testing your bot.
When using phone.requestCall and phone.acceptCall, specify all library versions supported by the client. The server will merge and choose the best library version supported by both peers, returning only the best value in the result of the callee's phone.acceptCall and in the phoneCallAccepted update received by the caller.
The app must show the message to the user upon receiving this update. In case the popup parameter was passed, the text message must be displayed in a popup alert immediately upon receipt. It is recommended to handle the text as you would an ordinary message in terms of highlighting links, etc. The message must also be stored locally as part of the message history with the user id 777000 (Telegram Notifications).
When was the notification received The message must also be stored locally as part of the message history with the user id 777000 (Telegram Notifications).
String, identical in format and contents to the type field in API errors. Describes type of service message. It is acceptable to ignore repeated messages of the same type within a short period of time (15 minutes).
The user is preparing a message; typing, recording, uploading, etc. This update is valid for 6 seconds. If no repeated update received after 6 seconds, it should be considered that the user stopped doing whatever he's been doing.
For serialization write the constructor id 0x1cb5c415:int, then the number of vector elements - #:int, then, one after another, the # of the elements of the type t, that was implicitly passed to the constructor.
The provided email isn't confirmed, X is the length of the verification code that was just sent to the email: use account.verifyEmail to enter the received verification code and enable the recovery email.
The phone code you provided has expired, this may happen if it was sent to any chat on telegram (if the code is sent through a telegram chat (not the official account) to avoid it append or prepend to the code some chars)
The method returns an auth.CheckedPhone type object with information on whether an account with such a phone number has already been registered, as well as whether invitations were sent to this number (using the auth.sendInvites method).
Returned legacy group chats must be first upgraded to supergroups before they can be set as a discussion group.
-To set a returned supergroup as a discussion group, access to its old messages must be enabled using channels.togglePreHistoryHidden, first.
If enabled, the rating of top peers indicates the relevance of a frequently used peer in a certain category (frequently messaged users, frequently used bots, inline bots, frequently visited channels and so on).
Obtains a list of messages, indicating to which other public channels was a channel message forwarded.
-Will return a list of messages with peer_id equal to the public channel to which this message was forwarded.
Get changelog of current app. Typically, an updates constructor will be returned, containing one or more updateServiceNotification updates with app-specific changelogs.
Generate a login token, for login via QR code. The generated login token should be encoded using base64url, then shown as a tg://login?token=base64encodedtoken URL in the QR code.
Binds a temporary authorization key temp_auth_key_id to the permanent authorization key perm_auth_key_id. Each permanent key may only be bound to one temporary key at a time, binding a new temporary key overwrites the previous one.
Resend the login code via another medium, the phone code type is determined by the return value of the previous auth.sendCode/auth.resendCode: see login for more info.
Optional: notify the server that the user is currently busy in a call: this will automatically refuse all incoming phone calls until the current phone call is ended.
Returned legacy group chats must be first upgraded to supergroups before they can be set as a discussion group. To set a returned supergroup as a discussion group, access to its old messages must be enabled using channels.togglePreHistoryHidden, first.
Notify the user that the sent passport data contains some errors The user will not be able to re-submit their Passport data to you until the errors are fixed (the contents of the field for which you returned the error must change).
Use this if the data submitted by the user doesn't satisfy the standards your service requires for any reason. For example, if a birthday date seems invalid, a submitted document is blurry, a scan shows evidence of tampering, etc. Supply some details in the error message to make sure the user knows how to correct the issues.
Should be called after the user hides the report spam/add as contact bar of a new chat, effectively prevents the user from executing the actions specified in the peer's settings.
Returns an HTTP URL which can be used to automatically log in into translation platform and suggest new emoji replacements. The URL will be valid for 30 seconds after generation
If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the bot will receive an updateBotShippingQuery update. Use this method to reply to shipping queries.
Once the user has confirmed their payment and shipping details, the bot receives an updateBotPrecheckoutQuery update. Use this method to respond to such pre-checkout queries. Note: Telegram must receive an answer within 10 seconds after the pre-checkout query was sent.
Obtains a list of messages, indicating to which other public channels was a channel message forwarded. Will return a list of messages with peer_id equal to the public channel to which this message was forwarded.
Delete the user's account from the telegram servers. Can be used, for example, to delete the account of a user that provided the login code, but forgot the 2FA password and no recovery method is configured.
It remains to describe how types, e.g. values of type Type, are transmitted (serialized). In general, there is nothing unexpected going on here: we have type constructors of various arities (for example, List is an arity-1 constructor, but IntList is a 0-arity constructor); and if we know that a 32-bit “name” is assigned to each type constructor, there are no further questions -- values of type Type are serialized exactly like values of any other recursive type with a defined set of constructors of differing arity.
-
How can a 32-bit “name” be assigned to a type (a type constructor, to be more exact) such as List or IntList?
-It is proposed to use the sum of the names of all of its constructors, plus the CRC32 of the string with the designation of the type's name and all of its parameters such as “IntList = Type” or “List X:Type = Type”. This way, the List constructor’s “name” is the sum of the CRC32s of the three strings "List X:Type = Type", "cons X:Type hd:X tl:List X = List X", and "nil X:Type = List X".
-For “bare” types (which, formally speaking, are subtypes of the corresponding “boxed” type), the situation is somewhat more complicated; the logical negation of the corresponding constructor’s name is used. For built-in bareand boxed types (for example, int and Int), a pseudo-declaration is used (for example, int ? = Int").
-
-
This description is somewhat outdated and may be updated in the future. Specifically, how to treat the ! modifier has not been explained.*
This document describes MTProto v1.0, its status is DEPRECATED. For information on encryption used in up-to-date Telegram clients, kindly see this document.
The protocol is designed for access to a server API from applications running on mobile devices. It must be emphasized that a web browser is not such an application.
-
The protocol is subdivided into three virtually independent components:
-
-
High-level component (API query language): defines the method whereby API queries and responses are converted to binary messages.
-
Cryptographic (authorization) layer: defines the method by which messages are encrypted prior to being transmitted through the transport protocol.
-
Transport component: defines the method for the client and the server to transmit messages over some other existing network protocol (such as, http, https, tcp, udp).
Got questions about this setup? — Check out the Advanced FAQ!
-
-
Note 1
-
Each plaintext message to be encrypted in MTProto always contains the following data to be checked upon decryption in order to make the system robust against known problems with the components:
Telegram's End-to-end encrypted Secret Chats are using an additional layer of encryption on top of the described above. See Secret Chats, End-to-End encryption for details.
-
Brief Component Summary
-
High-Level Component (RPC Query Language/API)
-
From the standpoint of the high-level component, the client and the server exchange messages inside a session. The session is attached to the client device (the application, to be more exact) rather than a specific http/https/tcp connection. In addition, each session is attached to a user key ID by which authorization is actually accomplished.
-
Several connections to a server may be open; messages may be sent in either direction through any of the connections (a response to a query is not necessarily returned through the same connection that carried the original query, although most often, that is the case; however, in no case can a message be returned through a connection belonging to a different session). When the UDP protocol is used, a response might be returned by a different IP address than the one to which the query had been sent.
-
There are several types of messages:
-
-
RPC calls (client to server): calls to API methods
-
RPC responses (server to client): results of RPC calls
-
Message received acknowledgment (or rather, notification of status of a set of messages)
-
Message status query
-
Multipart message or container (a container that holds several messages; needed to send several RPC calls at once over an HTTP connection, for example; also, a container may support gzip).
-
-
From the standpoint of lower level protocols, a message is a binary data stream aligned along a 4 or 16-byte boundary. The first several fields in the message are fixed and are used by the cryptographic/authorization system.
-
Each message, either individual or inside a container, consists of a message identifier (64 bits, see below), a message sequence number within a session (32 bits), the length (of the message body in bytes; 32 bits), and a body (any size which is a multiple of 4 bytes). In addition, when a container or a single message is sent, an internal header is added at the top (see below), then the entire message is encrypted, and an external header is placed at the top of the message (a 64-bit key identifier and a 128-bit message key).
-
A message body normally consists of a 32-bit message type followed by type-dependent parameters. In particular, each RPC function has a corresponding message type. For more detail, see Binary Data Serialization, Mobile Protocol: Service Messages.
-
All numbers are written as little endian. However, very large numbers (2048-bit) used in RSA and DH are written in the big endian format because that is what the OpenSSL library does.
-
Authorization and Encryption
-
Prior to a message (or a multipart message) being transmitted over a network using a transport protocol, it is encrypted in a certain way, and an external header is added at the top of the message which is: a 64-bit key identifier (that uniquely identifies an authorization key for the server as well as the user) and a 128-bit message key. A user key together with the message key defines an actual 256-bit key which is what encrypts the message using AES-256 encryption. Note that the initial part of the message to be encrypted contains variable data (session, message ID, sequence number, server salt) that obviously influences the message key (and thus the AES key and iv). The message key is defined as the 128 lower-order bits of the SHA1 of the message body (including session, message ID, etc.). Multipart messages are encrypted as a single message.
The protocol’s principal drawback is that an intruder passively intercepting messages and then somehow appropriating the authorization key (for example, by stealing a device) will be able to decrypt all the intercepted messages post factum. This probably is not too much of a problem (by stealing a device, one could also gain access to all the information cached on the device without decrypting anything); however, the following steps could be taken to overcome this weakness:
-
-
Session keys generated using the Diffie-Hellman protocol and used in conjunction with the authorization and the message keys to select AES parameters. To create these, the first thing a client must do after creating a new session is send a special RPC query to the server (“generate session key”) to which the server will respond, whereupon all subsequent messages within the session are encrypted using the session key as well.
-
Protecting the key stored on the client device with a (text) password; this password is never stored in memory and is entered by a user when starting the application or more frequently (depending on application settings).
-
Data stored (cached) on the user device can also be protected by encryption using an authorization key which, in turn, is to be password-protected. Then, a password will be required to gain access even to those data.
-
-
Time Synchronization
-
If client time diverges widely from server time, a server may start ignoring client messages, or vice versa, because of an invalid message identifier (which is closely related to creation time). Under these circumstances, the server will send the client a special message containing the correct time and a certain 128-bit salt (either explicitly provided by the client in a special RPC synchronization request or equal to the key of the latest message received from the client during the current session). This message could be the first one in a container that includes other messages (if the time discrepancy is significant but does not as yet result in the client’s messages being ignored).
-
Having received such a message or a container holding it, the client first performs a time synchronization (in effect, simply storing the difference between the server’s time and its own to be able to compute the “correct” time in the future) and then verifies that the message identifiers for correctness.
-
Where a correction has been neglected, the client will have to generate a new session to assure the monotonicity of message identifiers.
-
Transport
-
Enables the delivery of encrypted containers together with the external header (hereinafter, Payload) from client to server and back. There are three types of transport:
-
-
HTTP
-
TCP
-
UDP
-
-
We shall examine the first two types.
-
HTTP Transport
-
Implemented over HTTP/1.1 (with keepalive) running over the traditional TCP Port 80. HTTPS is not used; the above encryption method is used instead.
-
An HTTP connection is attached to a session (or rather, to session + key identifier) specified in the most recent user query received; normally, the session is the same in all queries, but crafty HTTP proxies may corrupt that. A server may not return a message into an HTTP connection unless it belongs to the same session, and unless it is the server’s turn (an HTTP request had been received from the client to which a response has not been sent yet).
-
The overall arrangement is as follows. The client opens one or more keepalive HTTP connections to the server. If one or more messages need to be sent, they are made into a payload which is followed by a POST request to the URL/api to which the payload is transmitted as data. In addition, Content-Length, Keepalive, and Host are valid HTTP headers.
-
Having received the query, the server may either wait a little while (if the query requires a response following a short timeout) or immediately return a dummy response (only acknowledging the receipt of the container). In any case, the response may contain any number of messages. The server may at the same time send out any other messages it might be holding for the session.
-
In addition, there exists a special long poll RPC query (valid for HTTP connections only) which transmits maximum timeout T. If the server has messages for the session, they are returned immediately; otherwise, a wait state is entered until such time as the server has a message for the client or T seconds have elapsed. If no events occur in the span of T seconds, a dummy response is returned (special message).
-
If a server needs to send a message to a client, it checks for an HTTP connection that belongs to the required session and is in the “answering an HTTP request” state (including long poll) whereupon the message is added to the response container for the connection and sent to the user. In a typical case, there is some additional wait time (50 milliseconds) against the eventuality that the server will soon have more messages for the session.
-
If no suitable HTTP connection is available, the messages are placed in the current session’s send queue. However, they find their way there anyway until receipt is explicitly or indirectly confirmed by the client. For the HTTP protocol, sending the next query into the same HTTP connection is regarded as an implicit acknowledgment (not any more, the HTTP protocol also requires that explicit acknowledgments be sent); in other cases, the client must return an explicit acknowledgment within a reasonable time (it can be added to a container for the following request).
-
Important: if the acknowledgment fails to arrive on time, the message can be resent (possibly, in a different container). The parties must autonomously be ready for this and must store the identifiers of the most recent messages received (and ignore such duplicates rather than repeat actions). In order not to have the identifiers stored forever, there exist special garbage collection messages that take advantage of message identifier monotonicity.
-
If the send queue overflows or if messages stay in the queue for over 10 minutes, the server forgets them (or sends them to swap, no genius required). This may happen even faster, if the server is running out of buffer space (for example, because of serious network issues resulting in a large number of connections becoming severed).
-
TCP Transport
-
This is very similar to the HTTP transport. May also be implemented over Port 80 (to penetrate all firewalls) and even use the same server IP addresses. In this situation, the server understands whether HTTP or TCP protocol must be used for the connection, based on the first four incoming bytes (for HTTP, it is POST).
-
When a TCP connection is created, it is assigned to the session (and the authorization key) transmitted in the first user message, and subsequently used exclusively for this session (multiplexing arrangements are not allowed).
-
If a payload (packet) needs to be transmitted from server to client or from client to server, it is encapsulated as follows: 4 length bytes are added at the front (to include the length, the sequence number, and CRC32; always divisible by 4) and 4 bytes with the packet sequence number within this TCP connection (the first packet sent is numbered 0, the next one 1, etc.), and 4 CRC32 bytes at the end (length, sequence number, and payload together).
-
There is an abridged version of the same protocol: if the client sends 0xef as the first byte (important: only prior to the very first data packet), then packet length is encoded by a single byte (0x01..0x7e = data length divided by 4; or 0x7f followed by 3 length bytes (little endian) divided by 4) followed by the data themselves (sequence number and CRC32 not added). In this case, server responses look the same (the server does not send 0xefas the first byte).
-
In case 4-byte data alignment is needed, an intermediate version of the original protocol may be used: if the client sends 0xeeeeeeee as the first int (four bytes), then packet length is encoded always by four bytes as in the original version, but the sequence number and CRC32 are omitted, thus decreasing total packet size by 8 bytes.
-
The full, the intermediate and the abridged versions of the protocol have support for quick acknowledgment. In this case, the client sets the highest-order length bit in the query packet, and the server responds with a special 4 bytes as a separate packet. They are the 32 higher-order SHA1 bits of the encrypted portion of the packet with the most significant bit set to make clear that this is not the length of a regular server response packet; if the abridged version is used, bswap is applied to these four bytes.
-
There are no implicit acknowledgments for the TCP transport: all messages must be acknowledged explicitly. Most frequently, acknowledgments are placed in a container with the next query or response if it is transmitted in short order. For example, this is almost always the case for client messages containing RPC queries: the acknowledgment normally arrives with the RPC response.
-
In the event of an error, the server may send a packet whose payload consists of 4 bytes as the error code. For example, Error Code 403 corresponds to situations where the corresponding HTTP error would have been returned by the HTTP protocol.
Telegram Passport is a unified authorization method for services that require personal identification. Users can upload their documents once, then instantly share their data with services that require real-world ID (finance, ICOs, etc.). Telegram doesn't have access to the users' personal information thanks to end-to-end encryption.
-
Overview
-
From the perspective of a service that requires real-world ID, the process looks like this:
-
-
A user presses "Log in with Telegram" on your website or in your app.
The user accepts your privacy policy and agrees to share their data.
-
The user's Telegram app downloads and decrypts the data you requested from the end-to-end encrypted storage on Telegram.
-
If some of the data you requested is missing, the user can add it to their Telegram Passport at this point.
-
The user's app encrypts the data with your public key and sends it to you.
-
You decrypt the data, check it for errors and re-request any missing or invalid information.
-
You sign the user up for your service. Tada!
-
-
Check out this example to see Telegram Passport in action.
-
-
To learn more about Telegram Passport from the perspective of a user, please see this blog post and the technical MTProto documentation.
-See this page if you're interested in encryption algorithms used on Telegram's side.
Added support for requesting certified English translations for documents (see Fields; new field translation also added to the SecureValue object). Note: Please only request translations after you have received a valid document that requires one.
-
Added support for requesting names in the language of the user's country of residence (if other than English). New fields first_name_native, last_name_native and middle_name_native added to the PersonalDetails object.
-
Replaced the payload parameter with the new parameter nonce, which serves the same function, to make the purpose more obvious (see Request Parameters and the Credentials object).
-
Updated the example page to support the new functionality.
-
-
Setting Up Telegram Passport
-
To integrate Telegram Passport into your login or verification flow, you need a working Telegram bot (see this page for information on how to get one).
-
To request data from Telegram Passport users, your bot will need to generate a pair of encryption keys.
-
Generating a private key
-
First, use a console to generate a private key:
-
openssl genrsa 2048 > private.key
-
WARNING: Keep your private key SECRET!
-
Generating your public key
-
Then use the console to print the corresponding public key:
-
openssl rsa -in private.key -pubout
-
Use the /setpublickey command with @BotFather to connect this public key with your bot.
-
Privacy Policy
-
Add a link to your Privacy Policy by using the /setprivacypolicy command. Users will see this link when offered to authorize you to access their data.
-
Requesting Information
-
SDK
-
To request information stored in a Telegram Passport, use one of these SDKs:
List of elements one of which must be provided; must contain either several of “passport”, “driver_license”, “identity_card”, “internal_passport” or several of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
-
-
-
selfie
-
Boolean
-
Optional. Use this parameter if you want to request a selfie with the document from this list that the user chooses to upload.
-
-
-
translation
-
Boolean
-
Optional. Use this parameter if you want to request a translation of the document from this list that the user chooses to upload. Note: We suggest to only request translations after you have received a valid document that requires one.
-
-
-
-
PassportScopeElementOne
-
This object represents one particular element that must be provided. If no options are needed, String can be used instead of this object to specify the type of the element.
-
-
-
-
Field
-
Type
-
Description
-
-
-
type
-
String
-
Element type. One of "personal_details", "passport", "driver_license", "identity_card", "internal_passport", "address", "utility_bill", "bank_statement", "rental_agreement", "passport_registration", "temporary_registration", "phone_number", "email"
-
-
-
selfie
-
Boolean
-
Optional. Use this parameter if you want to request a selfie with the document as well. Available for "passport", "driver_license", "identity_card" and "internal_passport"
-
-
-
translation
-
Boolean
-
Optional. Use this parameter if you want to request a translation of the document as well. Available for "passport", "driver_license", "identity_card", "internal_passport", "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration". Note: We suggest to only request translations after you have received a valid document that requires one.
-
-
-
native_names
-
Boolean
-
Optional. Use this parameter to request the first, last and middle name of the user in the language of the user's country of residence. Available for "personal_details"
-
-
-
-
You can also use the special type "id_document" as an alias for one of "passport", "driver_license", "identity_card" and the special type "address_document" as an alias for one of "utility_bill", "bank_statement", "rental_agreement".
-So {"type":"id_document",selfie:true} is equal to {"one_of":["passport","driver_license","identity_card"],selfie:true}.
-
Fields
-
Your bot can request personal details, one or several types of identity document, residential address, one or several types of proof of address document, a phone number, or an email address. You can also request optional selfies with the document and certified English translations of the document.
-This is just a list of data types that can be requested, and the encrypted objects that will contain such data.
-
-
Note: We suggest to only request English translations after you have received a valid document that requires one.
Country of residence (ISO 3166-1 alpha-2 country code)
-
-
-
first_name_native
-
String
-
First Name in the language of the user's country of residence
-
-
-
last_name_native
-
String
-
Last Name in the language of the user's country of residence
-
-
-
middle_name_native
-
String
-
Optional. Middle Name in the language of the user's country of residence
-
-
-
-
ResidentialAddress
-
This object represents a residential address.
-
-
-
-
Field
-
Type
-
Description
-
-
-
street_line1
-
String
-
First line for the address
-
-
-
street_line2
-
String
-
Optional. Second line for the address
-
-
-
city
-
String
-
City
-
-
-
state
-
String
-
Optional. State
-
-
-
country_code
-
String
-
ISO 3166-1 alpha-2 country code
-
-
-
post_code
-
String
-
Address post code
-
-
-
-
IdDocumentData
-
This object represents the data of an identity document.
-
-
-
-
Field
-
Type
-
Description
-
-
-
document_no
-
String
-
Document number
-
-
-
expiry_date
-
String
-
Optional. Date of expiry, in DD.MM.YYYY format
-
-
-
-
PassportFile
-
This object represents a PassportFile related to a document. The file is up to 10MB in size and in the .jpg format.
-
Receiving information
-
When the user confirms your request by pressing the 'Authorize' button, the Bot API sends an Update with the field passport_data to the bot that contains encrypted Telegram Passport data.
-
-
Note that all base64-encoded fields should be decoded before use.
-
-
Decrypting data
-
To decrypt the received data, first, decrypt the credentials contained in EncryptedCredentials.
-
-
-
Decrypt the credentials secret ( secret field in EncryptedCredentials) using your private key (set OAEP padding option, e.g. OPENSSL_PKCS1_OAEP_PADDING in PHP)
-
-
-
Use this secret and the credentials hash ( hash field in EncryptedCredentials) to calculate credentials_key and credentials_iv as described below:
Decrypt the credentials data ( data field in EncryptedCredentials) by AES256-CBC using these credentials_key and credentials_iv. IMPORTANT: At this step, make sure that the credentials hash is equal to SHA256( credentials_data )
-
-
-
Credentials data is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of this padding (including this byte). Remove the padding to get the data.
-
-
-
-
Note that all hashes represent as raw binary data, not hexits
Optional. Credentials for encrypted temporary registration
-
-
-
-
SecureValue
-
This object represents the credentials required to decrypt encrypted values. All fields are optional and depend on the type of fields that were requested.
Optional. Credentials for encrypted Telegram Passport data. Available for "personal_details", "passport", "driver_license", "identity_card", "internal_passport" and "address" types.
Optional. Credentials for an encrypted selfie of the user with a document. Available for "passport", "driver_license", "identity_card" and "internal_passport".
Optional. Credentials for an encrypted translation of the document. Available for "passport", "driver_license", "identity_card", "internal_passport", "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration".
Optional. Credentials for encrypted files. Available for "utility_bill", "bank_statement", "rental_agreement", "passport_registration" and "temporary_registration" types.
-
-
-
-
DataCredentials
-
These credentials can be used to decrypt encrypted data from the data field in EncryptedPassportElement.
-
-
-
-
Field
-
Type
-
Description
-
-
-
data_hash
-
String
-
Checksum of encrypted data
-
-
-
secret
-
String
-
Secret of encrypted data
-
-
-
-
-
-
To decrypt data, use the corresponding secret and data_hash from DataCredentials as described below:
Use AES256-CBC with this data_key and data_iv to decrypt the data (the data field in EncryptedPassportElement). IMPORTANT: At this step, make sure that data_hash from the credentials is equal to SHA256( data ).
-
-
-
The data is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of the padding (including this byte). Remove padding to get the data.
These credentials can be used to decrypt encrypted files from the front_side, reverse_side, selfie, files and translation fields in EncryptedPassportElement.
-
-
-
-
Field
-
Type
-
Description
-
-
-
file_hash
-
String
-
Checksum of encrypted file
-
-
-
secret
-
String
-
Secret of encrypted file
-
-
-
-
-
-
To decrypt the file, use the corresponding secret and file_hash from FileCredentials as described below:
Download the encrypted file using the getFile method.
-
-
-
Use AES256-CBC with this file_key and file_iv to decrypt the content of the file. IMPORTANT: At this step, make sure that file_hash from the credentials is equal to SHA256( file_content ).
-
-
-
The content of the file is padded with 32 to 255 random padding bytes to make its length divisible by 16 bytes. The first byte contains the length of the padding (including that byte). Remove padding to get the file content.
-
-
-
Fixing errors
-
If the data you received contains errors, the bot can use the setPassportDataErrors method to inform the user and request information again. The user will not be able to resend the data, until all errors are fixed.
The Android SDK helps you easily integrate Telegram Passport requests into your Android-based apps. Check out our GitHub repository to see samples using this SDK.
-
Installation
-
Installing from Maven
-
Telegram Passport SDK is available from the Maven repository.
-Add this line to the dependencies section in your build.gradle:
-
compile 'org.telegram:passport:1.1'
-
and sync your project.
-
Adding as a module
-
Download the library, unzip it and copy the library project to the root of your project directory (the one with settings.gradle and gradle.properties). Then, make the following changes to your Gradle scripts.
-
In settings.gradle, add ':telegrampassport' to includes:
-
include ':app', ':telegrampassport'
-
In the build.gradle file for your app, add this line to the dependencies section:
-
compile ':telegrampassport'
-
and sync your project.
-
Usage
-
Adding the button
-
The SDK provides the "Log in with Telegram" button which we recommend using for a consistent user experience across different apps. You can either add it from your Java code:
-
TelegramLoginButton telegramButton;
-// ...
-telegramButton=new TelegramLoginButton(this);
-// Optionally you can change the roundness of the button corners
-// to better fit your design.
-telegramButton.setCornerRoundness(1f);
-viewGroupOfSomeSort.addView(telegramButton, ViewGroup.LayoutParams.WRAP_CONTENT, ViewGroup.LayoutParams.WRAP_CONTENT);
The button doesn't do anything by itself; you need to set an OnClickListener on it to start the authorization flow (replace the comments with actual parameters):
-
private static final int TG_PASSPORT_RESULT=352; // this can be any integer less than 0xFFFF
-// ...
-telegramButton.setOnClickListener(new View.OnClickListener(){
-@Override
-public void onClick(View view){
- TelegramPassport.AuthRequest req=new TelegramPassport.AuthRequest();
- req.botID=/* your bot ID here */;
- req.publicKey=/* your bot public key here */;
- req.nonce=/* a unique nonce to pass to the bot server */;
- // Request either a passport or an ID card with selfie, a driver license, personal details with
- // name as it appears in the documents, address with any address document, and a phone number.
- // You could also pass a raw JSON object here if that's what works better for you
- // (for example, if you already get it from your server in the correct format).
- req.scope=new PassportScope(
- new PassportScopeElementOneOfSeveral(PassportScope.PASSPORT, PassportScope.IDENTITY_CARD).withSelfie(),
- new PassportScopeElementOne(PassportScope.PERSONAL_DETAILS).withNativeNames(),
- PassportScope.DRIVER_LICENSE,
- PassportScope.ADDRESS,
- PassportScope.ADDRESS_DOCUMENT,
- PassportScope.PHONE_NUMBER
- );
- TelegramPassport.request(MyActivity.this, req, TG_PASSPORT_RESULT);
-}});
-
If you need more control over the process, the TelegramPassport class contains several more methods:
-
-
getAuthIntent(AuthParams) returns an Intent for you to use in startActivityForResult if you need to do that in some special way. Be sure to check that an app is present that can handle this intent before starting it by using PackageManager or intent.resolveActivity.
-
showAppInstallAlert(Activity) shows an alert that the user needs to install Telegram in order to continue. This is intended to be used together with the previous method for the cases when the app isn't installed.
-
-
Handling the result
-
The result is delivered via the onActivityResult method in your activity with the request code you passed to TelegramPassport.request. Currently, the only meaningful parameter is resultCode, which is RESULT_OK if the authorization was successful and RESULT_CANCELED otherwise.
TDLib (Telegram Database Library) is a cross-platform, fully functional Telegram client. We designed it to help third-party developers create their own custom apps using the Telegram platform.
Cross-platform. TDLib can be used on Android, iOS, Windows, macOS, Linux, WebAssembly, FreeBSD, Windows Phone, watchOS, tvOS, Tizen, Cygwin. It should also work on other *nix systems with or without minimal effort.
-
Multilanguage. TDLib can be easily used with any programming language that is able to execute C functions. Additionally it already has native bindings to Java (using JNI) and C# (using C++/CLI).
-
Easy to use. TDLib takes care of all network implementation details, encryption and local data storage.
-
High-performance. In the Telegram Bot API, each TDLib instance handles more than 24,000 active bots simultaneously.
-
Well-documented. All TDLib API methods and public interfaces are fully documented.
-
Consistent. TDLib guarantees that all updates will be delivered in the right order.
-
Reliable. TDLib remains stable on slow and unreliable Internet connections.
-
Secure: All local data is encrypted using a user-provided encryption key.
-
Fully-asynchronous. Requests to TDLib don't block each other or anything else, responses will be sent when they are available.
Messages with animated stickers can have a compressed svg (< 300 bytes) to show the outline of the sticker before fetching the actual lottie animation.
A basic bare type, the values of which correspond to single-element sequences, i.e. numbers from -2^31 to 2^31-1 which in this case represent themselves.
A basic bare type. Values of type string look differently depending on the length L of the string being serialized:
-
-
If L <= 253, the serialization contains one byte with the value of L, then L bytes of the string followed by 0 to 3 characters containing 0, such that the overall length of the value be divisible by 4, whereupon all of this is interpreted as a sequence of int(L/4)+1 32-bit little-endian integers.
-
If L >= 254, the serialization contains byte 254, followed by 3 bytes with the string length L in little-endian order, followed by L bytes of the string, further followed by 0 to 3 null padding bytes.
-
-
All strings passed to the API must be encoded in UTF-8. When arbitrary byte sequences have to be serialized, bytes alias is to be used.
Basic bare type. It is an alias of the string type, with the difference that the value may contain arbitrary byte sequences, including invalid UTF-8 sequences.
-
When computing crc32 for a constructor or method it is necessary to replace all byte types with string types.
Farewell to typos! Starting today, you can edit the text of your messages after sending them. This works across all Telegram chats, including groups and one-on-one conversations.
-
-
-
Edit messages
-
-
-
Simply tap and hold on a message, then press ‘Edit’. If you're on desktop, press the up arrow button to edit your last message. The messages will display a small ‘edited’ label so that it's easy to tell which were altered.
-
New Mentions
-
Mentioning other people in groups is handy since it sends them a notification about your message even if they muted the group. Starting today, you can mention any members in a group – even if they don't have a username. Just type the @ symbol and select whoever you would like to address. Easy!
-
-
-
Mention group members
-
-
-
People List
-
Speaking of addressing people, you can now get to your recent chats much faster using the new People list in Search.
-
-
-
Recent chats
-
-
-
-
Bot Attachments
-
We've also made it easier for you to access your favorite inline bots. Simply scroll down the attachment menu – and there they are. The more you use them, the higher they will climb.
-
-
-
Bots in attachment menu
-
-
-
Naturally, you will only see inline bots in the attachment menu if you used them at least once. Try @youtube, @gif or @imdb if you don't know where to start. Check out this post for more info on how to use inline bots.
-
Interface Improvements
-
We‘ve added quick sharing buttons to forwarded messages from bots, channels, and public groups. Notifications about messages with stickers will now show the relevant emoji so that you’ll know the general idea at first glance.
-
-
-
Scroll to bottom
-
-
-
Last but not least, if you're on iOS, your app now remembers the scroll position in chats when switching to a different chat and back. And scrolling up in a chat summons a new button that will send you back to the bottom in one tap. This button also displays a handy unread message counter if new ones are waiting for you there.
-
-
-
And that's it for today. Stay tuned for more updates coming soon!
Bots became an integral part of Telegram for many users, but communication with them wasn't always easy. You had to send them messages in separate chats or add them to your groups. Today we are introducing a quicker way to contact bots.
-
With the new inline mode, bots become omnipresent and can be used as a tool in any of your chats, groups or channels – it doesn't matter, whether the bot is a member or not. Inline bots can help you with dozens of different tasks, like quickly sending relevant GIFs, pictures from the Web, YouTube videos, Wikipedia articles, etc.
-
-
-
-
-
-
-
How does it work?
-
We've created several sample bots for you to try out: @gif, @vid, @pic, @bing, @wiki, @imdb and @bold. To see them in action, simply type one of their @usernames in the message field in any chat, then type some keywords. The bot will offer you relevant content.
-
-
-
-
-
-
-
-
Tap on an item to instantly send it to the chat. This way you can share stuff from bots without any hassle. Inline bots don't see any messages in your chats – they only receive what you type after their username in the input field.
-
-
-
-
-
-
-
Tap on ‘via @username’ to send a new request to the bot. Recently used inline bots will also show up in the suggestion box when you type @ in the input field in any chat.
-
A new dimension for bots
-
Like pretty much everything else at Telegram, inline bots are part of an open platform, available for free to every developer in the world starting today. Hundreds of new inline bots are sure to arrive once developers start supporting the new mode.
-
If you are a developer, take a look at our Introduction to Inline Bots. Also, feel free to subscribe to our official @BotNews channel to stay up to date on platform news.
Polls 2.0: Visible Votes, Multiple Answers, and Quiz Mode
-
-
-
-
-
-
-
-
-
-
Since we first added polls for groups and channels, they've been used for everything from deciding where to have lunch to organizing leaderless protests. Today we're expanding the range of possibilities with three new kinds of Telegram polls.
-
-
-
-
-
Visible Votes
-
Previously, all polls on Telegram were anonymous. With this update, you can create polls that allow everyone in the group to see who voted for what. Now you will know exactly which friends you disagree with on the matter of pineapple and pizza.
-
-
-
-
-
Naturally, you can still create anonymous polls to make sure nobody finds out it was you who voted for broccoli instead of cookies.
-
Multiple Answers
-
One of the best ways to settle the score is with polls that allow people to select multiple answers. Scheduling events, or choosing a playlist of songs for a party – sometimes you need more than one choice.
-
-
-
-
-
Our aunt who has a knack for statistics and exploring bizarre correlations kept asking for this feature – and we just couldn't say no. (33% of developers who didn't refuse this request were also found to be addicted to cheese.)
-
Quiz Mode
-
For the game show guru and “Who Wants To Be A Millionaire” contestant in all of us, polls now have Quiz Mode. Such polls have one correct answer and can power anything from trivia games to public service exams.
-
-
-
-
-
As if guessing right wasn't sweet enough, correct answers will trigger a shower of confetti.
-
Creating Polls
-
Polls can be created in groups or channels (they feel lonely in one-on-one chats). Simply choose the “Poll” option in the attachment menu. Type in your question, add answer options, choose the settings that fit your purpose best – and you're ready to go:
-
-
-
-
-
Bot API and Quiz Bot
-
All the new poll types are supported in today's update to our Bot API, so bot developers can build on this new functionality.
-
As an example, we've created a Quiz Bot that lets you create multi-question quizzes and share them with others. It also lets you add text or media before questions to help create exam-style prompts with graphs and tables – or better yet, your own Know Your Meme tests.
-
Once your quiz is ready, you can share it to a group or channel – or invite users to answer questions privately, in a chat with the bot. To see how this works, try our demo quiz: Who is Who in the 'Great Minds' sticker pack.
-
-
-
-
-
The bot will keep tabs on how many questions users got right and how much time it took them to complete the quiz. It also keeps a global leaderboard for each quiz you create.
-
Message Corners
-
In addition to the new polls, our apps just got a new visual setting. If you find your Telegram messages too hip to be square (or round, depending on your platform), you can tweak the appearance of message bubbles in Settings:
-
-
-
-
-
Download Progress Counters on Android
-
Just like on iOS, Android users can now see exact progress counters when downloading or uploading files – if they're in the mood to count bits and bytes.
-
-
-
-
-
And that's it for today. Here's to a good new year full of updates. Stay tuned!
Telegram is a messaging app with a focus on speed and security, it’s super-fast, simple and free. You can use Telegram on all your devices at the same time — your messages sync seamlessly across any number of your phones, tablets or computers. Telegram has over 500 million monthly active users and is one of the 10 most downloaded apps in the world.
-
With Telegram, you can send messages, photos, videos and files of any type (doc, zip, mp3, etc), as well as create groups for up to 200,000 people or channels for broadcasting to unlimited audiences. You can write to your phone contacts and find people by their usernames. As a result, Telegram is like SMS and email combined — and can take care of all your personal or business messaging needs. In addition to this, we support end-to-end encrypted voice and video calls, as well as voice chats in groups for thousands of participants.
-
-
Follow our Tips Channel to learn more about Telegram features.
-
-
Q: Who is Telegram for?
-
Telegram is for everyone who wants fast and reliable messaging and calls. Business users and small teams may like the large groups, usernames, desktop apps and powerful file sharing options.
In case you're more into pictures, Telegram has animated gif search, a state of the art photo editor, and an open sticker platform (find some cool stickers here or here). What's more, there is no need to worry about disk space on your device. With Telegram's cloud support and cache management options, Telegram can take up nearly zero space on your phone.
-
Those looking for extra privacy should check out our advanced settings and rather revolutionary policy. And if you want secrecy, try our device-specific Secret Chats with self-destructing messages, photos, and videos — and lock your app with an additional passcode.
Unlike WhatsApp, Telegram is a cloud-based messenger with seamless sync. As a result, you can access your messages from several devices at once, including tablets and computers, and share an unlimited number of photos, videos and files (doc, zip, mp3, etc.) of up to 2 GBeach.
-
Telegram needs less than 100 MB on your device – you can keep all your media in the cloud without deleting things – simply clear your cache to free up space.
-
Thanks to Telegram's multi-data center infrastructure and encryption, is faster and way more secure. On top of that, private messaging on Telegram is free and will stay free — no ads, no subscription fees, forever.
-
Telegram's API and code is open, and developers are welcome to create their own Telegram apps. We also have a Bot API, a platform for developers that allows anyone to easily build specialized tools for Telegram, integrate any services, and even accept payments from users around the world.
-
And that's just the tip of the iceberg.
-
-
Follow our Tips Channel to learn more about Telegram features.
-
-
Q: How old is Telegram?
-
Telegram for iOS was launched on August 14, 2013. The alpha version of Telegram for Android officially launched on October 20, 2013. More and more Telegram clients appear, built by independent developers using Telegram's open platform.
-
Q: Which devices can I use?
-
You can use Telegram on smartphones, tablets, and even computers. We have apps for iOS (9.0 and above), Android (4.1 and up), a native macOS app and a universal desktop app for Windows, macOS, and Linux. Telegram Web can also help to quickly do something on the go.
-
-
You can log in to Telegram from as many of your devices as you like — all at the same time. Just use your main mobile phone number to log in everywhere, your cloud chats will sync instantly.
-
-
The Telegram API is open for developers, should you want to build your own applications for other platforms.
-
Q: Who are the people behind Telegram?
-
Telegram is supported by Pavel Durov and his brother Nikolai. Pavel supports Telegram financially and ideologically while Nikolai's input is technological. To make Telegram possible, Nikolai developed a unique custom data protocol, which is open, secure and optimized for work with multiple data-centers. As a result, Telegram combines security, reliability and speed on any network.
Most of the developers behind Telegram originally come from St. Petersburg, the city famous for its unprecedented number of highly skilled engineers. The Telegram team had to leave Russia due to local IT regulations and has tried a number of locations as its base, including Berlin, London and Singapore. We’re currently happy with Dubai, although are ready to relocate again if local regulations change.
-
Q: Will you have ads in my private chats and groups? Or sell my data? Or steal my beloved and enslave my children?
We believe in fast and secure messaging that is also 100% free.
-
Our founder and CEO Pavel Durov, who financed Telegram throughout most of its history, has outlined a strategy to make Telegram sustainable in this post.
-
While Telegram will introduce monetization in 2021 to pay for the infrastructure and developer salaries, making profits will never be an end-goal for us.
-
Q: What are your thoughts on internet privacy?
-
We think that the two most important components of Internet privacy should be:
-
-
Protecting your private conversations from snooping third parties, such as officials, employers, etc.
-
Protecting your personal data from third parties, such as marketers, advertisers, etc.
-
-
Telegram's aim is to create a truly free messenger, with a revolutionary privacy policy.
-
Q: What about GDPR?
-
The General Data Protection Regulation (GDPR) came into force in Europe on May 25, 2018. Since taking back our right to privacy was the reason we made Telegram, there wasn't much we had to change. We don’t use your data for ad targeting, we don’t sell it to others, and we're not part of any mafia family “family of companies.”
-
Telegram only keeps the information it needs to function as a feature-rich cloud service. For example, your cloud chats – so that you can access them from any devices without using third-party backups, or your contacts – so that you can rely on your existing social graph when messaging people on Telegram. Please see our Privacy Policy for more information.
Request a copy of all your data that Telegram stores.
-
Contact us about Data Privacy.
-
-
Q: There's illegal content on Telegram. How do I take it down?
-
All Telegram chats and group chats are private amongst their participants. We do not process any requests related to them.
-
But sticker sets, channels, and bots on Telegram are publicly available. If you find sticker sets or bots on Telegram that you think are illegal, please ping us at abuse@telegram.org.
-
You can also use the 'report' buttons right inside our apps, see this post on our official @ISISwatch channel for details.
-
-
Note: If a scammer is pretending to be you, contact @NoToScam
-
-
Q: A bot or channel is infringing on my copyright. What do I do?
-
All Telegram chats and group chats are private amongst their participants. We do not process any requests related to them. But sticker sets, channels, and bots on Telegram are publicly available.
-
If you see a bot, channel, or sticker set that is infringing on your copyright, kindly submit a complaint to dmca@telegram.org. Please note that such requests should only be submitted by the copyright owner or an agent authorized to act on the owner’s behalf.
-
Q: Wait! 0_o Do you process take-down requests from third parties?
-
Our mission is to provide a secure means of communication that works everywhere on the planet. To do this in the places where it is most needed (and to continue distributing Telegram through the App Store and Google Play), we have to process legitimate requests to take down illegal public content (e.g., sticker sets, bots, and channels) within the app. For example, we can take down sticker sets that violate intellectual property rights or porn bots.
-
User-uploaded stickers sets, channels, and bots by third-party developers are not part of the core Telegram UI. Whenever we receive a complaint at abuse@telegram.org or dmca@telegram.org regarding the legality of public content, we perform the necessary legal checks and take it down when deemed appropriate.
-
Please note that this does not apply to local restrictions on freedom of speech. For example, if criticizing the government is illegal in some country, Telegram won't be a part of such politically motivated censorship. This goes against our founders' principles. While we do block terrorist (e.g. ISIS-related) bots and channels, we will not block anybody who peacefully expresses alternative opinions.
-
Q: My bot or sticker set was banned unfairly, what do I do?
-
If you think we banned your bot, channel, or sticker set for no apparent reasons, drop us a line at abuse@telegram.org.
-
Q: Do you process data requests?
-
Secret chats use end-to-end encryption, thanks to which we don't have any data to disclose.
-
To protect the data that is not covered by end-to-end encryption, Telegram uses a distributed infrastructure. Cloud chat data is stored in multiple data centers around the globe that are controlled by different legal entities spread across different jurisdictions. The relevant decryption keys are split into parts and are never kept in the same place as the data they protect. As a result, several court orders from different jurisdictions are required to force us to give up any data.
-
Thanks to this structure, we can ensure that no single government or block of like-minded countries can intrude on people's privacy and freedom of expression. Telegram can be forced to give up data only if an issue is grave and universal enough to pass the scrutiny of several different legal systems around the world.
-
To this day, we have disclosed 0 bytes of user data to third parties, including governments.
-
Telegram Basics
-
-
Follow our Tips Channel to learn more about Telegram features.
-
-
Q: Who can I write to?
-
You can write to people who are in your phone contacts and have Telegram. Another way of contacting people is to type their Telegram username into the search field – you don't need to know their phone number to do this.
-
Q: Who can contact me?
-
People can contact you on Telegram if they know your phone number or if you message them first.
-
If they don't know your phone number, they can find you in these cases:
-
-
When you both are members of the same group.
-
If you set a public username. Others can use Global Search and find you by your username.
-
If you opt-in to appear in the People Nearby section (this is turned off by default).
-
-
Q: How do I know who in my contacts has Telegram?
-
Your contacts, who have Telegram, are shown at the top of your Contacts. They also have pictures.
-
Q: How do I invite my friends?
-
iOS: The basic invitations are simple SMS messages. They will be charged as standard outgoing SMS by your carrier (unless sent via iMessage). Naturally, you have other options to bring your friends here. Try sending them a download link via any other messaging service: email, Facebook, WhatsApp, an actual telegram — you name it. The link: https://telegram.org/dl/
-
Android: Open the app menu (swipe right in chat list) > Invite Friends. Then choose an application via which you would like to send out invitations.
-
-
You can give your friends a t.me link with your username so that they can easily find you on Telegram even if they don't have your phone number.
-
-
Q: What do the check marks mean?
-
One check — message delivered to the Telegram cloud and your friend has been notified if he allows notifications. Two checks — message read (your friend opened Telegram and opened the conversation with the message).
-
We don't have a 'delivered to device' status for messages because Telegram can run on as many devices as you want. So which particular one would that check mean?
Remember that you won't see Last Seen timestamps for people with whom you don't share your own. You will, however, see an approximate last seen value. This keeps stalkers away but makes it possible to understand whether a person is reachable over Telegram. There are four possible approximate values:
-
-
Last seen recently — covers anything between 1 second and 2-3 days
-
Last seen within a week — between 2-3 and seven days
-
Last seen within a month — between 6-7 days and a month
-
Last seen a long time ago — more than a month (this is also always shown to blocked users)
-
-
Q: Who can see me 'online'?
-
The last seen rules apply to your online status as well. People can only see you online if you're sharing your last seen status with them.
-
There are some exceptions because sometimes it is obvious that you are online. Regardless of the last seen settings, people will see you online for a brief period (~30 seconds) if you do the following:
-
-
Send them a message in a one-on-one chat or in a group where you both are members.
-
Read a message they sent you in a one-on-one chat.
-
Broadcast a “typing…” status to their chat with you or to a group where you both are members.
-
-
If you're not sharing your last seen timestamp with someone and don't do anything of the above, they'll never see you online. Another way of achieving this is to block that person.
-
Q: What is People Nearby?
-
People Nearby is an optional feature that allows Telegram users to explore local groups, find friends to chat with in their area, or quickly exchange contacts with people who are close.
-
You can find it in Contacts > Find People Nearby, as well as directly in the side menu on Android.
-
While you have the People Nearby section open on your screen, people who are very close will be able to see you there. If you don't open the section, others will never see you in 'People Nearby'.
-
You can also choose to permanently add your profile to the list of nearby people by tapping Make Myself Visible. After becoming visible, you can remove your profile from the list at any time by tapping Stop Showing Me.
-
-
Note: People Nearby is never turned on by default – users must manually enable it. If you are receiving messages from someone you don't know, see Q: Who can contact me?
-
-
Q: Can I delete my messages?
-
Yes. You can always delete any messages you sent or received for both sides in any one-on-one conversation (in groups, it's still your own messages only). You can also clear the entire chat history on both ends. On Telegram, deleted messages do not leave a mark in the chat.
-
-
-
-
-
Together with privacy settings for forwarded messages, this makes exchanging Telegram messages similar to talking face to face (without a tape recorder). As a result, users no longer need to worry about the data accumulating in their chats over the years. Both parties in a conversation have full control over what does and what doesn't belong to their online identity.
If you want more participants, try starting a Voice Chat in one of the groups you created. Voice Chats add a live layer of ephemeral talk to the group. They can be used as virtual office spaces for teams or informal lounges for any community. While Voice Chats are not group calls, they can achieve similar goals.
-
Q: How can I use emoticons?
-
Type one word in your input field to get relevant emoji suggestions. You can also type “:” followed by any keyword to open emoji search – like :heart.
-
You can suggest missing keywords for emoji in your language using this interface (this will open suggestions for English, don't forget to change to your language in the left menu).
-
Groups and Channels
-
Q: What makes Telegram groups cool?
-
Telegram groups can have up to 200,000 members each and are extremely powerful communication tools. Here are a few key features that make them stand out in the messaging world:
-
Unified history Edit your messages after posting, delete them so that they disappear for everyone.
-
Cross-platform availability Access your messages anytime, from any number of your mobile or desktop devices.
-
Instant search Find the message you're looking for, even among millions. Filter by sender to make searching easier.
-
Replies, mentions, hashtags Easily trace a conversation and keep communication efficient, no matter the group size.
-
Smart notifications Mute the group to get notifications only when people mention you or reply to your messages.
-
Pinned messages You can pin any message to be displayed at the top of the chat screen. All members will get a notification — even if they muted ordinary messages from your group.
-
Moderation tools Appoint administrators that can mass-delete messages, control membership, and pin important messages. Define their admin privileges with granular precision.
-
Group permissions Set default permissions to restrict all members from posting specific kinds of content. Or even restrict members from sending messages altogether – and let the admins chat amongst themselves while everybody else is watching.
-
File sharing Send and receive files of any type, up to 2 GB in size each, access them instantly on your other devices.
-
Public groups Get a short link for your group and make it public, like t.me/publictestgroup. This way, anybody can view the group's entire chat history and join to post messages.
-
Customization via bots Create custom tools for any specific needs using our Bot API and Inline Bots.
-
Q: What's the difference between groups and channels?
-
Telegram groups are ideal for sharing stuff with friends and family or collaboration in small teams. But groups can also grow very large and support communities of up to 200,000 members. You can make any group public, toggle persistent history to control whether or not new members have access to earlier messages and appoint administrators with granular privileges. You can also pin important messages to the top of the screen so that all members can see them, including those who have just joined.
-
Channels are a tool for broadcasting messages to large audiences. In fact, a channel can have an unlimited number of subscribers. When you post in a channel, the message is signed with the channel's name and photo and not your own. Each message in a channel has a view counter that gets updated when the message is viewed, including its forwarded copies.
iOS: Start a new message (tap the icon in the top right corner in Chats) > 'New Group'. Android: Tap the circular pencil icon in the chat list > 'New Group'. Telegram Desktop: Click the menu button in the top left corner > 'New Group'.
-
Q: Can I assign administrators?
-
You can add administrators to help you manage your group and define their privileges with granular precision.
-
iOS: Go to Group Info (tap the photo in the top right corner on the group‘s chat screen) > Edit > Administrators. Android: Go to Group Info (tap the name in the header) > the pencil icon (in the top right corner) > Administrators. Telegram Desktop: When in the group, click '…' in the top right corner > Manage group > Administrators.
-
Q: How do I add more members? What's an invite link?
-
You can add your contacts, or using search by username.
-
It is easy to migrate existing groups to Telegram by sending people an invite link. To create an invite link, go to Group Info > Add Member > Invite to Group via Link.
-
Anyone who has Telegram installed will be able to join your group by following this link. If you choose to revoke the link, it will stop working immediately.
You can set up a public username on Telegram. It then becomes possible for other users to find you by that username — you will appear in contacts search under 'global results'. Please note that people who find you will be able to send you messages, even if they don't know your number. If you are not comfortable with this, we advise against setting up a username in Telegram.
-
You can set up a username in Settings and use the universal search box in the chat list to search for chats, messages, and usernames.
-
Q: How does t.me work?
-
Once you've set up a username, you can give people a t.me/username link. Opening that link on their phone will automatically fire up their Telegram app and open a chat with you. You can share username links with friends, write them on business cards or put them up on your website.
-
This way people can contact you on Telegram without knowing your phone number.
-
Q: What can I use as my username?
-
You can use a-z, 0-9 and underscores. Usernames are case-insensitive, but Telegram will store your capitalization preferences (e.g. Telegram and TeleGram is the same user). The username must be at least five characters long.
-
Q: Do I need a username?
-
You don't have to get one. Remember that Telegram usernames are public and choosing a username on Telegram makes it possible for people to find you in global search and send you messages even if they don't have your number. If you are not comfortable with this, we advise against setting up a username.
-
Q: If someone finds me by username, messages and I reply — will they know my number?
-
No. Neither party will see another's phone number (unless this is permitted by your privacy settings). This is similar to the case when you message a person who you've met in a Telegram group.
-
Q: How do I delete my username?
-
Go to Settings and save an empty username. This will remove your username; people will no longer be able to find you via search. This will not affect existing conversations.
-
Q: What do I do if my username is taken?
-
Telegram usernames are distributed on a first come — first serve basis.
-
We understand that certain usernames are part of an online identity for some of us. If your desired username is already taken, we will be happy to help you acquire it for your account or channel, provided that you have that same username on at least two of these services: Facebook, Twitter, Instagram.
-
Due to the fact that one account can register multiple bot and channel usernames, we reserve the right to recall usernames assigned to unused bots and channels, as well as openly squatted usernames.
Telegram is more secure than mass market messengers like WhatsApp and Line. We are based on the MTProto protocol (see description and advanced FAQ), built upon time-tested algorithms to make security compatible with high-speed delivery and reliability on weak connections. We are continuously working with the community to improve the security of our protocol and clients.
-
Q: What if I’m more paranoid than your regular user?
-
We've got you covered. Telegram’s special secret chats use end-to-end encryption, leave no trace on our servers, support self-destructing messages and don’t allow forwarding. On top of this, secret chats are not part of the Telegram cloud and can only be accessed on their devices of origin.
-
Q: So how do you encrypt data?
-
We support two layers of secure encryption. Server-client encryption is used in Cloud Chats (private and group chats), Secret Chats use an additional layer of client-client encryption. All data, regardless of type, is encrypted in the same way — be it text, media or files.
-
Our encryption is based on 256-bit symmetric AES encryption, 2048-bit RSA encryption, and Diffie–Hellman secure key exchange. You can find more info in the Advanced FAQ.
Telegram is open, anyone can check our source code, protocol and API, see how everything works and make an informed decision. Telegram supports verifiable builds, which allow experts to independently verify that our code published on GitHub is the exact same code that is used to build the apps you download from App Store or Google Play.
-
We welcome security experts to audit our system and appreciate any feedback at security@telegram.org.
-
On top of that, Telegram's primary focus is not to bring a profit, so commercial interests will never interfere with our mission.
Q: Do I need to trust Telegram for this to be secure?
-
When it comes to secret chats, you don't — just make sure that the visualized key of your secret chat matches the one in your friend's secret chat settings. More about this below.
-
Q: What if my hacker friend says they could decipher Telegram messages?
-
Anyone who claims that Telegram messages can be deciphered is welcome to prove that claim in our competition and win $300,000. You can check out the Cracking Contest Description to learn more.
-
Any comments on Telegram's security are welcome at security@telegram.org. All submissions which result in a change of code or configuration are eligible for bounties, ranging from $100 to $100,000 or more, depending on the severity of the issue. Please note that we can not offer bounties for issues that are disclosed to the public before they are fixed.
-
Q: Can Telegram protect me against everything?
-
Telegram can help when it comes to data transfer and secure communication. This means that all data (including media and files) that you send and receive via Telegram cannot be deciphered when intercepted by your internet service provider, owners of Wi-Fi routers you connect to, or other third parties.
-
But please remember that we cannot protect you from your own mother if she takes your unlocked phone without a passcode. Or from your IT-department if they access your computer at work. Or from any other people that get physical or root access to your phones or computers running Telegram.
-
If you have reasons to worry about your personal security, we strongly recommend using only Secret Chats in official or at least verifiable open-source apps for sensitive information, preferably with a self-destruct timer. We also recommend enabling 2-Step Verification and setting up a strong passcode to lock your app, you will find both options in Settings > Privacy and Security.
-
Q: How does 2-Step Verification work?
-
Logging in with an SMS code is an industry standard in messaging, but if you're looking for more security or have reasons to doubt your mobile carrier or government, we recommend protecting your cloud chats with an additional password.
-
You can do this in Settings > Privacy and Security > 2-Step Verification. Once enabled, you will need both an SMS code and a password to log in. You can also set up a recovery email address that will help regain access, should you forget your password. If you do so, please remember that it's important that the recovery email account is also protected with a strong password and 2-Step Verification when possible.
-
Check this out for tips on creating a strong password that is easy to remember.
-
Q: Why can jailbroken and rooted devices be dangerous?
-
Using a rooted or jailbroken device makes it easier for a potential attacker to gain full administrative control over your device — root access.
-
A user with root access can easily bypass security features built into the operating system, read process memory or access restricted areas, such as the internal storage. Once an attacker has root access, any efforts to mitigate threats become futile. No application can be called safe under these circumstances, no matter how strong the encryption.
-
Secret Chats
-
Q: How are secret chats different?
-
Secret chats are meant for people who want more secrecy than the average fella. All messages in secret chats use end-to-end encryption. This means only you and the recipient can read those messages — nobody else can decipher them, including us here at Telegram (more on this here). On top of this, Messages cannot be forwarded from secret chats. And when you delete messages on your side of the conversation, the app on the other side of the secret chat will be ordered to delete them as well.
-
You can order your messages, photos, videos and files to self-destruct in a set amount of time after they have been read or opened by the recipient. The message will then disappear from both your and your friend's devices.
-
All secret chats in Telegram are device-specific and are not part of the Telegram cloud. This means you can only access messages in a secret chat from their device of origin. They are safe for as long as your device is safe in your pocket.
-
Q: How do I start a secret chat?
-
Open the profile of the user you want to contact. Tap on ‘…’, then ‘Start Secret Chat’.
-
Remember that Telegram secret chats are device-specific. If you start a secret chat with a friend on one of your devices, this chat will only be available on that device. If you log out, you will lose all your secret chats. You can create as many different secret chats with the same contact as you like.
-
Q: How do self-destructing messages work?
-
The Self-Destruct Timer is available for all messages in Secret Chats and for media in private cloud chats.
-
To set the timer, simply tap the clock icon (in the input field on iOS, top bar on Android), and then choose the desired time limit. The clock starts ticking the moment the message is displayed on the recipient's screen (gets two check marks). As soon as the time runs out, the message disappears from both devices. We will try to send a notification if a screenshot is taken.
-
Please note that the timer in Secret Chats only applies to messages that were sent after the timer was set. It has no effect on earlier messages.
-
Q: Can I be certain that my conversation partner doesn't take a screenshot?
-
Unfortunately, there is no bulletproof way of detecting screenshots on certain systems (most notably, some Android and Windows Phone devices). We will make every effort to alert you about screenshots taken in your Secret Chats, but it may still be possible to bypass such notifications and take screenshots silently. We advise to share sensitive information only with people you trust. After all, nobody can stop a person from taking a picture of their screen with a different device or an old school camera.
-
Q: What is this 'Encryption Key' thing?
-
When a secret chat is created, the participating devices exchange encryption keys using the so-called Diffie-Hellman key exchange. After the secure end-to-end connection has been established, we generate a picture that visualizes the encryption key for your chat. You can then compare this image with the one your friend has — if the two images are the same, you can be sure that the secret chat is secure, and no man-in-the-middle attack can succeed.
-
Newer versions of Telegram apps will show a larger picture along with a textual representation of the key (this is not the key itself, of course!) when both participants are using an updated app.
-
Always compare visualizations using a channel that is known to be secure — it's safest if you do this in person, in an offline meeting with the conversation partner.
-
Q: Why not just make all chats 'secret'?
-
All Telegram messages are always securely encrypted. Messages in Secret Chats use client-client encryption, while Cloud Chats use client-server/server-client encryption and are stored encrypted in the Telegram Cloud (more here). This enables your cloud messages to be both secure and immediately accessible from any of your devices – even if you lose your device altogether.
-
The problem of restoring access to your chat history on a newly connected device (e.g. when you lose your phone) does not have an elegant solution in the end-to-end encryption paradigm. At the same time, reliable backups are an essential feature for any mass-market messenger. To solve this problem, some applications (like Whatsapp and Viber) allow decryptable backups that put their users' privacy at risk – even if they do not enable backups themselves. Other apps ignore the need for backups altogether and leave their users vulnerable to data loss.
-
We opted for a third approach by offering two distinct types of chats. Telegram disables default system backups and provides all users with an integrated security-focused backup solution in the form of Cloud Chats. Meanwhile, the separate entity of Secret Chats gives you full control over the data you do not want to be stored.
-
This allows Telegram to be widely adopted in broad circles, not just by activists and dissidents, so that the simple fact of using Telegram does not mark users as targets for heightened surveillance in certain countries. We are convinced that the separation of conversations into Cloud and Secret chats represents the most secure solution currently possible for a massively popular messaging application.
On Telegram, you can send messages in private chats and groups without making your phone number visible. By default, your number is only visible to people who you've added to your address book as contacts. You can further modify this in Settings > Privacy and Security > Phone Number.
-
-
Note that people will always see your number if they know it already and saved it in their address book.
-
-
Q: I have a new phone number, what do I do?
-
Each phone number is a separate account on Telegram. You have several options if you are using multiple phone numbers:
-
-
If you will no longer use the old number (e.g., you moved to a new country or changed your number for good), simply go to Settings and change the number connected to your Telegram account to the new number. Important: make sure you have access to your connected phone number – otherwise you risk losing access to your account.
-
If you will use the new number for a limited time (e.g., you're on a trip or vacation), there's no need to do anything.
-
If you want to keep using both numbers (e.g., you have a work phone and personal phone), choose one as your Telegram number. You may create another Telegram account on the second number as well, for example, if you want to keep work and personal chats separated. It is possible to log in to one Telegram app with up to 3 different accounts at once.
-
-
Q: How do I log out?
-
Most users don't need to log out of Telegram:
-
-
You can use Telegram on many devices at the same time. Just use the same phone number to log in on all devices.
-
You can go to Settings > Data and Storage > Storage Usage> Clear cache to free up space on your device without logging out.
-
If you use Telegram with multiple phone numbers, you can switch between accounts without logging out.
-
If you use Telegram on a shared device, you can set up a passcode in Settings > Privacy and Security to make sure only you have access to your account.
-
-
If you do want to log out for some reason, here's how you do that:
-
iOS: Go to Settings > Edit > Log out. Android, Telegram Desktop: Go to Settings > … (in the top right corner) > Log out.
-
If you log out, you will keep all your cloud messages. However, you will lose all your Secret Chats and all messages inside those secret chats when you log out.
-
-
Note that logging out does not trigger remote deletion of your secret chat messages on your partner's device — to do that, choose 'Clear History' first.
-
-
Q: How do I change my phone number?
-
You can change your number in Telegram and keep everything, including all your contacts, messages, and media from the Telegram cloud, as well as all your Secret Chats on all devices.
-
To change your number, go to Settings, then tap on your phone number (just above the username), then 'Change Number'. If you already have a different Telegram account on the target number, you'll need to delete that account first.
-
Q: How do I delete my account?
-
If you would like to delete your account, you can do this on the deactivation page. Deleting your account permanently removes all your messages and contacts. All groups and channels that you've created are orphaned and left without a creator but admins retain their rights.
-
This action must be confirmed via your Telegram account and cannot be undone.
-
-
We recommend using a non-mobile browser for this process. Note that you'll receive the code via Telegram, not SMS.
-
-
Q: What happens if I delete my account?
-
As was just mentioned above, all your data will be flushed from our system: all messages, groups, and contacts associated with your account will be deleted. That said, your contacts will still be able to chat in the groups that you have created, and they will still have their copy of the messages you sent them. So if you want to send messages that can vanish without a trace, try using our self-destruct timer instead.
-
Termination of a Telegram account is irreversible. If you sign up again, you will appear as a new user and will not get your history, contacts or groups back. People, who have your phone number in their contacts, will be notified. The new user will be displayed as a separate conversation in their messages list and their conversation history with this new user will be empty.
-
Q: How does account self-destruction work?
-
Telegram is not a commercial organization, and we value our disk space greatly. If you stop using Telegram and don't come online for at least six months, your account will be deleted along with all messages, media, contacts and every other piece of data you store in the Telegram cloud. You can change the exact period after which your inactive account will self-destruct in Settings.
-
Q: My phone was stolen, what do I do?
-
First of all, sorry about your phone. Unfortunately, the phone number is the only way for us to identify a Telegram user at the moment. We don't collect additional information about you, so whoever has the number, has the account. This means we can't help you unless you have access either to the phone number or to Telegram itself on any of your devices.
-
I have access to Telegram on another device
-
-
Go to Telegram Settings > Privacy and Security and turn on Two-Step Verification. This way the phone number alone will not be enough to log in to your account.
-
Go to Settings > Devices (or Privacy & Security > Active Sessions) and terminate your Telegram session on the old device. Whoever has your phone will not be able to log in again, since they don't know your password.
-
Contact your phone provider, so that they block your old SIM and issue a new one with your number.
-
If you decide to switch to a new phone number, don't forget to go to Settings, tap on your phone number and change your Telegram number to the new one.
-
-
I don't have access to Telegram on any other devices
-
-
First and foremost, you need to contact your phone provider, so that they block your old SIM and issue a new one with your number.
-
Wait till you receive your new SIM with the old number, log in to Telegram, then go to Settings > Devices (or Privacy & Security > Active Sessions) and terminate your Telegram session on the old device.
-
-
Removing sensitive data
-
Common thieves usually throw out the SIM card immediately (the phone is harder to locate this way), then wipe the devices and sell them, so there isn't much risk for the data in case of regular petty theft. But if you have reasons to worry about the data on the device and are unable to log out the other device, it is best that you wipe it remotely. You can read more about it here: Apple iOS, Android. Unfortunately, this requires you to have prepared in advance for this scenario.
-
You can delete your Telegram account if you are logged in on at least one of your other devices (mobile or desktop). Note that inactive Telegram accounts self-destruct automatically after a period of time — 6 months being the default setting.
-
Bots
-
-
If you're a developer, you may find our Bots FAQ more useful.
-
-
Q: What are bots?
-
Bots are like small programs that run right inside Telegram. They are made by third-party developers using the Telegram Bot API.
-
Q: How do I create a bot?
-
Creating Telegram bots is super-easy, but you will need at least some skills in computer programming. If you're sure you're up to it, our Introduction for Developers is a good place to start.
-
Unfortunately, there are no out-of-the-box ways to create a working bot if you are not a developer. But we're sure you'll soon find plenty of bots created by other people to play with.
-
Q: A bot is sending me messages, how do I make it stop?
-
If you don't want a bot to send you messages, feel free to block it – same as you would block a human user. Some Telegram clients have a 'Stop Bot' button right in the bot's profile.
-
That said, most bot developers offer commands that silence the bot, check its /help for clues.
-
Q: Are bots safe?
-
Yes. Bots are no different from human users that you meet in groups for example. They can see your public name, username, and profile pictures, and they can see messages you send to them, that's it. They can't access your last seen status and don't see your phone number (unless you decide to give it to them yourself).
-
Naturally, any bot should be treated as a stranger — don't give them your passwords, Telegram codes or bank account numbers, even if they ask nicely. Also, be careful when opening files sent by bots, same as you would deal with ordinary humans. Example: If a bot sent us a file called OpenMe.exe, we probably wouldn't open it.
-
Q: If I add a bot to my group, can it read my messages?
-
Bots can work in two modes when you add them to groups. By default, bots only see messages that are meant for them. In this case, you'll see 'has no access to messages' in the group members list next to the bot.
-
Some bots need more information to work, so developers may disable the privacy mode. In this case, the bot will see all messages sent to the group, and you will see 'has access to messages' in the members list next to the bot.
If your group contains very sensitive information, maybe it's better to avoid adding bots you don't trust 100%.
-
Q: Are bots made by Telegram?
-
No. While we have some official bots for specific purposes (like @gif or @GDPRbot), we don't usually make bots. Bots are made by third-party developers using the Telegram Bot API and platform.
-
Q: Where can I find more bots?
-
There is no official store at the moment, so you'll have to ask your friends or search the web for now. We're pretty sure you'll find some bots to play with.
-
Deeper questions
-
Q: Can I get Telegram's server-side code?
-
All Telegram client apps are fully open source. We offer verifiable builds both for iOS and Android – this technology allows to independently verify that the application you download from the app stores was built using the exact same code that we publish.
-
By contrast, publishing the server code doesn’t provide security guarantees neither for Secret Chats nor for Cloud Chats. This is because – unlike with the client-side code – there’s no way to verify that the same code is run on the servers.
-
As for Secret Chats, you don’t need the server-side code to check their integrity – the point of end-to-end encryption is that it must be solid regardless of how the servers function.
-
-
In a post on his channel, Pavel Durov explained why Telegram hasn't published the server code, even as a publicity stunt.
-
-
The encryption and API used on Telegram's servers are fully documented and open for review by security experts. We welcome any comments at security@telegram.org
-
Q: Can I run Telegram using my own server?
-
Our architecture does not support federation yet. Telegram is a unified cloud service, so creating forks where two users might end up on two different Telegram clouds is unacceptable. To enable you to run your own Telegram server while retaining both speed and security is a task in itself. At the moment, we are undecided on whether or not Telegram should go in this direction.
Apple created privacy sheets to inform users about what data apps may collect, but information there is vague and can be misleading. You can see a detailed explanation of Telegram's sheet here.
-
Q: Why do you have two apps in the Mac App Store?
-
One is our app for macOS, the other is Telegram Lite, the macOS version of our multi-platform client. Both apps are official. Both started out as unofficial applications by two different developers and vary in design and functionality.
-
Telegram for macOS supports many platform-specific features, such as the MacBook Pro Touch Bar, gesture navigation, integration with the Mac's Share menu and more. It has every feature from the iOS version of the app including Secret Chats.
-
Telegram Lite is a lightning-fast app, optimized for work-related tasks and handling large communities. It offers a three-column interface, perfect for multitasking and quick access to media, files and links shared in your chats. This app can also be used to export your Telegram data and chats.
-
Q: Can I translate Telegram?
-
Telegram is officially available in English, Spanish, German, Dutch, Italian, French, Arabic, Portuguese, Korean, Malay, Russian and Ukrainian on most platforms, and we are gradually expanding the list of languages built into the apps.
-
If you don’t like how a specific element in Telegram's interface is translated in your language, or would like to help us maintain the translation, check out our localization platform. Everyone can suggest translations and vote for the best ones, making Telegram localization a community-driven effort.
-
If you're looking to go beyond suggestions for individual phrases and would like to help us maintain the official translation to your language on a continuous basis, you can contact @TelegramAuditions. Please include a hashtag with the English name of your language (e.g. #Albanian) and a few links to phrases on this platform with your translation suggestions or comments. Be sure to read the Style Guide carefully before you apply.
-
Q: Can I help?
-
Yes, we are always looking for volunteers to help us with user support. If you would be interested in answering questions about Telegram to users from your country, contact our auditions account.
Telegram Passport is a unified authorization method for services that require personal identification. With Telegram Passport, you can upload your documents once, then instantly share your data with services that require real-world ID (finance, ICOs, etc.).
-
Your identity documents and personal data will be stored in the Telegram cloud using End-to-End Encryption. To Telegram, this data is just random gibberish, and we have no access to the information you store in your Telegram Passport. When you share data, it goes directly to the recipient.
-
-
You can find more information about Telegram Passport on our blog.
-
-
If you're a developer or owner of a service that requires real-life ID, kindly take a look at this manual. You can also try requesting Telegram Passport data using this page.
-
-
Troubleshooting
-
Login and SMS
-
Please make sure you are entering your mobile phone number in the international format. I.e.: +(country code)(city or carrier code)(your number)
-
If you are having registration or login problems, please contact us using this form.
-
Getting a code via a phone call
-
For security reasons, login codes dictated via a phone call are only available for accounts that have two-step verification enabled (Settings > Privacy & Security > Two-Step Verification).
-
Please also note that Telegram accounts can only be connected to a mobile number. We currently don't support landline numbers.
-
Getting a code via Telegram
-
If you have recently used one of our apps on another device (it could also be a different app on the same device), we may send the login code via Telegram instead of SMS.
-
To receive such a code, just check Telegram from any of your connected devices. You will find it in the chat with Telegram, a verified profile with a blue check:
-
-
-
Login code sent via Telegram
-
-
-
WARNING! Please note that getting codes via Telegram should not be considered an alternative to using an up-to-date phone number. In case of a change in numbers, always make sure Telegram is connected to a phone number you control, otherwise you risk losing access to your account forever.
Check notification priority for Telegram in Android settings, it can be called Importance or Behaviour depending on your device.
-
If your phone uses some battery saving software, make sure that Telegram is whitelisted in that application.
-
-
-
NOTE: Huawei and Xiaomi devices have evil task killer services that interfere with the Telegram notification service. For our notifications to work, you need to add Telegram to allowed apps in those devices' security settings. Huawei: Phone Manager App > Protected Apps > Add Telegram to the list. Xiaomi: Services > Security > Permissions > Autostart, find Telegram and enable autostart.
-
-
iOS
-
-
Go to Telegram Settings — Notifications and Sounds, make sure that notifications are ON in Telegram.
-
Check that notifications are ON in phone Settings.
-
Check, whether contact or group is muted.
-
Shut down Telegram (go to home screen, double tap home button, swipe upwards on Telegram), then go to phone settings, set the alert style for Telegram to NONE. Relaunch Telegram, go to phone settings, set alert style back to banners.
-
-
Problems with contacts
-
If you know your friends have Telegram, but you can't see them — or they appear as numbers instead of names.
-
Android:
-
-
Make sure you are using the latest version of the app.
-
Relaunch the app (by terminating it from processes list and launching again).
-
Temporarily change the name of the contact in phone contacts (add a few symbols, then change back again).
-
If that didn't help, re-login. Remember that logging out kills your Secret Chats.
-
-
iOS:
-
-
Force quit the app (double tap home button, then swipe up on Telegram), then relaunch and check if it helped.
-
If that doesn't help, temporarily change the name of the contact in phone contacts (add a few symbols, then change back again).
-
If that doesn’t work, re-login: Settings > Edit > Log Out. Remember that logging out kills all your Secret Chats. Then log in again.
-
-
Deleting contacts on Android
-
To delete a contact, open a chat with the person, tap the title in the top area of the chat screen to open their profile, then tap on (⋮) in the top right corner > 'Delete contact'.
-
If you want to delete the contact completely, make sure you also delete them from your phone contacts. Telegram stays in sync and will add the contact back if you don't.
-
Where did my Secret Chat messages go?
-
Secret Chats are established between the two devices they were created on. This means that all those messages are not available in the cloud and cannot be accessed on other devices.
-
Moreover, Secret Chats are also tied to your current login session on the device. If you log out and in again, you will lose all your Secret Chats.
-
Can't send messages to non-contacts
-
When users report unwanted messages from a Telegram account, we apply a limit: Reported accounts can only send messages to people who have their number saved as a contact.
-
This means that if you randomly contact people you don't know and send them annoying messages, you may lose the ability to do so in the future.
-
If you think that this limit was applied to your account wrongly, please visit this page.
-
Telegram uses the camera or microphone in the background!
-
Telegram can use the microphone in the background if you minimize the app when making a call, recording a video, or recording a voice/video message.
-
Permission monitors on Samsung and Xiaomi can inadvertently flag and notify you that Telegram requested access to camera in the background. This happens when the app requests info about the camera — it isn’t using the camera. Unfortunately it may look the same to the Samsung and Xiaomi permission monitors.
-
Camera info is requested by the app when you tap on the attachment button, or start recording a video or a video message. If you do this and quickly close the app, the already initiated request may try to run asynchronously when the app is already in the background, or be sent when the system wakes up the app to show a notification about a new message. In any case, these requests are only for the camera info, the app never uses the camera itself in the background.
-
Anyone can check Telegram’s open source code and confirm that the app is not doing anything behind their back. We also offer reproducible builds that can help you prove that the version you downloaded from App Store or Google Play is built from the exact same source code we publish.
-
-
Telegram Support
-
If you have any other questions, please contact Telegram Support (in Telegram go to Settings — Ask a question). Note that we rely on volunteers for support.
-
If you can't log in to your account, please use this form.
-
-
For media requests, please contact @PressBot on Telegram.
We have a special account that can help you with login problems, @smstelegram. This account is official. Don't be afraid to DM it the number you use for Telegram, we need this info to investigate issues.
-
Be careful, we don't have any other support accounts on any social media platforms.
-
Facebook or other platforms?
-
If anyone on Facebook or any other platform is telling you they're us, they are not.
When users press the ‘Report spam’ button in a chat, they forward these messages to our team of moderators for review. If the moderators decide that the messages deserved this, the account becomes limited temporarily.
-
This means that if you have been sending unwanted messages to random strangers or posting spam in groups, you lose the ability to do so.
-
Q: So I can't send messages anymore?
-
No, it's not that bad. Limited accounts can send messages to people who have their number saved as a contact. You can also always reply to anyone who messages you first.
-
Q: Why was I reported?
-
Telegram‘s username search is not a tool for making new friends. People usually don’t like it when strangers contact them — so they will report you if they find your messages annoying. Please only contact people if you're sure that they are expecting messages from you. The same applies to adding people to unwanted groups and channels. In addition to this, group admins can also report users who post spam in their groups.
-
Naturally, all such reports are also checked by human moderators. If the messages contain spam, the account will be temporarily limited.
-
Q: What can people report me for?
-
For private messages, it really doesn‘t matter what you send, as long as the receivers find it unwelcome. It could have been a photo, an invite link or a simple ’hello‘. Please only send messages when you are sure people won’t mind getting them.
-
As a general rule, people do mind getting unsolicited advertisements, links, invite links to groups or channels, random photos and, above all, anything related to commerce or online popularity. If you send them something like this, you will be blocked — and everybody else will be happy.
-
Moderators are more lenient when it comes to messages in groups, but anyone who sends spam or unsolicited advertisments will be limited.
-
Q: What do I do now?
-
If this happened to you for the first time (and you are not an industrial scale spammer), most likely your account will be limited for a few days or so. Please wait and consider that people want a peaceful time using our messenger.
-
Repeated offences will result in longer periods of being blocked. If you keep writing unwanted messages to strangers, you may lose the ability to do so forever.
-
Q: I read all of the above, and I‘m certain that I didn’t break any rules!
-
If you are sure that the limit was wrongfully applied to your account, please contact our @SpamBot.
-
Please forgive us for the inconvenience — even the best systems, algorithms and well-trained people can make mistakes sometimes.
-
Q: I know I was wrong, please release me sooner!
-
We're sorry, but this is impossible. We value the inner peace of Telegram users too much.
-
Q: I‘ve just signed up and didn’t send any messages yet, but my account is limited.
-
Some numbers may trigger an overly harsh response from our system, either due to their previous owners‘ activities or due to them being certain virtual/VOIP numbers. We’re sorry if this resulted in your account being limited for no reason.
-
If you think this is your case, please contact @SpamBot and tell it your story.
-
-