Telegram Messaging API

Start logging in to a Telegram user account and obtain the sessionId used by every other endpoint. Three modes — pick one and send its JSON body, then poll Get Session Status until status reads CONNECTED. Phone login. Body: {"mode":"phone","phoneNumber":"+8613800138000","deviceName":"My Bot"}. phoneNumber is the full international number with the leading +. Poll the session until status is WAITING_FOR_OTP, then submit the login code from the Telegram app via Verify OTP. If the account has two-factor authentication, the session shows twoFactorRequired=true and you continue with Submit 2FA Password. QR login. Body: {"mode":"qr","deviceName":"My Bot"}. The create response returns a qrPageUrl you can open to watch the login live; poll Get Session Status for the qrImage (base64 data-URI). On the phone: Telegram → Settings → Devices → Link Desktop Device, then scan. Restore. Body: {"mode":"restore","sessionId":"<previous id>"} reconnects a previously logged-in account without a new code. After connecting, the sessionId switches to a stable account-derived ID (both IDs stay valid); keep it for later restore calls. An optional proxy field accepts a SOCKS5 URL such as socks5://user:pass@host:1080.

Return the current state of a session: its status (CREATED, WAITING_FOR_SCAN, WAITING_FOR_OTP, CONNECTING, CONNECTED, DISCONNECTED, LOGGED_OUT, or FAILED), the login mode, the phone number, and — while waiting for login — the qrImage (base64 data-URI) plus twoFactorRequired when a cloud password is needed. If the account is saved but offline, this call lazily reconnects it. Poll it after Create Session until status is CONNECTED.

Disconnect a session. By default it only drops the live connection while keeping the stored login, so the account can be restored later. Pass logout=true to also log out of Telegram remotely and delete the stored login — after which the account must log in again with a code or QR scan.

Submit the login code Telegram delivered to the account in the Telegram app (not SMS). Only valid while the session status is WAITING_FOR_OTP. Send a JSON body with code. The call is accepted asynchronously — poll Get Session Status for the final result. If the account has two-factor authentication, the session then shows twoFactorRequired=true and you continue with Submit 2FA Password.

Submit the Telegram two-factor (cloud) password. Only valid while the session shows twoFactorRequired=true (phone mode after Verify OTP, or QR mode after scanning). Send a JSON body with password. The call is accepted asynchronously — poll Get Session Status until it reads CONNECTED.

Send a Telegram text message from a connected session. Send a JSON body with the recipient as to and the message as text. to accepts @username or a bare username, +phone in full international format, or me for the account's own Saved Messages; a bare phone number is tried as a fallback. A bare numeric user ID is not supported unless the account already knows the peer. The session must have completed login.

Upload and send a media message from a connected session. Send a JSON body with the recipient as to, the media type as type (image, video, audio, voice, or document), and the base64-encoded file content as data. fileName sets the document name, caption adds a caption, and mimeType overrides the inferred type. to accepts the same peer formats as Send a Text Message. Returns a sent confirmation.

Return messages received in real time while the session was connected, newest first, excluding messages sent by the account itself. Each item includes the message id, chatJid, sender, type, text, and timestamp. The inbox is an in-memory cache holding the most recent 500 messages per session and is cleared on restart. Use limit to cap how many are returned. Ideal for polling new inbound messages to power auto-replies.

Mark a peer's history as read up to a given message. Send a JSON body with peer (@username, +phone, me, or a user:<id> / chat:<id> / channel:<id> peer from inbox or chat responses) and an optional maxId; when maxId is omitted, everything up to the latest message is marked read.

Add an emoji reaction to a message. Send a JSON body with peer, the numeric messageId of the target message (from chat history or the inbox), and the emoji to apply. Send an empty-string emoji to clear your reaction.

Edit the text of a message previously sent by the account. Send a JSON body with peer, the numeric messageId of your sent message, and the new text. Only the account's own messages can be edited.

Delete a message for everyone. Send a JSON body with peer and the numeric messageId of the target message. Use it to retract a message sent by the account or to moderate where permissions allow.

