Skip to content

Commit 2e5dfd0

Browse files
authored
Merge pull request #580 from Telegram-Mini-Apps/feature/v8-emoji-status
Emoji status-related functions
2 parents a58fe0a + 8bd6d16 commit 2e5dfd0

File tree

19 files changed

+361
-13
lines changed

19 files changed

+361
-13
lines changed

.changeset/config.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@
88
"baseBranch": "master",
99
"updateInternalDependencies": "patch",
1010
"ignore": [
11+
"docs",
1112
"custom-playground",
13+
"vue-template",
14+
"svelte-template",
1215
"nextjs-template",
1316
"reactjs-template",
1417
"solidjs-template"

.changeset/hip-birds-whisper.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@telegram-apps/sdk": minor
3+
---
4+
5+
Add emoji status-related functionality.

.changeset/hungry-mails-buy.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 methods and events connected with custom emoji set.

apps/docs/.vitepress/packages.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ export const packagesLinksGenerator = (prefix: string = '') => {
109109
]),
110110
],
111111
'Utilities': [{ url: 'utils', page: false }, fromEntries([
112+
scope('emoji-status'),
112113
scope('links'),
113114
scope('privacy'),
114115
scope('uncategorized'),
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Emoji Status
2+
3+
## `requestEmojiStatusAccess`
4+
5+
To request access to user emoji status update, use the `requestEmojiStatusAccess` function:
6+
7+
::: code-group
8+
9+
```ts [Using isAvailable]
10+
import { requestEmojiStatusAccess } from '@telegram-apps/sdk';
11+
12+
if (requestEmojiStatusAccess.isAvailable()) {
13+
const status = await requestEmojiStatusAccess();
14+
}
15+
```
16+
17+
```ts [Using ifAvailable]
18+
import { requestEmojiStatusAccess } from '@telegram-apps/sdk';
19+
20+
const status = await requestEmojiStatusAccess.ifAvailable();
21+
```
22+
23+
:::
24+
25+
## `setEmojiStatus`
26+
27+
To set an emoji status on user's behalf, use the `setEmojiStatus` function.
28+
29+
As the first argument, it accepts a custom emoji id. Optionally, you can pass the second
30+
argument determining for how many seconds the status must be set.
31+
32+
::: code-group
33+
34+
```ts [Using isAvailable]
35+
import { setEmojiStatus } from '@telegram-apps/sdk';
36+
37+
if (setEmojiStatus.isAvailable()) {
38+
// Set for unlimited period of time.
39+
await setEmojiStatus('5361800828313167608');
40+
41+
// Set for 1 day.
42+
await setEmojiStatus('5361800828313167608', 86400);
43+
}
44+
```
45+
46+
```ts [Using ifAvailable]
47+
import { setEmojiStatus } from '@telegram-apps/sdk';
48+
49+
// Set for unlimited period of time.
50+
await setEmojiStatus.ifAvailable('5361800828313167608');
51+
52+
// Set for 1 day.
53+
await setEmojiStatus.ifAvailable('5361800828313167608', 86400);
54+
```
55+
56+
:::

apps/docs/platform/events.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,32 @@ Custom method invocation completed.
191191
| result | `unknown` | _Optional_. Method invocation result. |
192192
| error | `string` | _Optional_. Method invocation error code. |
193193

194+
### `emoji_status_access_requested`
195+
196+
Available since: **v8.0**
197+
198+
Access to set custom emoji status was requested.
199+
200+
| Field | Type | Description |
201+
|--------|----------|------------------------------------------------------------|
202+
| status | `string` | Request status. Possible values: `allowed` or `cancelled`. |
203+
204+
### `emoji_status_failed`
205+
206+
Available since: **v8.0**
207+
208+
Failed to set custom emoji status.
209+
210+
| Field | Type | Description |
211+
|-------|----------|-----------------------------------------------------------------------------------------|
212+
| error | `string` | Emoji set failure reason. Possible values: `SUGGESTED_EMOJI_INVALID` or `USER_DECLINED` |
213+
214+
### `emoji_status_set`
215+
216+
Available since: **v8.0**
217+
218+
Custom emoji status set.
219+
194220
### `fullscreen_changed`
195221

196222
Available since: **v8.0**

apps/docs/platform/methods.md

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ Opens the biometric access settings for bots. Useful when you need to request bi
128128
access to users who haven't granted it yet.
129129

130130
> [!INFO]
131-
> This method can be called only in response to user interaction with the Mini App interface
131+
> This method can be called only in response to user interaction with the Mini App interface
132132
> (e.g. a click inside the Mini App or on the main button)
133133
134134
### `web_app_biometry_request_access`
@@ -388,6 +388,12 @@ Requests the current content safe area information from Telegram.
388388
As a result, Telegram triggers the
389389
[**`content_safe_area_changed`**](events.md#content-safe-area-changed) event.
390390

391+
### `web_app_request_emoji_status_access`
392+
393+
Available since: **v8.0**
394+
395+
Shows a native popup requesting permission for the bot to manage user's emoji status.
396+
391397
### `web_app_request_fullscreen`
392398

393399
Available since: **v8.0**
@@ -445,6 +451,17 @@ Updates the Mini App bottom bar background color.
445451
|-------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
446452
| color | `string` | The Mini App bottom bar background color in `#RRGGBB` format, or one of the values: `bg_color`, `secondary_bg_color` or `bottom_bar_bg_color` |
447453

454+
### `web_app_set_emoji_status`
455+
456+
Available since: **v8.0**
457+
458+
Opens a dialog allowing the user to set the specified custom emoji as their status.
459+
460+
| Field | Type | Description |
461+
|-----------------|----------|----------------------------------------------------|
462+
| custom_emoji_id | `string` | Custom emoji identifier to set. |
463+
| duration | `number` | _Optional_. The status expiration time in seconds. |
464+
448465
### `web_app_set_header_color`
449466

450467
Available since: **v6.1**

packages/bridge/src/events/types/events.ts

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import type { RGB } from '@telegram-apps/types';
22

3-
import type {
3+
import {
44
PhoneRequestedStatus,
55
InvoiceStatus,
66
WriteAccessRequestedStatus,
@@ -9,6 +9,8 @@ import type {
99
BiometryTokenUpdateStatus,
1010
SafeAreaInsets,
1111
FullScreenErrorStatus,
12+
EmojiStatusAccessRequestedStatus,
13+
EmojiStatusFailedError,
1214
} from './misc.js';
1315

1416
/**
@@ -150,6 +152,31 @@ export interface Events {
150152
*/
151153
error?: string;
152154
};
155+
/**
156+
* Request to set custom emoji status was requested.
157+
* @see https://docs.telegram-mini-apps.com/platform/events#emoji-status-access-requested
158+
* @since v8.0
159+
*/
160+
emoji_status_access_requested: {
161+
/**
162+
* Request status.
163+
*/
164+
status: EmojiStatusAccessRequestedStatus;
165+
};
166+
/**
167+
* Failed to set custom emoji status.
168+
* @see https://docs.telegram-mini-apps.com/platform/events#emoji-status-failed
169+
* @since v8.0
170+
*/
171+
emoji_status_failed: {
172+
error: EmojiStatusFailedError;
173+
};
174+
/**
175+
* Custom emoji status set.
176+
* @see https://docs.telegram-mini-apps.com/platform/events#emoji-status-set
177+
* @since v8.0
178+
*/
179+
emoji_status_set: never;
153180
/**
154181
* App entered or exited fullscreen mode.
155182
* @since v8.0

packages/bridge/src/events/types/misc.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ export type InvoiceStatus =
77

88
export type PhoneRequestedStatus = 'sent' | 'cancelled' | string;
99

10+
export type EmojiStatusAccessRequestedStatus = 'allowed' | string;
11+
12+
export type EmojiStatusFailedError = 'SUGGESTED_EMOJI_INVALID' | 'USER_DECLINED' | string;
13+
1014
export type WriteAccessRequestedStatus = 'allowed' | string;
1115

1216
export type BiometryType = 'finger' | 'face' | string;

packages/bridge/src/methods/supports.test.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,9 @@ describe.each<[
118118
]],
119119
['8.0', [
120120
'web_app_request_fullscreen',
121-
'web_app_exit_fullscreen'
121+
'web_app_exit_fullscreen',
122+
'web_app_set_emoji_status',
123+
'web_app_request_emoji_status_access',
122124
]],
123125
])('%s', (version, methods) => {
124126
const higher = increaseVersion(version, 1);

0 commit comments

Comments
 (0)