├── README.md ├── dist └── index.d.ts └── package.json /README.md: -------------------------------------------------------------------------------- 1 | # Telegram Web Apps for Bots TypeScript typings 2 | 3 | TypeScript typings for Telegram Web Apps for Bots. See https://core.telegram.org/bots/webapps 4 | 5 | ## Usage 6 | 7 | ### Install the package 8 | 9 | Using `npm` 10 | 11 | ``` 12 | npm install telegram-webapps-types 13 | ``` 14 | 15 | ### If you are working on a `TypeScript` project 16 | 17 | Include the types file inside your [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) 18 | file like this: 19 | 20 | ```diff 21 | { 22 | "compilerOptions": { 23 | + "typeRoots": [ 24 | + "./node_modules/@types", 25 | + "./node_modules/telegram-webapps-types" 26 | + ] 27 | } 28 | } 29 | ``` 30 | 31 | ### If you are working on a `JavaScript` project 32 | 33 | > This step does not add types to your project, but it improves your autocompletion experience. This typically works 34 | > with all modern editors & IDEs. If you encounter an issue, check the documentation for your editor. 35 | 36 | 1. Create the [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig) file at the root of your project. 37 | 38 | 2. Add the following 39 | 40 | ```json 41 | { 42 | "compilerOptions": { 43 | "typeRoots": [ 44 | "./node_modules/@types", 45 | "./node_modules/telegram-webapps-types" 46 | ] 47 | } 48 | } 49 | ``` 50 | 51 | 3. You should be able to get autocompletion working inside your JavaScript project. 52 | -------------------------------------------------------------------------------- /dist/index.d.ts: -------------------------------------------------------------------------------- 1 | export declare namespace TelegramWebApps { 2 | interface SDK { 3 | WebApp: WebApp; 4 | } 5 | 6 | /** 7 | * Available app events. 8 | */ 9 | type EventType = "themeChanged" | "viewportChanged" | "mainButtonClicked"; 10 | 11 | interface WebApp { 12 | /** 13 | * A string with raw data transferred to the Web App, convenient for validating data. 14 | * WARNING: Validate data from this field before using it on the bot's server. 15 | */ 16 | initData: string; 17 | /** 18 | * An object with input data transferred to the Web App. 19 | * WARNING: Data from this field should not be trusted. 20 | * You should only use data from initData on the bot's server and only after it has been validated. 21 | */ 22 | initDataUnsafe: WebAppInitData; 23 | /** 24 | * The color scheme currently used in the Telegram app. Either “light” or “dark”. 25 | * Also available as the CSS variable var(--tg-color-scheme). 26 | */ 27 | colorScheme: "light" | "dark"; 28 | /** 29 | * An object containing the current theme settings used in the Telegram app. 30 | */ 31 | themeParams: ThemeParams; 32 | /** 33 | * True if the Web App is expanded to the maximum available height. 34 | * False, if the Web App occupies part of the screen and can be expanded to the full height using the expand() method. 35 | */ 36 | isExpanded: boolean; 37 | /** 38 | * The current height of the visible area of the Web App. Also available in CSS as the variable var(--tg-viewport-height). 39 | */ 40 | viewportHeight: number; 41 | /** 42 | * The height of the visible area of the Web App in its last stable state. Also available in CSS as a variable var(--tg-viewport-stable-height). 43 | */ 44 | viewportStableHeight: number; 45 | /** 46 | * An object for controlling the main button, which is displayed at the bottom of the Web App in the Telegram interface. 47 | */ 48 | MainButton: MainButton; 49 | /** 50 | * A method that sets the app event handler. 51 | */ 52 | onEvent(eventType: EventType, eventHandler: Function): void; 53 | /** 54 | * A method that deletes a previously set event handler. 55 | */ 56 | offEvent(eventType: EventType, eventHandler: Function): void; 57 | /** 58 | * A method used to send data to the bot. 59 | */ 60 | sendData(data): void; 61 | /** 62 | * A method that informs the Telegram app that the Web App is ready to be displayed. 63 | */ 64 | ready(): void; 65 | /** 66 | * A method that expands the Web App to the maximum available height. 67 | */ 68 | expand(): void; 69 | /** 70 | * A method that closes the Web App. 71 | */ 72 | close(): void; 73 | } 74 | 75 | interface ThemeParams { 76 | /** 77 | * Background color in the #RRGGBB format. 78 | * Also available as the CSS variable var(--tg-theme-bg-color). 79 | */ 80 | bg_color?: string; 81 | /** 82 | * Main text color in the #RRGGBB format. 83 | * Also available as the CSS variable var(--tg-theme-text-color). 84 | */ 85 | text_color?: string; 86 | /** 87 | * Hint text color in the #RRGGBB format. 88 | * Also available as the CSS variable var(--tg-theme-hint-color). 89 | */ 90 | hint_color?: string; 91 | /** 92 | * Link color in the #RRGGBB format. 93 | * Also available as the CSS variable var(--tg-theme-link-color). 94 | */ 95 | link_color?: string; 96 | /** 97 | * Button color in the #RRGGBB format. 98 | * Also available as the CSS variable var(--tg-theme-button-color). 99 | */ 100 | button_color?: string; 101 | /** 102 | * Button text color in the #RRGGBB format. 103 | * Also available as the CSS variable var(--tg-theme-button-text-color). 104 | */ 105 | button_text_color?: string; 106 | } 107 | 108 | interface WebAppInitData { 109 | /** 110 | * A unique identifier for the Web App session, required for sending messages via the answerWebAppQuery method. 111 | */ 112 | query_id?: string; 113 | /** 114 | * An object containing data about the current user. 115 | */ 116 | user?: WebAppUser; 117 | /** 118 | * An object containing data about the chat partner of the current user in the chat where the bot was launched via the attachment menu. Returned only for Web Apps launched via the attachment menu. 119 | */ 120 | receiver?: WebAppUser; 121 | /** 122 | * The value of the startattach parameter, passed via link. Only returned for Web Apps when launched from the attachment menu via link. 123 | */ 124 | start_param?: string; 125 | /** 126 | * Unix time when the form was opened. 127 | */ 128 | auth_date?: number; 129 | /** 130 | * A hash of all passed parameters, which the bot server can use to check their validity. 131 | */ 132 | hash?: string; 133 | } 134 | 135 | interface WebAppUser { 136 | /** 137 | * A unique identifier for the user or bot. 138 | */ 139 | id?: number; 140 | /** 141 | * True, if this user is a bot. Returns in the receiver field only. 142 | */ 143 | is_bot: boolean; 144 | /** 145 | * First name of the user or bot. 146 | */ 147 | first_name: string; 148 | /** 149 | * Last name of the user or bot. 150 | */ 151 | last_name?: string; 152 | /** 153 | * Username of the user or bot. 154 | */ 155 | username?: string; 156 | /** 157 | * IETF language tag of the user's language. Returns in user field only. 158 | */ 159 | language_code?: string; 160 | /** 161 | * URL of the user’s profile photo. The photo can be in .jpeg or .svg formats. Only returned for Web Apps launched from the attachment menu. 162 | */ 163 | photo_url?: string; 164 | } 165 | 166 | interface MainButton { 167 | /** 168 | * Current button text. Set to CONTINUE by default. 169 | */ 170 | text: string; 171 | /** 172 | * Current button color. Set to themeParams.button_color by default. 173 | */ 174 | color: string; 175 | /** 176 | * Current button text color. Set to themeParams.button_text_color by default. 177 | */ 178 | textColor: string; 179 | /** 180 | * Shows whether the button is visible. Set to false by default. 181 | */ 182 | isVisible: boolean; 183 | /** 184 | * Shows whether the button is active. Set to true by default. 185 | */ 186 | isActive: boolean; 187 | /** 188 | * Readonly. Shows whether the button is displaying a loading indicator. 189 | */ 190 | isProgressVisible: boolean; 191 | /** 192 | * A method to set the button text. 193 | */ 194 | setText(text: string): MainButton; 195 | /** 196 | * A method that sets the button press event handler. An alias for Telegram.WebApp.onEvent('mainButtonClicked', callback) 197 | */ 198 | onClick(callback: Function): MainButton; 199 | /** 200 | * A method to make the button visible. 201 | */ 202 | show(): MainButton; 203 | /** 204 | * A method to hide the button. 205 | */ 206 | hide(): MainButton; 207 | /** 208 | * A method to enable the button. 209 | */ 210 | enable(): MainButton; 211 | /** 212 | * A method to disable the button. 213 | */ 214 | disable(): MainButton; 215 | /** 216 | * A method to show a loading indicator on the button. 217 | */ 218 | showProgress(leaveActive: boolean): MainButton; 219 | /** 220 | * A method to hide the loading indicator. 221 | */ 222 | hideProgress(): MainButton; 223 | /** 224 | * A method to set the button parameters. 225 | */ 226 | setParams(params: MainButtonParams): MainButton; 227 | } 228 | 229 | interface MainButtonParams { 230 | /** 231 | * Button text. 232 | */ 233 | text?: string; 234 | /** 235 | * Button color. 236 | */ 237 | color?: string; 238 | /** 239 | * Button text color. 240 | */ 241 | text_color?: string; 242 | /** 243 | * Enable the button. 244 | */ 245 | is_active?: boolean; 246 | /** 247 | * Show the button. 248 | */ 249 | is_visible?: boolean; 250 | } 251 | } 252 | 253 | declare global { 254 | const Telegram: TelegramWebApps.SDK; 255 | } 256 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "telegram-webapps-types", 3 | "version": "1.0.5", 4 | "description": "TypeScript typings for Telegram Web Apps for Bots. See https://core.telegram.org/bots/webapps", 5 | "scripts": { 6 | "test": "echo \"Error: no test specified\" && exit 1" 7 | }, 8 | "repository": { 9 | "type": "git", 10 | "url": "git+https://github.com/prKassad/telegram-webapps-types.git" 11 | }, 12 | "keywords": [ 13 | "typescript", 14 | "bots", 15 | "telegram", 16 | "typings", 17 | "webapps" 18 | ], 19 | "author": "Vitaliy Abramov", 20 | "types": "./dist/index.d.ts", 21 | "license": "MIT", 22 | "bugs": { 23 | "url": "https://github.com/prKassad/telegram-webapps-types/issues" 24 | }, 25 | "homepage": "https://github.com/prKassad/telegram-webapps-types#readme" 26 | } 27 | --------------------------------------------------------------------------------