Return the chats observed since the session connected (built from incoming messages), sorted by last activity, newest first. Each item includes the jid (a user:<id> / chat:<id> / channel:<id> peer), the display name when known, and the last timestamp. In-memory only, cleared on restart. Use it to build a conversation list and to discover the peer identifiers accepted by history and management endpoints.

Fetch recent messages for a peer live from the server (not the in-memory cache), newest first. Provide the sessionId and the peer (@username, +phone, me, or a user:<id> / chat:<id> / channel:<id> peer from chat or inbox responses). Each message includes its numeric id, chatJid, sender, fromMe flag, type, text, and timestamp. Use limit to control how many are returned (default 20).

Download the media (photo or document) attached to a specific message and return it base64-encoded with its MIME type. Provide the sessionId, the peer, and the numeric messageId from the chat history response.

Return information about the account logged in on this session: its numeric user id, phone number, username, first and last name, and whether it is a bot. Use it to confirm exactly which account a session is connected as and to display your own identity before sending.

Update the connected account's public profile. Send a JSON body with firstName, lastName, and/or about (bio); provide at least one field — only supplied fields change. Changes are reflected on your Telegram profile visible to others.

Return the account's saved contacts. Each contact includes its numeric id, username, first and last name, and phone number. Use it to enumerate known contacts for enrichment, recipient pickers, or audience building.

Resolve a peer and report whether it exists on Telegram. Pass the peer (@username, +phone, or a typed user:<id> / chat:<id> / channel:<id>) in the path. Returns exists with the resolved id, username, and display name when found, or exists=false with a reason when the peer cannot be resolved. Use it to validate recipients before sending to improve deliverability.

Return a user's bio (About) text. Pass the peer (@username or +phone) in the path. Uses a connected session to query the value in real time; the result is empty when the user has no bio or hides it.

Download a peer's profile picture and return it base64-encoded with its MIME type. Pass the peer (@username or +phone) in the path. Returns exists=false when the peer has no picture. Uses a connected session for a live lookup.

Create a basic Telegram group with a title and an initial set of participants. Send a JSON body with name and participants (an array of peer strings resolving to users, e.g. ["@alice","+8613800138000"]). Returns the created chat's peer ids for immediate follow-up operations.

Return the groups and channels the connected account belongs to. Each item includes the jid (chat:<id> for basic groups, channel:<id> for supergroups and channels), the name, the type (group, supergroup, or channel), and a participant count for basic groups. Use it to discover the peer ids needed for management operations.

Join a Telegram group or channel using an invite link or hash. Send a JSON body with link, which can be a full invite link (https://t.me/+AbCdEf or https://t.me/joinchat/AbCdEf) or just the hash. Returns the joined peer. Useful for programmatically entering communities you administer or monitor.

Return a group or channel's details: its name, description (about), type (group, supergroup, or channel), and participant count. Provide the sessionId and the peer (chat:<id> or channel:<id> from List Groups, or a resolvable @username). Use it to inspect a community before broadcasting or moderation.

Update a group or channel's title and/or description. Send a JSON body with name and/or topic (the description); provide at least one field — only supplied fields change. Requires the appropriate admin rights in the group or channel.

Add one or more users to a group or channel. Send a JSON body with participants (an array of peer strings resolving to users, e.g. ["@alice","+8613800138000"]). Returns how many were added. Requires the appropriate admin rights in the group or channel.

Remove one or more users from a group or channel. Send a JSON body with participants (an array of peer strings resolving to users, e.g. ["@alice"]). Returns how many were removed. Requires the appropriate admin rights in the group or channel.

Promote members to admin or demote existing admins. Only supported for supergroups and channels (channel:<id>). Send a JSON body with participants (an array of peer strings resolving to users) and action (promote or demote). Returns the action and how many were updated. Requires the appropriate admin rights.

Export a new invite link for a group or channel. Provide the sessionId and the peer. Returns a shareable t.me invite link. Requires the appropriate admin rights in the group or channel.

Remove the connected account from a group or channel. Provide the sessionId and the peer; no request body is required. Returns the peer that was left. Use it to programmatically exit communities the account no longer needs to be in.