Telegram allows you to export data connected to your account so that it becomes accessible offline in JSON or in human-readable HTML. To use this feature, make sure you have Telegram Desktop installed on your computer, then click Settings > Advanced > Export Telegram data.
This document outlines the data layout and schema for the JSON export. To view the HTML export, open the
export_results.htmlfile with a web browser and freely interact with the interface. If you export a single chat, the file will be calledmessages.htmlinstead.
The exported data will be laid out as follows.
/your/path/export_folder
│
├── result.json
│
├── chats
│ ├── chat_01
│ │ ├── contacts
│ │ │ ├── contact_1.vcard
│ │ │ ├── ...
│ │ ├── photos
│ │ │ ├── photo_1@DD-MM-YYYY_hh-mm-ss.jpg
│ │ │ ├── ...
│ │ ├── video_files
│ │ │ ├── video_1@DD-MM-YYYY_hh-mm-ss.mp4
│ │ │ ├── video_1@DD-MM-YYYY_hh-mm-ss.mp4_thumb.jpg
│ │ │ ├── ...
│ │ ├── round_video_messages
│ │ │ ├── file_1@DD-MM-YYYY_hh-mm-ss.mp4
│ │ │ ├── file_1@DD-MM-YYYY_hh-mm-ss.mp4_thumb.jpg
│ │ │ ├── ...
│ │ ├── stickers
│ │ │ ├── AnimatedSticker.tgs
│ │ │ ├── AnimatedSticker.tgs_thumb.jpg
│ │ │ ├── sticker.webp
│ │ │ ├── sticker.webp_thumb.jps
│ │ │ ├── AnimatedSticker(1).tgs
│ │ │ ├── AnimatedSticker(1).tgs_thumb.jpg
│ │ │ ├── sticker(1).webp
│ │ │ ├── sticker(1).webp_thumb.jps
│ │ │ ├── ...
│ │ ├── voice_messages
│ │ │ ├── audio_1@DD-MM-YYYY_hh-mm-ss.ogg
│ │ │ ├── ...
│ │ ├── files
│ │ │ ├── file_name.jpg
│ │ │ ├── file_name.jpg_thumb.jpg
│ │ │ ├── AUD-NAME.opus
│ │ │ ├── ...
│ ├── chat_02
│ │ ├── ...
│ ├── ...
│
├── lists
│ └── other_data.json
│
├── stories
│ ├── story_1@DD-MM-YYYY_hh-mm-ss.jpg
│ ├── story_2@DD-MM-YYYY_hh-mm-ss.mp4
│ ├── ...
│
└── profile_pictures
├── photo_1@DD-MM-YYYY_hh-mm-ss.jpg
├── photo_2@DD-MM-YYYY_hh-mm-ss.jpg
├── ...All media elements are referenced by
result.jsonvia relative paths.
Example:"photo": "chats/chat_01/photos/photo_2@29-10-2021_09-30-00.jpg".
The documentation below assumes that you performed a full export. If you exported a single chat, the result.json file will instead represent a single Chat object, and you should start reading the schema from there.
This object represents the main result.json file itself.
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| personal_information | PersonalInformation | Optional. Basic information about the user |
| profile_pictures | Array of UserProfilePhoto | Optional. The user's current profile photos |
| stories | Array of Story | Optional. Stories posted by the user from Telegram mobile apps. |
| contacts | Contacts | Optional. Exported contacts, if any |
| frequent_contacts | FrequentContacts | Optional. Exported frequent contacts, if any. The user may have disabled this in their privacy settings |
| sessions | Sessions | Optional. Info shown in Settings > Privacy & Security > Active Sessions |
| web_sessions | WebSessions | Optional. The user's web sessions. |
| other_data | OtherData | Optional. Data such as the user's IP address, history of username and phone number changes |
| chats | Chats | Optional. Exported chats, if any |
| left_chats | LeftChats | Optional. Exported chats that the user left or was banned from |
This object contains basic information about the user.
| Field | Type | Description |
|---|---|---|
| user_id | Integer | Unique identifier for this user. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. |
| phone_number | String | User's phone number (e.g., +01 234 567 8910) |
| first_name | String | User's first name |
| last_name | String | User's last name |
| username | String | Optional. User's public username (e.g., @username) |
| bio | String | Optional. User's bio |
This object represents a user profile photo.
| Field | Type | Description | ||
|---|---|---|---|---|
| date | String | Upload date of this photo as an ISO 8601 timestamp (e.g., 2021-12-28T18:53:27) |
||
| date_unixtime | String | Upload date of this photo as a unix timestamp (e.g., 1640714007) |
||
| photo | String | Relative path of this photo (e.g., profile_pictures/photo_1@28-12-2021_18-53-27.jpg) |
This object represents a story.
| Field | Type | Description |
|---|---|---|
| date | String | Upload date of this story as an ISO 8601 timestamp (e.g., 2023-09-02T17:05:43) |
| date_unixtime | String | Upload date of this story as a unix timestamp (e.g., 1693667143) |
| expires | String | Expiration date of this story as an ISO 8601 timestamp (e.g., 2023-09-03T17:05:43) |
| expires_unixtime | String | Expiration date of this story as a unix timestamp (e.g., 1693753543) |
| pinned | Boolean | True if the story is pinned, false otherwise |
| media | String | Relative path to the media uploaded as a story (e.g., stories/story_2@02-09-2023_17-05-43.mp4) |
This object contains all the contacts in this export. If the user allowed access, their contacts are continuously synced with Telegram. Synced contacts can be deleted in Settings > Privacy & Security on Telegram's mobile apps.
| Field | Type | Description | |
|---|---|---|---|
| about | String | Brief description of the data exported herein | |
| list | Array of Contact | Array of all exported contacts |
This object represents a phone contact.
| Field | Type | Description |
|---|---|---|
| first_name | String | Contact's first name |
| last_name | String | Contact's last name |
| phone_number | String | Contact's phone number |
| date | String | Optional. Creation date of this contact as an ISO 8601 timestamp (e.g., 2000-11-27T09:30:00) |
| date_unixtime | String | Optional. Creation date of this contact as a unix timestamp (e.g., 975317400) |
Frequent contacts are those that the user is more likely to message frequently. Telegram uses this data to populate the People box at the top of the Search section. This rating is also calculated for inline bots so that the app can suggest the bots the user is most likely to use in the attachment menu (or when they start a new message with @).
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| list | Array of FrequentContact | List of all exported frequent contacts |
To delete this data, go to Settings > Privacy & Security and disable 'Suggest Frequent Contacts' (requires Telegram for iOS v.4.8.3 or Telegram for Android v.4.8.10 or higher).
This object represents a frequent phone contact.
| Field | Type | Description |
|---|---|---|
| id | Integer | Unique identifier for the user or bot stored in this contact. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier. |
| category | String | Category of this contact. Currently, must be one of “people”, “inline_bots”, “calls”. |
| type | String | Type of this contact. Currently, must be one of “user”, “private_channel”, “private_group”, “private_supergroup”, “public_channel”, “public_supergroup”. |
| name | String | Contact's name |
| rating | Float | A rating to represent how likely the user is to message this contact. The contact with the highest rating is the most likely to be messaged. |
This object contains all session info as shown in Settings > Privacy & Security > Active Sessions.
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| list | Array of Session | Array of sessions |
This object represents a Telegram session.
| Field | Type | Description |
|---|---|---|
| last_active | String | Last active date of this session as an ISO 8601 timestamp (e.g., 2023-11-13T14:37:50) |
| last_active_unixtime | String | Last active date of this session as a unix timestamp (e.g., 1699882670) |
| last_ip | String | Last ip that used this session (e.g., 192.0.2.1) |
| last_country | String | Last country where this session was active |
| last_region | String | Last region where this session was active |
| application_name | String | Application name (e.g., “Telegram Android”) |
| application_version | String | Application version (e.g., “10.2.8”) |
| device_model | String | Device model (e.g., “Google Pixel 7 Pro”, “Chrome 116”, etc.) |
| platform | String | Platform name (e.g., “Windows”, “Android”, etc.) |
| system_version | String | System version (e.g., “Windows 11”, “SDK 34”, etc.) |
| created | String | Creation date of this session as an ISO 8601 timestamp (e.g., 2022-06-03T19:53:50) |
| created_unixtime | String | Creation date of this session as a unix timestamp (e.g., 1654278830) |
This object contains all websites where you logged in using authentication via Telegram. This information is shown in Settings > Privacy & Security > Active Sessions.
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| list | Array of WebSession | Array of web sessions |
This object represents a Telegram login session via web.
| Field | Type | Description |
|---|---|---|
| last_active | String | Last active date of this session as an ISO 8601 timestamp (e.g., 2023-11-13T14:37:50) |
| last_active_unixtime | String | Last active date of this session as a unix timestamp (e.g., 1699882670) |
| last_ip | String | Last ip that used this session (e.g., 192.0.2.1) |
| last_region | String | Last region where this session was last active |
| bot_username | String | Username of the bot used to authenticate this session (e.g., TutorialBot) |
| domain_name | String | Authenticated domain (e.g., “core.telegram.org”) |
| browser | String | Browser used to login (e.g., “Chrome 113”) |
| platform | String | Platform used to login (e.g., “Windows”) |
| created | String | Creation date of this session as an ISO 8601 timestamp (e.g., 2022-06-03T19:53:50) |
| created_unixtime | String | Creation date of this session as a unix timestamp (e.g., 1654278830) |
Data such as the user's IP address, history of username and phone number changes.
| Field | Type | Description |
|---|---|---|
| about_meta | String | Brief description of the data exported herein |
| help | String | Temporary disclaimer about the fact that OtherData is currently in beta |
| changes_log | Array of ChangeEvent | Array of events related to this user (e.g., a username change, phone number change, etc.) |
| created_stickers | Array of StickerPack | Array of sticker packs created by the user |
| drafts | Array of CloudDraft | Array of cloud drafts |
| drafts_about | String | Brief description of cloud drafts |
| installed_stickers | Array of StickerPack | Array of sticker packs installed by the user |
| ips | Array of Ip | Array of ips this user accessed Telegram from over the last 12 months |
| email_about | String | Currently empty |
This object represents a Telegram sticker pack. Currently only holds its URL.
| Field | Type | Description |
|---|---|---|
| url | String | URL of this sticker pack |
This object represents a cloud draft, that is, a message the user left in the input field of a Telegram chat without sending it.
| Field | Type | Description |
|---|---|---|
| chat | String | Chat identifier in the format <type> #<chat_id>, (e.g., user #12345678, bot #93372553) |
| chat_name | String | Chat name (e.g., “BotFather”) |
| html | String | Text content of the draft rendered as valid HTML. Formatting in the text is automatically converted to html tags |
This object represents an Ip address.
| Field | Type | Description |
|---|---|---|
| ip | String | Ip address |
This object represents a change event related to the user (e.g., a username change, name change, password change, etc.).
| Field | Type | Description |
|---|---|---|
| app_id | Integer | Id of the app where the event took place |
| country | String | ISO 3166-1 alpha-2 code of the country where the event took place |
| event | String | Currently, one of “username_change”, “name_change”, “password_change”, “phone_change” |
| ip | String | Ip address at the time the event took place |
| phone_country | String | ISO 3166-1 alpha-2 code of the country where the event took place, based on the phone number |
| session_age | String | Age of the session where the event took place, in seconds |
| timestamp | Integer | Unix timestamp of the event |
| new_username | String | Optional. Username after the change. Available for username_change events |
| old_username | String | Optional. Username before the change. Available for username_change events |
| new_name | String | Optional. Name after the change. Available for name_change events |
| old_name | String | Optional. Name before the change. Available for name_change events |
| new_phone | String | Optional. Phone number after the change. Available for phone_change events |
| old_phone | String | Optional. Phone number before the change. Available for phone_change events |
| String | Optional. Email before the change. Available for password_change events |
|
| new_email | String | Optional. Email after the change. Available for password_change events |
| hint | String | Optional. Password hint. Available for password_change events |
This object contains all chats in the export.
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| list | Array of Chat | Array of chats |
This object contains supergroups and channels that the user left or was banned from.
| Field | Type | Description |
|---|---|---|
| about | String | Brief description of the data exported herein |
| list | Array of Chat | Array of chats the user left or was banned from |
This object represents a chat.
| Field | Type | Description |
|---|---|---|
| id | Integer | Unique identifier for this chat. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier. |
| name | String | Name of the chat |
| type | String | Type of the chat, currently one of “saved_messages”, “replies”, “personal_chat”, “bot_chat”, “private_group”, “private_supergroup”, “public_supergroup”, “private_channel”, or “public_channel”. |
| messages | Array of Message | Array of messages in the chat. Note that public group and channel exports will only contain messages sent by the user requesting the export. |
This object represents a special entity in a text message. For example, hashtags, usernames, URLs, etc.
| Field | Type | Description |
|---|---|---|
| type | String | Type of the entity. Currently, one of “unknown”, “mention”, “hashtag”, “bot_command”, “link”, “email”, “bold”, “italic”, “code”, “pre”, “plain”, “text_link”, “mention_name”, “phone”, “cashtag”, “underline”, “strikethrough”, “blockquote”, “bank_card”, “spoiler”, “custom_emoji”. |
| text | String | Text this entity applies to |
This object represents a message.
| Field | Type | Description |
|---|---|---|
| id | Integer | Unique message identifier inside this chat |
| type | String | The type is message for regular messages and service for service messages |
| action | String | Optional. Service message action. Currently, one of “create_group”, “edit_group_title”, “edit_group_photo”, “delete_group_photo”, “invite_members”, “remove_members”, “join_group_by_link”, “create_channel”, “migrate_to_supergroup”, “migrate_from_group”, “pin_message”, “clear_history”, “score_in_game”, “send_payment”, “phone_call”, “take_screenshot”, “attach_menu_bot_allowed”, “web_app_bot_allowed”, “allow_sending_messages”, “allow_sending_messages”, “send_passport_values”, “joined_telegram”, “proximity_reached”, “requested_phone_number”, “group_call”, “invite_to_group_call”, “set_messages_ttl”, “group_call_scheduled”, “edit_chat_theme”, “join_group_by_request”, “send_webview_data”, “send_premium_gift”, “topic_created”, “topic_edit”, “suggest_profile_photo”, “requested_peer”, “gift_code_prize”, “giveaway_launch”, “set_chat_wallpaper”, “set_same_chat_wallpaper”. |
| date | String | Message date as an ISO 8601 timestamp (e.g., 2023-09-03T17:05:43) |
| date_unixtime | String | Message date as a unix timestamp (e.g., 1693753543) |
| from | String | Name of the message sender. Also available in proximity_reached actions, representing the name of the user or chat that is now in proximity of to. |
| from_id | String | Sender id as <type><id>, (e.g., user123456, channel123456, chat123456). Also available in proximity_reached actions, representing the user or chat that is now in proximity of “to_id”. |
| edited | String | Optional. Message edit date as an ISO 8601 timestamp (e.g., 2023-09-03T17:05:43) |
| edited_unixtime | String | Optional. Message date as a unix timestamp (e.g., 1693753543) |
| reply_to_message_id | Integer | Optional. If the message is a reply, ID of the original message |
| text | String or Array of String and MessageEntity | Text of the message. String if there are no entities. Otherwise, array of MessageEntity in the order they appear. Note that entities of type “plain” are unwrapped and represented in the array as a single string containing the text. Also holds the text of the keyboardButtonSimpleWebView that was pressed to open the web app in send_webview_data actions. |
| text_entities | Array of MessageEntity | Text of the message as an array of MessageEntity in the order they appear. Plain text is represented as an entity of type “plain” |
| members | Array of String | Optional. List of members, available for create_group, invite_members, remove_members and invite_to_group_call actions |
| actor | String | Optional. Name of the user or entity that performed the action; available if “action” is defined |
| actor_id | String | Optional. Id of the user or entity who performed the action; available if “action” is defined. Provided as <type><id> (e.g., user123456, channel123456, group123456) |
| photo | String | Optional. Relative path to a photo, if the message is a photo. Also available for compatible actions, currently edit_group_photo and suggest_profile_photo |
| width | String | Optional. Media width. Available with compatible media |
| height | String | Optional. Media height. Available with compatible media |
| file | String | Optional. Relative path to a file, if the message has any compatile media |
| thumbnail | String | Optional. Relative path to a media thumbnail, if present |
| self_destruct_period_seconds | Integer | Optional. Time to live, in seconds, for this message. Available in self-destructing messages |
| title | String | Optional. Chat, topic or music title. Available for create_group, create_channel, migrate_from_group, edit_group_title and topic_edit actions and audio_file media type. |
| inviter | String | Optional. Name of the user who created the invite link. Available for join_group_by_link actions |
| message_id | Integer | Optional. ID of the message the action refers to. Available for pin_message and set_same_chat_wallpaper. |
| game_message_id | Integer | Optional. ID of the game score message. Available for score_in_game actions |
| score | Integer | Optional. Game score. Available for score_in_game actions |
| amount | Integer | Optional. Price of the product in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). |
| currency | String | Optional. Three-letter ISO 4217 currency code. Available for send_payment actions |
| invoice_message_id | Integer | Optional. ID of the invoice message. Available for send_payment actions |
| recurring | String | Optional. Refers to the type of payment in send_payment actions. If available, must be one of used, init. |
| duration_seconds | Integer | Optional. Represents a duration. Available for phone_call actions and compatible media |
| discard_reason | String | Optional. Reason a call was discarded, available for phone_call actions. If available, must be one of “busy”, “disconnect”, “hangup”, “missed”. |
| information_text | String | Optional. Custom action text. See here. |
| reason_app_id | Integer | Optional. ID of an app through which we allowed a bot to send us messages. Available for allow_sending_messages actions. |
| reason_app_name | String | Optional. Name of an app through which we allowed a bot to send us messages. Available for allow_sending_messages actions. |
| reason_domain | String | Optional. Domain through which we authorized a bot to send us messages using the Telegram Login feature. Available for allow_sending_messages actions. |
| values | Array of String | Optional. Secure telegram passport value types requested. Available for “send_passport_values” actions. Can contain one or several of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address_information”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”, “phone_number”, “email”. |
| to_id | Integer | Optional. ID of the user or chat that subscribed to live geolocation proximity alerts. Available for proximity_reached actions. |
| to | String | Optional. Name of the user or chat that subscribed to live geolocation proximity alerts. Available for proximity_reached actions. |
| distance | Integer | Optional. Distance, in meters (0-100000). Available for proximity_reached actions. |
| period | Integer | Optional. New Time-To-Live of all messages sent in this chat; if 0, autodeletion was disabled. Available for set_messages_ttl actions. |
| schedule_date | Integer | Optional. When is this group call scheduled to start. Available for group_call_scheduled actions. |
| emoticon | String | Optional. Emoji that identifies the chat theme. Available for edit_chat_theme actions |
| cost | Integer | Optional. Price of a gifted Telegram Premium subscription in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). Available for send_premium_gift actions. |
| months | Integer | Optional. Duration of the gifted Telegram Premium subscription. Available for send_premium_gift and gift_code_prize actions |
| new_title | String | Optional. New topic title. Available for topic_edit actions |
| new_icon_emoji_id | String | Optional. New topic icon emoji id. Available for topic_edit actions |
| button_id | Integer | Optional. Button id contained in a keyboardButtonRequestPeer button. Available for requested_peer actions. |
| peer_id | Integer | Optional. Shared peer id. Available for requested_peer actions |
| author | String | Optional. Name of the author of this message for channel posts with signatures enabled |
| forwarded_from | String | Optional. Name of the peer this message was forwarded from |
| saved_from | String | Optional. Name of the chat this message was saved from |
| via_bot | String | Optional. If the message was sent via a bot, this field stores that bot's username |
| media_type | String | Optional. Media type of this message, if any. One of sticker, video_message, voice_message, animation, video_file, audio_file. |
| performer | String | Optional. Performer for this media. Available for media_type audio_file |
| mime_type | String | Optional. Media mime type. Unavailable for stickers |
| contact_information | Contact | Optional. Shared contact |
| contact_vcard | String | Optional. Relative path to the contact's exported vcard file |
| location_information | Location | Optional. Message is a shared location, information about the location |
| live_location_period_seconds | Integer | Optional. For live locations. Indicates how long the location should be shared, in seconds |
| place_name | String | Optional. Name of the venue shared by the user |
| address | String | Optional. Physical address of the venue shared by the user |
| game_title | String | Optional. Title of the HTML5 game sent via this message |
| game_description | String | Optional. Description of the HTML5 game sent via this message |
| game_link | String | Optional. Link to the HTML5 game sent via this message |
| invoice_information | Invoice | Optional. Invoice for a transaction on Telegram |
| poll | Poll | Optional. A Telegram poll. |
| gift_code | String | Optional. A gift code, available for gift_code_prize actions |
| boost_peer_id | Integer | Optional. Identifier of a chat or a user that created the gift code. Available for gift_code_prize actions |
| unclaimed | Boolean | Optional. True, if the gift code is unclaimed. Available for gift_code_prize actions |
| via_giveaway | Boolean | Optional. True, if the gift code was created for a giveaway. Available for gift_code_prize actions |
| giveaway_information | Giveaway | Optional. A Telegram giveaway |
Note, media paths may be replaced by a warning depending on your export media size threshold and mediatype exclusion filters.
This object represents a point on the map.
| Field | Type | Description |
|---|---|---|
| latitude | Float | Latitude as defined by the sender |
| longitude | Float | Longitude as defined by the sender |
This object contains basic information about an invoice.
| Field | Type | Description |
|---|---|---|
| title | String | Invoice title |
| description | String | Invoice description |
| amount | Integer | Price of the product in the smallest units of the currency (integer, not float/double). For example, for a price of US$ 1.45 pass amount = 145. See the exp parameter in currencies.json, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies). |
| currency | String | Three-letter ISO 4217 currency code |
| receipt_message_id | Integer | Optional. Receipt message id |
This object represents a Telegram poll.
| Field | Type | Description |
|---|---|---|
| question | String | Poll question, 1-300 characters |
| closed | String | Equals “true” if the poll is closed, “false” otherwise. |
| total_voters | Integer | Total voters in the poll |
| answers | Array of PollAnswer | Array of poll answers |
This object represents an answer to a Telegram poll.
| Field | Type | Description |
|---|---|---|
| text | String | Answer text, 1-100 characters |
| voters | Integer | How many people voted for this answer |
| chosen | String | Equals “true” if the user chose this answer, “false” otherwise. |
This object represents a Telegram giveaway.
| Field | Type | Description |
|---|---|---|
| quantity | Integer | Total number of subscriptions distributed as part of this giveaway |
| months | Integer | Duration, in months, of a subscription won via this giveaway |
| until_date | String | The date when the giveaway ends. ISO 8601 timestamp (e.g., 2023-11-13T14:37:50) |
| channels | Array of Integer | Array of channel ids participating in the giveaway |
And that's all for the current version of the export! For a more in-depth look or to make changes, feel free to consult the open source Telegram Desktop client code, as well as our detailed core API schema.