Skip to content

Commit 0bf19ec

Browse files
heyqbnkheyqbnk
authored
Merge pull request #637 from Telegram-Mini-Apps/feature/v8-methods-and-events
Feature/v8 methods and events
2 parents 6408dfa + 73fd6c1 commit 0bf19ec

File tree

8 files changed

+637
-1
lines changed

8 files changed

+637
-1
lines changed

‎.changeset/tiny-beds-trade.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@telegram-apps/bridge": minor
3+
---
4+
5+
Add v8 methods and events.

‎apps/docs/platform/events.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,40 @@ package's [documentation](../packages/telegram-apps-bridge/events.md#listening-t
104104
This section contains the list of events, sent from Telegram: their names, description, and
105105
parameters. Section title means minimal version, from which events inside the section could be sent.
106106

107+
### `accelerometer_changed`
108+
109+
Available since: **v8.0**
110+
111+
Accelerometer data changed.
112+
113+
| Field | Type | Description |
114+
|-------|----------|-----------------------------------------------------------|
115+
| x | `number` | The current acceleration in the X-axis, measured in m/s². |
116+
| y | `number` | The current acceleration in the Y-axis, measured in m/s². |
117+
| z | `number` | The current acceleration in the Z-axis, measured in m/s². |
118+
119+
### `accelerometer_failed`
120+
121+
Available since: **v8.0**
122+
123+
Failed to start accelerometer data tracking.
124+
125+
| Field | Type | Description |
126+
|-------|----------|-----------------|
127+
| error | `string` | Occurred error. |
128+
129+
### `accelerometer_started`
130+
131+
Available since: **v8.0**
132+
133+
Accelerometer data tracking started.
134+
135+
### `accelerometer_stopped`
136+
137+
Available since: **v8.0**
138+
139+
Accelerometer data tracking stopped.
140+
107141
### `back_button_pressed`
108142

109143
Available since: **v6.1**
@@ -191,6 +225,41 @@ Custom method invocation completed.
191225
| result | `unknown` | _Optional_. Method invocation result. |
192226
| error | `string` | _Optional_. Method invocation error code. |
193227

228+
### `device_orientation_changed`
229+
230+
Available since: **v8.0**
231+
232+
Device orientation data changed.
233+
234+
| Field | Type | Description |
235+
|----------|-----------|------------------------------------------------------------------------------------------------------------|
236+
| absolute | `boolean` | _Optional_. A boolean that indicates whether the device is providing orientation data in absolute values. |
237+
| alpha | `number` | The rotation around the Z-axis, measured in radians. |
238+
| beta | `number` | The rotation around the X-axis, measured in radians. |
239+
| gamma | `number` | The rotation around the Y-axis, measured in radians. |
240+
241+
### `device_orientation_failed`
242+
243+
Available since: **v8.0**
244+
245+
Device orientation data tracking failed to start.
246+
247+
| Field | Type | Description |
248+
|-------|----------|-----------------|
249+
| error | `string` | Occurred error. |
250+
251+
### `device_orientation_started`
252+
253+
Available since: **v8.0**
254+
255+
Device orientation data tracking started.
256+
257+
### `device_orientation_stopped`
258+
259+
Available since: **v8.0**
260+
261+
Device orientation data tracking stopped.
262+
194263
### `emoji_status_access_requested`
195264

196265
Available since: **v8.0**
@@ -217,6 +286,14 @@ Available since: **v8.0**
217286

218287
Custom emoji status set.
219288

289+
### `file_download_requested`
290+
291+
Available since: **v8.0**
292+
293+
| Field | Type | Description |
294+
|--------|----------|------------------------------------------------------------------|
295+
| status | `string` | Request status. Set to `downloading` if the is being downloaded. |
296+
220297
### `fullscreen_changed`
221298

222299
Available since: **v8.0**
@@ -237,6 +314,40 @@ Occurs whenever the mini app enters or exits the fullscreen mode.
237314
|-------|----------|---------------------------------------------------------------------------------------|
238315
| error | `string` | Fullscreen mode status error. Possible values: `UNSUPPORTED` or `ALREADY_FULLSCREEN`. |
239316

317+
### `gyroscope_changed`
318+
319+
Available since: **v8.0**
320+
321+
Gyroscope data changed.
322+
323+
| Field | Type | Description |
324+
|-------|----------|-----------------------------------------------------------------|
325+
| x | `number` | The current rotation rate around the X-axis, measured in rad/s. |
326+
| y | `number` | The current rotation rate around the Y-axis, measured in rad/s. |
327+
| z | `number` | The current rotation rate around the Z-axis, measured in rad/s. |
328+
329+
### `gyroscope_failed`
330+
331+
Available since: **v8.0**
332+
333+
Gyroscope data tracking failed to run.
334+
335+
| Field | Type | Description |
336+
|-------|----------|-----------------|
337+
| error | `string` | Occurred error. |
338+
339+
### `gyroscope_started`
340+
341+
Available since: **v8.0**
342+
343+
Gyroscope data tracking started.
344+
345+
### `gyroscope_stopped`
346+
347+
Available since: **v8.0**
348+
349+
Gyroscope data tracking stopped.
350+
240351
### `home_screen_added`
241352

