Example implementations: telegram for android, tdlib.

To show a nicely formatted and validated phone number field, the help.countriesList constructor can be obtained using the help.getCountriesList method.

Authorization requires that a text message containing an authorization code first be sent to the user’s phone. This may be done using the auth.sendCode method. The system will automatically choose how to send the authorization code; there are four possible ways the code can arrive:

• Telegram code
• SMS code
• Phone call: a synthesized voice will tell the user which verification code to input
• Flash phone call: the code will be sent via a flash phone call, that will be closed immediately. In the last case, the phone code will then be the phone number itself, just make sure that the phone number matches the specified pattern (see auth.sentCodeTypeFlashCall).

The auth.sendCode method also has parameters for enabling/disabling use of flash calls, and allows passing an SMS token that will be included in the sent SMS. For example, the latter is required in newer versions of android, to use the android SMS receiver APIs.

The returned auth.SentCode object will contain multiple parameters:

If the message takes too long (timeout seconds) to arrive at the phone, the auth.resendCode method may be invoked to resend a code of type next_type. If the same happens again, you can use auth.resendCode with the next_type returned by the previous call to auth.resendCode. To cancel the verification code use auth.cancelCode.

When user enters verification code, the auth.signIn method must be used to validate it and possibly sign user in.

If the code was entered correctly, but the method returns auth.authorizationSignUpRequired, it means that account with this phone number doesn't exist yet: user needs to provide basic information, accept terms of service and then the new user registration method (auth.signUp) must be invoked.

Numerical value similar to HTTP status. Contains information on the type of error that occurred: for example, a data input error, privacy error, or server error. This is a required parameter.

A string literal in the form of /[A-Z_0-9]+/, which summarizes the problem. For example, AUTH_KEY_UNREGISTERED. This is an optional parameter.

There should be a way to handle errors that are returned in rpc_error constructors.

Below is a list of error codes and their meanings:

The request must be repeated, but directed to a different data center.

The query contains errors. In the event that a request was created using a form and contains user generated data, the user should be notified that the data must be corrected before the query is repeated.

There was an unauthorized attempt to use functionality available only to authorized users.

Privacy violation. For example, an attempt to write a message to someone who has blacklisted the current user.

An attempt to invoke a non-existent object, such as a method.

Similar to 400 BAD_REQUEST, but the app should not display any error messages to user in UI as a result of this response. The error message will be delivered via updateServiceNotification instead.

The maximum allowed number of attempts to invoke the given method with the given input parameters has been exceeded. For example, in an attempt to request a large number of text messages (SMS) for the same phone number.

An internal server error occurred while a request was being processed; for example, there was a disruption while accessing a database or file storage. If a client receives a 500 error, or you believe this error should not have occurred, please collect as much information as possible about the query and error and send it to the developers.

If a server returns an error with a code other than the ones listed above, it may be considered the same as a 500 error and treated as an internal server error.

              
botCommand#c27ac8c7 command:string description:string = BotCommand;

botInfo#98e81d3a user_id:int description:string commands:Vector<BotCommand> = BotInfo;

channelFull#f0e6672a flags:# can_view_participants:flags.3?true can_set_username:flags.6?true can_set_stickers:flags.7?true hidden_prehistory:flags.10?true can_set_location:flags.16?true has_scheduled:flags.19?true can_view_stats:flags.20?true blocked:flags.22?true id:int about:string participants_count:flags.0?int admins_count:flags.1?int kicked_count:flags.2?int banned_count:flags.2?int online_count:flags.13?int read_inbox_max_id:int read_outbox_max_id:int unread_count:int chat_photo:Photo notify_settings:PeerNotifySettings exported_invite:ExportedChatInvite bot_info:Vector<BotInfo> migrated_from_chat_id:flags.4?int migrated_from_max_id:flags.4?int pinned_msg_id:flags.5?int stickerset:flags.8?StickerSet available_min_id:flags.9?int folder_id:flags.11?int linked_chat_id:flags.14?int location:flags.15?ChannelLocation slowmode_seconds:flags.17?int slowmode_next_send_date:flags.18?int stats_dc:flags.12?int pts:int = ChatFull;
userFull#edf17c12 flags:# blocked:flags.0?true phone_calls_available:flags.4?true phone_calls_private:flags.5?true can_pin_message:flags.7?true has_scheduled:flags.12?true video_calls_available:flags.13?true user:User about:flags.1?string settings:PeerSettings profile_photo:flags.2?Photo notify_settings:PeerNotifySettings bot_info:flags.3?BotInfo pinned_msg_id:flags.6?int common_chats_count:int folder_id:flags.11?int = UserFull;

user#938458c1 flags:# self:flags.10?true contact:flags.11?true mutual_contact:flags.12?true deleted:flags.13?true bot:flags.14?true bot_chat_history:flags.15?true bot_nochats:flags.16?true verified:flags.17?true restricted:flags.18?true min:flags.20?true bot_inline_geo:flags.21?true support:flags.23?true scam:flags.24?true apply_min_photo:flags.25?true id:int access_hash:flags.0?long first_name:flags.1?string last_name:flags.2?string username:flags.3?string phone:flags.4?string photo:flags.5?UserProfilePhoto status:flags.6?UserStatus bot_info_version:flags.14?int restriction_reason:flags.18?Vector<RestrictionReason> bot_inline_placeholder:flags.19?string lang_code:flags.22?string = User;
              
            

The botInfo constructors contained in the userFull, chatFull, channelFull contain a list of commands, and for groups, the ID and a description of each bot.

In graphical clients, when users begin a message with a /, a list of commands supported by all bots present in the current chat should be shown; the same should be done for one-to-one chats with the bot itself.

If the command list of a bot changes, the bot_info_version contained in the user constructor received in updates will change; this indicates that the client should refetch full bot information using users.getFullUser.

              
botCommand#c27ac8c7 command:string description:string = BotCommand;

---functions---

bots.setBotCommands#805d46f6 commands:Vector<BotCommand> = Bool;
              
            

The command list can be changed by the owner of the bot through @botfather, but bots can also change their own command list by invoking bots.setBotCommands.