242353
Available since: **v8.0**
@@ -275,6 +386,37 @@ An invoice was closed.
275386
| slug | `string` | Passed during the [web_app_open_invoice](methods.md#web-app-open-invoice) method invocation `slug` value. |
276387
| status | `string` | Invoice status. Possible values: `paid`, `failed`, `pending` or `cancelled`. |
277388

389+
### `location_checked`
390+
391+
Available since: **v8.0**
392+
393+
Location-related functionality availability status was retrieved.
394+
395+
| Field | Type | Description |
396+
|------------------|-----------|-------------------------------------------------------------------|
397+
| available | `boolean` | Shows whether location tracking is available. |
398+
| access_requested | `boolean` | Shows whether permission to location tracking has been requested. |
399+
| access_granted | `boolean` | Shows whether permission to location tracking has been granted. |
400+
401+
### `location_requested`
402+
403+
Available since: **v8.0**
404+
405+
The application received the information about the current user location.
406+
407+
| Field | Type | Description |
408+
|---------------------|-----------|-------------------------------------------------------------------------------------------------------|
409+
| available | `boolean` | Shows whether location tracking is available. |
410+
| latitude | `number` | Latitude in degrees. Set only if `available` is True. |
411+
| longitude | `number` | Longitude in degrees. Set only if `available` is True. |
412+
| altitude | `number` | _Optional_. Altitude above sea level in meters. Set only if `available` is True. |
413+
| course | `number` | _Optional_. The direction the device is moving in degrees. Set only if `available` is True. |
414+
| speed | `number` | _Optional_. The speed of the device in m/s. Set only if `available` is True. |
415+
| horizontal_accuracy | `number` | _Optional_. Accuracy of the latitude and longitude values in meters. Set only if `available` is True. |
416+
| vertical_accuracy | `number` | _Optional_. Accuracy of the altitude value in meters. Set only if `available` is True. |
417+
| course_accuracy | `number` | _Optional_. Accuracy of the course value in degrees. Set only if `available` is True. |
418+
| speed_accuracy | `number` | _Optional_. Accuracy of the speed value in m/s. Set only if `available` is True. |
419+
278420
### `main_button_pressed`
279421

280422
User clicked the [Main Button](main-button.md).
@@ -297,6 +439,22 @@ Application received phone access request status.
297439
|-----------|----------|-----------------------------------------------------------------------------------------------------------------------------------------|
298440
| button_id | `string` | _Optional_. Identifier of the clicked button. In case, the popup was closed without clicking any button, this property will be omitted. |
299441

442+
### `prepared_message_failed`
443+
444+
Available since: **v8.0**
445+
446+
Failed to send a prepared message.
447+
448+
| Field | Type | Description |
449+
|-------|----------|-----------------|
450+
| error | `string` | Occurred error. |
451+
452+
### `prepared_message_sent`
453+
454+
Available since: **v8.0**
455+
456+
A prepared message was sent.
457+
300458
### `qr_text_received`
301459

302460
Available since: **v6.4**

‎apps/docs/platform/methods.md‎

Lines changed: 106 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ have this interface:
1919
```typescript
2020
interface MessageJSON {
2121
eventType: string;
22-
eventData: any;
22+
eventData?: any;
2323
}
2424
```
2525

@@ -177,6 +177,12 @@ Available since: **v8.0**
177177
Sends a request to the native Telegram application to check if the current mini
178178
application is added to the device's home screen.
179179

180+
### `web_app_check_location`
181+
182+
Available since: **v8.0**
183+
184+
Requests location-related functionality availability state.
185+
180186
### `web_app_close`
181187

182188
Closes Mini App.
@@ -240,6 +246,17 @@ Opens link in the default browser. Mini App will not be closed.
240246
| url | `string` | URL to be opened by Telegram application. Should be a full path with `https` protocol. | |
241247
| try_instant_view | `boolean` | _Optional_. Link will be opened in [Instant View](https://instantview.telegram.org/) mode if possible. | `v6.4` |
242248

249+
### `web_app_open_location_settings`
250+
251+
Available since: **v8.0**
252+
253+
Opens the location access settings for bots. Useful when you need to request location access
254+
from users who haven't granted it yet.
255+
256+
> [!WARNING]
257+
> Note that this method can be called only in response to user interaction with the Mini App
258+
> interface (e.g., a click inside the Mini App or on the main button).
259+
243260
### `web_app_open_popup`
244261

245262
Available since: **v6.2**
@@ -409,12 +426,29 @@ Available since: **v8.0**
409426

410427
Shows a native popup requesting permission for the bot to manage user's emoji status.
411428

429+
### `web_app_request_file_download`
430+
431+
Available since: **v8.0**
432+
433+
Displays a native popup prompting the user to download a file.
434+
435+
| Field | Type | Description |
436+
|-----------|----------|---------------------------------------------|
437+
| url | `string` | The HTTPS URL of the file to be downloaded. |
438+
| file_name | `string` | The suggested name for the downloaded file. |
439+
412440
### `web_app_request_fullscreen`
413441

414442
Available since: **v8.0**
415443

416444
Requests full screen mode for mini app.
417445

446+
### `web_app_request_location`
447+
448+
Available since: **v8.0**
449+
450+
Requests location data.
451+
418452
### `web_app_request_phone`
419453

420454
Available since: **v6.9**
@@ -446,6 +480,16 @@ Available since: **v6.9**
446480

447481
Requests write message access to current user.
448482

483+
### `web_app_send_prepared_message`
484+
485+
Available since: **v8.0**
486+
487+
Opens a dialog allowing the user to share a message provided by the bot.
488+
489+
| Field | Type | Description |
490+
|-------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
491+
| id | `string` | Identifier of the message ([PreparedInlineMessage](https://core.telegram.org/bots/api#preparedinlinemessage)) previously obtained via the Bot API method [savePreparedInlineMessage](https://core.telegram.org/bots/api#savepreparedinlinemessage). |
492+
449493
### `web_app_set_background_color`
450494

451495
Available since: **v6.1**
@@ -555,6 +599,55 @@ A method that opens the native story editor.
555599
| widget_link.url | `string` | The URL to be included in the story. |
556600
| widget_link.name | `string` | _Optional_. The name to be displayed for the widget link, 0-48 characters. |
557601

602+
### `web_app_start_accelerometer`
603+
604+
Available since: **v8.0**
605+
606+
Starts tracking accelerometer data.
607+
608+
| Field | Type | Description |
609+
|--------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
610+
| refresh_rate | `number` | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value. |
611+
612+
### `web_app_start_device_orientation`
613+
614+
Available since: **v8.0**
615+
616+
Starts tracking device orientation data.
617+
618+
| Field | Type | Description |
619+
|---------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
620+
| refresh_rate | `number` | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value. |
621+
| need_absolute | `boolean` | _Optional_. Pass true to receive absolute orientation data, allowing you to determine the device's attitude relative to magnetic north. Use this option if implementing features like a compass in your app. If relative data is sufficient, pass false. <br/><br/> Keep in mind that some devices may not support absolute orientation data. In such cases, you will receive relative data even if need_absolute=true is passed. |
622+
623+
### `web_app_start_gyroscope`
624+
625+
Available since: **v8.0**
626+
627+
Starts tracking gyroscope data.
628+
629+
| Field | Type | Description |
630+
|--------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
631+
| refresh_rate | `number` | The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that `refresh_rate` may not be supported on all platforms, so the actual tracking frequency may differ from the specified value. |
632+
633+
### `web_app_stop_accelerometer`
634+
635+
Available since: **v8.0**
636+
637+
Stops tracking accelerometer data.
638+
639+
### `web_app_stop_device_orientation`
640+
641+
Available since: **v8.0**
642+
643+
Stops tracking device orientation data.
644+
645+
### `web_app_stop_gyroscope`
646+
647+
Available since: **v8.0**
648+
649+
Stops tracking gyroscope data.
650+
558651
### `web_app_setup_secondary_button`
559652

560653
Available since: **v7.10**
@@ -710,6 +803,18 @@ the specified inline query in the input field.
710803
</tbody>
711804
</table>
712805

806+
### `web_app_toggle_orientation_lock`
807+
808+
Available since: **v8.0**
809+
810+
Locks the Mini App’s orientation to its current mode (either portrait or landscape). Once locked,
811+
the orientation remains fixed, regardless of device rotation. This is useful if a stable orientation
812+
is needed during specific interactions.
813+
814+
| Field | Type | Description |
815+
|--------|-----------|-----------------------------------------|
816+
| locked | `boolean` | True if the orientation must be locked. |
817+
713818
### `web_app_trigger_haptic_feedback`
714819

715820
Available since: **v6.1**

0 commit comments

Comments
 (0)