### React In-App Routing Example

Source: https://docs.bale.ai/miniapp

Use MemoryRouter from react-router-dom for in-app routing to ensure the BackButton functions correctly in the web client.

```javascript
import { MemoryRouter } from "react-router-dom";

<MemoryRouter>{/* Routes */}</MemoryRouter>;
```

--------------------------------

### Vue In-App Routing Example

Source: https://docs.bale.ai/miniapp

Configure Vue Router with createMemoryHistory to manage in-app routing, essential for the BackButton's proper operation on the web client.

```javascript
import { createMemoryHistory, createRouter } from 'vue-router';

const router = createRouter({
  history: createMemoryHistory(),
  routes: [...] 
});
```

--------------------------------

### Making API Requests

Source: https://docs.bale.ai

All API requests to the Bale AI Bot must be made over HTTPS to the following URL format: `https://tapi.bale.ai/bot<token>/METHOD_NAME`. The API supports GET and POST methods, and parameters can be sent via URL query string, `application/x-www-form-urlencoded`, `application/json` (except for file uploads), or `multipart/form-data` (for file uploads).

```APIDOC
## Making API Requests

All requests to the Bale AI Bot API must be made over HTTPS to the following URL format:
`https://tapi.bale.ai/bot<token>/METHOD_NAME`

### Supported Methods
- GET
- POST

### Parameter Encoding
- URL query string
- `application/x-www-form-urlencoded`
- `application/json` (not for file uploads)
- `multipart/form-data` (for file uploads)

### Response Structure
- `ok` (boolean): Indicates if the request was successful.
- `description` (string): Provides details about the request outcome.
- `result` (any): Contains the result of a successful request.
- `error_code` (integer): Represents the error code for failed requests.
- `parameters` (ResponseParameters): Optional field for error details that can aid in automatic error handling.
```

--------------------------------

### askReview

Source: https://docs.bale.ai

Requests the user to submit or edit a review for the bot. This method is available in new versions of Bale clients starting from November 2025. If the user is using an unsupported version, the review form will not be displayed.

```APIDOC
## askReview

### Description
Use this method to request the user to submit or edit a review for the bot. Calling it displays a dedicated form in the Bale client for the user to submit their rating and comments. Upon successful execution, it returns `True`.

This feature is available in new versions of Bale clients starting from November 2025 and is not active in older versions. If the user is using a version that does not support this feature, the satisfaction form will not be displayed.

This method is not present in the standard Telegram Bot libraries. To use it, you must send an HTTP request directly to the server (more details in the Creating a Request section).

### Parameters
#### Path Parameters
- **user_id** (Integer) - Required - The unique ID of the user for whom the satisfaction form will be displayed.
- **delay_seconds** (Integer) - Required - The delay in seconds from the time the method is called until the satisfaction form is displayed.

#### Notes
* The best time to call this method is immediately after a successful operation or providing a useful service to the user.
* Sending the satisfaction form does not guarantee its display to the user; the server may impose limitations based on user conditions and not show the form. However, there is no need for manual checking or specifying limitations by the developer for sending it.
* The satisfaction form is only displayed when the user is present in the bot's page or the bot's mini-app.
* For more accurate feedback, it is recommended to send the satisfaction form to users who have previously used your bot's services and avoid sending it to new users.
```

--------------------------------

### Get JWT Access Token

Source: https://docs.bale.ai/gateway

Obtain a JWT access token by authenticating with your client credentials. This token is required for subsequent API requests.

```bash
curl -X POST "https://safir.bale.ai/api/v2/auth/token" \
     -d "grant_type=client_credentials" \
     -d "client_secret={password}" \
     -d "scope=read" \
     -d "client_id={username}"
```

--------------------------------

### answerCallbackQuery

Source: https://docs.bale.ai

Answers a callback query sent via inline buttons, allowing the bot to display a quick feedback to the user. This method is available in client versions released after June 2025. If the `callback_query_id` starts with '1', the user is on an older version and does not support this feature.

```APIDOC
## answerCallbackQuery

### Description
Use this method to answer a callback query sent via inline buttons. This allows the bot to display quick feedback (like an alert or confirmation) to the user. This feature was added to Bale clients in June 2025 and is **not available in older versions**. To check if the user's client supports this feature, examine the `callback_query_id` field; if its value starts with `1`, it means the user is using an old version and does not support this capability. In such cases, you can display the desired information using alternative methods, such as sending a message.

Upon successful execution, it returns `True`.

Note: After an inline button is pressed by the user, the button remains in a waiting state until the `answerCallbackQuery` method is called. Therefore, you must call this method even if you don't need to display a message to the user (without using optional parameters).

### Parameters
#### Path Parameters
- **callback_query_id** (String) - Required - The unique ID of the callback query to answer.
- **text** (String) - Optional - The notification text to display to the user. If empty, nothing is displayed to the user, and the inline button simply exits the waiting state. Between 0 and 200 characters.
- **show_alert** (Boolean) - Optional - If `True`, the message is displayed as an alert. Otherwise, it is displayed as a notification at the top of the screen.
```

--------------------------------

### ready

Source: https://docs.bale.ai/miniapp

Informs Bale that the mini-app is ready to be displayed, completing the loading state. It's recommended to call this as soon as essential UI elements are loaded.

```APIDOC
## ready()

### Description
Notifies Bale that the mini-app is ready to be displayed. This completes the loading state. If not called, the loading state completes only when the page is fully loaded. It's recommended to call this as soon as possible after essential UI elements are loaded.
```

--------------------------------

### Direct Link to Main Mini App

Source: https://docs.bale.ai/miniapp

Use these URL formats to provide users with direct access to your Mini App. The `startapp` parameter can optionally pass data to your Mini App.

```html
https://ble.ir/<bot_username>?startapp
https://ble.ir/<bot_username>?startapp=<start_param>
```

--------------------------------

### Get Authentication Token

Source: https://docs.bale.ai/gateway

Obtain a JWT access token by authenticating with your client credentials. This token is required for subsequent API requests.

```APIDOC
## POST /auth/token

### Description
This API allows clients to authenticate using client credentials (client ID and client secret) and obtain an access token for subsequent requests. Request body parameters should be sent as form-data.

### Method
POST

### Endpoint
https://safir.bale.ai/api/v2/auth/token

### Headers
- Content-Type: `application/x-www-form-urlencoded`

### Request Body
- **grant_type** (string) - Required - The type of grant requested. Must be `client_credentials`. Example: `client_credentials`
- **client_secret** (string) - Required - The password associated with your client ID. Example: `password`
- **scope** (string) - Required - The requested access level. Must be `read`. Example: `read`
- **client_id** (string) - Required - Your client ID. Example: `username`

### Request Example
```curl
curl -X POST "https://safir.bale.ai/api/v2/auth/token" \
     -d "grant_type=client_credentials" \
     -d "client_secret={password}" \
     -d "scope=read" \
     -d "client_id={username}"
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token to be used for subsequent requests. Example: `e..f`
- **expires_in** (number) - The token's expiration time in seconds. Example: `43200`
- **scope** (string) - The requested access level. Example: `read`
- **token_type** (string) - The type of token. Example: `bearer`

#### Response Example
```json
{
  "access_token": "eyadffdasasdf....asdfadf",
  "expires_in": 43200,
  "scope": "read",
  "token_type": "bearer"
}
```

#### Error Responses
- **401 Unauthorized**: Invalid client authentication.
  ```json
  {
   "error": "invalid_client",
   "error_description": "Client authentication failed"
  }
  ```
- **400 Bad Request**: Missing or incorrect request parameters.
  `"Failed to Parse Request"`
- **500 Internal Server Error**: Internal server error.
  `{"type": 1, "code": 2, "message": "internal server error occurred"}`
```

--------------------------------

### Initialize Bale WebApp SDK

Source: https://docs.bale.ai/miniapp

Include this script tag in the `<head>` of your HTML file before any other scripts to initialize the Bale WebApp SDK. This makes the `window.Bale.WebApp` object available for interacting with the Bale client.

```html
<script src="https://tapi.bale.ai/miniapp.js?3"></script>
```

--------------------------------

### getFile

Source: https://docs.bale.ai

Retrieves basic information about a file and prepares it for download. Bots can currently download files up to 20 MB. Returns a File object upon successful execution.

```APIDOC
## getFile

### Description
This method is used to get basic information about a file and prepare it for download. Bots can currently download files up to 20 MB. Upon successful execution, a File object is returned. The file can then be downloaded via the link `https://tapi.bale.ai/file/bot<token>/<file_path>`, where `<file_path>` is obtained from the response. The link is guaranteed to be valid for one hour. When the link expires, a new one can be obtained by calling this method again.

### Method
POST

### Endpoint
/getFile

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file_id** (String) - Required - The identifier for the file whose information should be retrieved.

### Request Example
```json
{
  "file_id": "AgADBAADGqcxG4..."
}
```

### Response
#### Success Response (200)
- **File object** - Description: An object containing information about the file.

#### Response Example
```json
{
  "file_id": "AgADBAADGqcxG4...",
  "file_unique_id": "...",
  "file_size": 10000,
  "file_path": "photos/file_1.jpg"
}
```
```

--------------------------------

### WebAppInitData

Source: https://docs.bale.ai/miniapp

This object contains data sent when the mini app is opened.

```APIDOC
## WebAppInitData

This object contains data sent when the mini app is opened.

### Fields
- **query_id** (String) - A unique identifier for the mini app session.
- **user** (WebAppUser) - An object containing information about the current user.
- **auth_date** (Integer) - The time the mini app was opened in Unix format.
- **hash** (String) - The hashed value of all sent data. You can use it to validate data on the Bale server.
```

--------------------------------

### Request Payload for Sending OTP

Source: https://docs.bale.ai/gateway

Use this JSON payload to send an OTP request. Ensure the phone number is formatted correctly, starting with '98' and without a leading zero.

```json
{
  "phone": "989123456789",
  "otp": 111111
}
```

--------------------------------

### Send Text Message using Curl

Source: https://docs.bale.ai/safir

Example of sending a text message using curl. Replace placeholders with your actual API access key, bot ID, and phone number.

```bash
curl --location 'https://safir.bale.ai/api/v3/send_message' --header 'api-access-key: <user-api-access-key>' --header 'Content-Type: application/json' --data '{
  "request_id": "absdfgesjgo",
  "bot_id": 123456789,
  "phone_number": "989123456789",
  "message_data": {
    "message": {
      "text": "test text message"
    }
  }
}'
```

--------------------------------

### showScanQrPopup

Source: https://docs.bale.ai/miniapp

Opens the QR code scanner. It emits `qrTextReceived` when a QR code is scanned and `scanQrPopupClosed` when the scanner is closed.

```APIDOC
## showScanQrPopup(data)

### Description
Opens the QR code scanner. Emits `qrTextReceived` when a QR code is scanned and `scanQrPopupClosed` when the scanner is closed.

### Parameters
- **data** (any) - Data associated with showing the QR scanner (specific usage not detailed in source).
```

--------------------------------

### openLink

Source: https://docs.bale.ai/miniapp

Opens a specified URL in either Bale's internal browser or the device's default browser. If the `options` parameter has `try_instant_view` set to `true`, it will open in Bale's internal browser.

```APIDOC
## openLink(url, options)

### Description
Opens a specified URL in the internal browser of Bale or the default browser of the user's device.

### Parameters
- **url** (string) - Required - The URL to open.
- **options** (object) - Optional - An object that can contain additional options.
  - **try_instant_view** (boolean) - Optional - If true, the link will be opened in Bale's internal browser.
```

--------------------------------

### Send Text Message JSON Structure

Source: https://docs.bale.ai/safir

Use this JSON structure to send a plain text message. Ensure the phone number starts with '98' and includes the full 10 digits.

```json
{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "message": {
      "text": "<your-text-message>"
    }
  }
}
```

--------------------------------

### Send Multimedia Message JSON Structure

Source: https://docs.bale.ai/safir

To send multimedia messages (photos, videos), first upload the file using the upload file service to get a file ID. Then, include this file_id in the message_data.

```json
{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "message": {
      "text": "<your-message-caption>",
      "file_id": "<your-file-id>"
    }
  }
}
```

--------------------------------

### expand

Source: https://docs.bale.ai/miniapp

Expands the mini-app to a full-screen view.

```APIDOC
## expand()

### Description
Expands the mini-app to display in full-screen mode.
```

--------------------------------

### ThemeParams

Source: https://docs.bale.ai/miniapp

Mini apps can adapt their UI appearance to match the user's settings in the Bale application. This object contains the current theme data for the user.

```APIDOC
## ThemeParams

Mini apps can adapt their UI appearance to match the user's settings in the Bale application. This object contains the current theme data for the user.

### Fields
- **bg_color** (String) - Optional. Background color in `#RRGGBB` format.
- **text_color** (String) - Optional. Main text color in `#RRGGBB` format. Use for body text (headers, paragraphs, lists).
- **hint_color** (String) - Optional. Hint text color in `#RRGGBB` format. Use for placeholder text (e.g., in inputs), secondary descriptions, and faint subtitles.
- **link_color** (String) - Optional. Link color in `#RRGGBB` format. Use for links and clickable text.
- **button_color** (String) - Optional. Button color in `#RRGGBB` format. Use for the background of main buttons like confirmation buttons.
- **button_text_color** (String) - Optional. Button text color in `#RRGGBB` format. Use for text on colored buttons.
- **secondary_bg_color** (String) - Optional. Secondary background color in `#RRGGBB` format. Use for card backgrounds and sections separated from the main background.
- **header_bg_color** (String) - Optional. Header background color in `#RRGGBB` format. Use for the top bar of pages.
- **bottom_bar_bg_color** (String) - Optional. Bottom bar background color in `#RRGGBB` format. Use for fixed sections at the bottom of the page.
- **accent_text_color** (String) - Optional. Accent text color in `#RRGGBB` format. Use for highlighted text and high-importance text elements.
- **section_bg_color** (String) - Optional. Section background color in `#RRGGBB` format. Use in conjunction with `secondary_bg_color`.
- **section_header_text_color** (String) - Optional. Section header text color in `#RRGGBB` format. Use for section titles (e.g., 'Account Settings', 'Payment Information').
- **section_separator_color** (String) - Optional. Section separator color in `#RRGGBB` format.
- **subtitle_text_color** (String) - Optional. Subtitle text color in `#RRGGBB` format.
- **destructive_text_color** (String) - Optional. Text color for irreversible actions (e.g., 'Delete Account') in `#RRGGBB` format.
```

--------------------------------

### addToHomeScreen

Source: https://docs.bale.ai/miniapp

Displays a prompt to the user to add the mini-app shortcut to their device's home screen.

```APIDOC
## addToHomeScreen()

### Description
Triggers a prompt for the user to add the mini-app shortcut to their device's home screen.
```

--------------------------------

### getMe

Source: https://docs.bale.ai

A simple method to test the bot's authentication token. It requires no parameters and returns basic bot information.

```APIDOC
## getMe

### Description
A simple method to test the authentication token. This method requires no parameters and returns basic bot information in a User object.

### Method
GET or POST

### Endpoint
/getMe
```

--------------------------------

### SettingsButton

Source: https://docs.bale.ai/miniapp

This object is responsible for adding and controlling the 'Settings' option in the Bale UI header's context menu.

```APIDOC
## SettingsButton

This object is responsible for adding and controlling the 'Settings' option in the Bale UI header's context menu.

### Fields
- **isVisible** (Boolean) - Indicates whether the option is visible in the menu. Defaults to `false`.
- **onClick(callback)** (Function) - Registers an event handler for option clicks. Equivalent to `Bale.WebApp.onEvent('settingsButtonClicked', callback)`.
- **offClick(callback)** (Function) - Deactivates the option click event handler. Equivalent to `Bale.WebApp.offEvent('settingsButtonClicked', callback)`.
- **show()** (Function) - Method to make the 'Settings' option visible in the context menu.
- **hide()** (Function) - Method to hide the 'Settings' option in the context menu.
```

--------------------------------

### answerPreCheckoutQuery

Source: https://docs.bale.ai

Answers a pre-checkout query to confirm or decline a payment before it is finalized. Returns true on success.

```APIDOC
## answerPreCheckoutQuery

### Description
After user payment confirmation and just before finalizing it, a bot receives an update with the `_pre_checkout_query_` field. This method is used to respond to this request, either confirming or declining the payment before it is completed. Returns `true` if the method execution is successful.

**Note**: The bot must respond to a `PreCheckoutQuery` update within a maximum of **10 seconds**, otherwise the payment will be canceled.

### Method
POST

### Endpoint
/answerPreCheckoutQuery

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pre_checkout_query_id** (String) - Required - The unique identifier for the `PreCheckoutQuery` update.
- **ok** (Boolean) - Required - `true` indicates that everything is in order (payment details are correct, items are available, etc.) and the bot is ready to proceed with the order. Set to `false` if there are any issues.
- **error_message** (String) - Optional - Required if `ok` is `false`. Contains an error message explaining to the user why the payment cannot be processed (this message will be displayed to the user).

### Request Example
```json
{
  "pre_checkout_query_id": "query_id_12345",
  "ok": true
}
```

### Response
#### Success Response (200)
- **result** (Boolean) - `true` if the operation was successful.

#### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### checkHomeScreenStatus

Source: https://docs.bale.ai/miniapp

Checks if the mini-app shortcut can be added to the home screen and if it has already been added. It can optionally call a callback function with the status.

```APIDOC
## checkHomeScreenStatus(callback)

### Description
Checks the status of adding the mini-app shortcut to the home screen. If a callback function is provided, it will be invoked with the status.

### Parameters
- **callback** (function) - Optional - A function that will be called with a `status` argument.
  - **status** (string) - Possible values: `unsupported`, `unknown`, `added`, `missed`.
```

--------------------------------

### openInvoice

Source: https://docs.bale.ai/miniapp

Opens the payment screen within the mini-app. It accepts invoice parameters and an optional callback function to handle the payment status.

```APIDOC
## openInvoice(invoiceParams, callback)

### Description
Opens the payment screen within the mini-app. It accepts invoice parameters and an optional callback function that is executed after the payment process is completed.

### Parameters
- **invoiceParams** (object) - Required - The parameters received from the `createInvoiceLink` response.
- **callback** (function) - Optional - A function that will be called after the payment process is completed. It receives an object with a `status` field indicating the final payment status.
  - **status** (string) - Possible values: `paid`, `cancelled`, `failed`, `pending`.

### Behavior
When the payment screen is closed, the mini-app receives the `invoiceClosed` event.

### Note
Before using this method, you must first call the `createInvoiceLink` method and obtain the `invoiceParams` from its response.

### Warning
On some older Android versions, users might experience UX issues during the payment process. Consider using a Memory Router to resolve this.
```

--------------------------------

### WebAppUser

Source: https://docs.bale.ai/miniapp

This object contains data about the user interacting with the mini app.

```APIDOC
## WebAppUser

This object contains data about the user interacting with the mini app.

### Fields
- **id** (Integer) - The unique user ID.
- **first_name** (String) - The user's first name in Bale.
- **username** (String) - Optional. The user's username in Bale.
- **allows_write_to_pm** (Boolean) - Optional. `true` if the user has allowed Bale to send direct messages to them.
- **photo_url** (String) - Optional. The URL of the user's profile picture. This picture can be in `jpeg` or `svg` format.
```

--------------------------------

### Setting Content Security Policy Header

Source: https://docs.bale.ai/miniapp

Ensure the 'Content-Security-Policy' header with 'frame-src' directive is correctly set to allow Mini Apps to open within an iframe on the web version.

```http
Content-Security-Policy: frame-src 'https://*.bale.ai';
```

--------------------------------

### uploadStickerFile

Source: https://docs.bale.ai

This method is used to upload a file for future use in createNewStickerSet and addStickerToSet methods. The uploaded file can be reused multiple times. Upon successful execution, it returns the uploaded file.

```APIDOC
## uploadStickerFile

### Description
Uploads a file to be used for creating or adding stickers to a sticker set.

### Method
POST (assumed, as it involves file upload and state change)

### Endpoint
/uploadStickerFile

### Parameters
#### Form Data
- **user_id** (Integer) - Required - The user ID of the sticker file owner.
- **sticker** (InputFile) - Required - A file in .WEBP, .PNG, .TGS, or .WEBM format.
```

--------------------------------

### createNewStickerSet

Source: https://docs.bale.ai

Creates a new sticker set owned by the creator. The bot can edit the created sticker set. Upon successful execution, it returns True.

```APIDOC
## createNewStickerSet

### Description
Creates a new sticker set for a user.

### Method
POST (assumed, as it creates a new resource)

### Endpoint
/createNewStickerSet

### Parameters
#### Request Body
- **user_id** (Integer) - Required - The user ID of the owner of the created sticker set.
- **name** (String) - Required - A short name for the sticker set. Must contain English letters, numbers, or "_". Must start with a letter, cannot contain multiple consecutive underscores, and must end with "by_bot_username_". The bot_username is case-sensitive. Between 1 and 64 characters.
- **title** (String) - Required - The title of the sticker set, between 1 and 64 characters.
- **sticker** (Array of InputSticker) - Required - A JSON-serialized list containing 1 to 50 stickers to be added to the sticker set.
```

--------------------------------

### close

Source: https://docs.bale.ai/miniapp

Closes the mini-app.

```APIDOC
## close()

### Description
Closes the mini-app.
```

--------------------------------

### addStickerToSet

Source: https://docs.bale.ai

Adds a new sticker to a set created by the bot. The format of the added sticker must match the format of other stickers in the set. Emoji sticker sets can contain up to 200 stickers. Video sticker sets can contain up to 50 stickers. Regular sticker sets can contain up to 120 stickers. Upon successful execution, it returns True.

```APIDOC
## addStickerToSet

### Description
Adds a new sticker to an existing sticker set.

### Method
POST (assumed, as it modifies an existing resource)

### Endpoint
/addStickerToSet

### Parameters
#### Request Body
- **user_id** (Integer) - Required - The user ID of the sticker set owner.
- **name** (String) - Required - The name of the sticker set.
- **sticker** (InputSticker) - Required - A JSON-serialized object with information about the added sticker. If the exact same sticker is added, the sticker set will not change.
```

--------------------------------

### sendInvoice

Source: https://docs.bale.ai

Allows your bot to send a 'request money' message to users. Users can then pay the specified amount using their Bale Wallet. The payment token for the bot's wallet must be provided in the `provider_token` field.

```APIDOC
## sendInvoice

### Description
Sends a payment request to a user via their Bale Wallet.

### Method
POST (assumed, as it initiates a transaction)

### Endpoint
/sendInvoice

### Parameters
#### Request Body
- **provider_token** (String) - Required - The payment token for the bot's wallet. Use `WALLET-TEST-1111111111111111` for testing.
```

--------------------------------

### createInvoiceLink

Source: https://docs.bale.ai

Creates a new payment provider invoice link for use in mini apps. Returns the created invoice link upon success.

```APIDOC
## createInvoiceLink

### Description
Creates a new payment provider invoice link for use in mini apps. For more information, refer to the openInvoice documentation in the mini app documentation. Returns the created invoice link as a string upon success.

### Method
POST

### Endpoint
/createInvoiceLink

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **title** (String) - Required - The product name, between 1 and 32 characters.
- **description** (String) - Required - The product description, between 1 and 255 characters.
- **payload** (String) - Required - An invoice payload defined by the bot, between 1 and 128 bytes. This field is not displayed to the user and is used for internal processes. It is returned in the SuccessfulPayment update upon successful payment, allowing for the differentiation of payment requests.
- **provider_token** (String) - Required - The payment provider token obtained from @botfather.
- **prices** (Array of LabeledPrice) - Required - The purchase invoice, a JSON-serialized list of ordered products including the item title and price. The sum of these prices is considered the final amount.

### Request Example
```json
{
  "title": "Mini App Product",
  "description": "Purchase item for mini app.",
  "payload": "mini_app_payload_456",
  "provider_token": "YOUR_PROVIDER_TOKEN",
  "prices": [
    {
      "label": "Mini App Item",
      "amount": 10000
    }
  ]
}
```

### Response
#### Success Response (200)
- **invoice_link** (String) - The created invoice link.

#### Response Example
```json
{
  "invoice_link": "https://bale.ai/pay?invoice=abcdef12345"
}
```
```

--------------------------------

### sendAudio

Source: https://docs.bale.ai

Sends audio files. Audio files must be in `.MP3` or `.M4A` format. Returns the sent message upon success. Current bots can send audio files up to 50MB.

```APIDOC
## sendAudio

### Description
Use this method to send audio files. If you want Bale clients to display these files in a music player, use this method. Audio files must be in `.MP3` or `.M4A` format. Returns the sent message upon success. Current bots can send audio files up to 50MB. This limit may change in the future.

For sending voice messages, use the `sendVoice` method.

### Method
POST

### Endpoint
/sendAudio

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat_id** (String or Integer) - Required - The unique identifier of the target chat or channel (e.g., @channelusername).
- **audio** (InputFile or String) - Required - The audio file to send. Use a `file_id` string to send an audio file that exists on Bale servers (recommended), a URL string to have Bale fetch it from the internet, or upload a new audio file using multipart/form-data.
- **caption** (String) - Optional - Audio caption, between 0 and 4096 characters.
- **reply_to_message_id** (Integer) - Optional - If the message is a reply, ID of the original message.
- **reply_markup** (InlineKeyboardButton or ReplyKeyboardMarkup or ReplyKeyboardRemove) - Optional - Additional interface options. A JSON-serialized object for an inline keyboard, ReplyMarkup, or instructions to remove the reply keyboard.
```

--------------------------------

### createChatInviteLink

Source: https://docs.bale.ai

Creates a new invite link for a group.

```APIDOC
## createChatInviteLink

### Description
Creates a new invite link for a group.

### Parameters
#### Path Parameters
- **chat_id** (String or Integer) - Required - Unique identifier for the target chat or username of the target channel (in the format @channelusername)
```

--------------------------------

### setHeaderColor

Source: https://docs.bale.ai/miniapp

Sets the color of the mini-app's header using predefined color keys or a custom hex color.

```APIDOC
## setHeaderColor(color)

### Description
Sets the color of the mini-app's header using predefined color keys (`bg_color` or `secondary_bg_color`) or a custom hex color (in `RRGGBB#` format).

### Parameters
- **color** (string) - The color to set for the header. Can be a predefined key or a hex color string.
```

--------------------------------

### Handling Home Screen Status Event

Source: https://docs.bale.ai/miniapp

This event handler is called after checking if the Mini App is on the home screen. It provides a status indicating support, whether it's added, or if the status is unknown.

```javascript
Bale.WebApp.onEvent('homeScreenChecked', function(event) {
  // event.status can be 'unsupported', 'unknown', 'added', or 'missed'
});
```

--------------------------------

### promoteChatMember

Source: https://docs.bale.ai

Promotes or demotes a user in a group or channel. The bot must be an administrator with appropriate permissions. Returns True on success.

```APIDOC
## promoteChatMember

### Description
Promotes or demotes a user in a group or channel. The bot must be an administrator with appropriate permissions. To demote a user, set all Boolean parameters to False. Returns True on success.

### Method
POST

### Endpoint
/promoteChatMember

### Parameters
#### Path Parameters
- **chat_id** (String or Integer) - Required - The unique identifier for the target chat or the username of the target channel (in the format @channelusername)
- **user_id** (Integer) - Required - The unique identifier of the target user

#### Query Parameters
- **can_change_info** (Boolean) - Optional - If you want the admin to be able to change chat info, send True
- **can_post_messages** (Boolean) - Optional - User's ability to post messages
- **can_edit_messages** (Boolean) - Optional - User's ability to edit messages
- **can_delete_messages** (Boolean) - Optional - User's ability to delete messages
- **can_manage_video_chats** (Boolean) - Optional - Ability to manage video chats
- **can_invite_users** (Boolean) - Optional - Ability to invite users
- **can_restrict_members** (Boolean) - Optional - Ability to restrict users
```

--------------------------------

### Authentication API Response (Success)

Source: https://docs.bale.ai/gateway

Successful authentication returns an access token, its expiration time, scope, and token type.

```json
{
  "access_token": "eyadffdasasdf....asdfadf",
  "expires_in": 43200,
  "scope": "read",
  "token_type": "bearer"
}
```

--------------------------------

### Authentication API Response (Bad Request)

Source: https://docs.bale.ai/gateway

A bad request error is returned if required parameters are missing or incorrect.

```text
"Failed to Parse Request"
```

--------------------------------

### askReview(data)

Source: https://docs.bale.ai/miniapp

This method is used to request the user to submit or edit a review about their bot. It is similar to the askReview method in the main Bale API.

```APIDOC
## askReview(data)

### Description
Requests the user to submit or edit a review about their bot. This method is analogous to the `askReview` method found in the main Bale API.

### Parameters
#### Request Body
- **data** (object) - Required - An object containing review request parameters.
  - **delay_seconds** (integer) - Required - Specifies the delay in seconds from the method invocation until the review form is displayed to the user.
```

--------------------------------

### sendVideo

Source: https://docs.bale.ai

Sends video files. Bale clients support MPEG4 videos. Bots can send video files up to 50MB. Supports file_id, HTTP URL, or multipart/form-data upload.

```APIDOC
## sendVideo

### Description
This method is used to send video files. Bale clients support MPEG4 videos (other formats can be sent as Documents). Upon successful execution, the output will be the sent message. Currently, bots can send video files with a maximum size of 50MB. This limit may change in the future.

### Method
POST

### Endpoint
/sendVideo

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat_id** (String or Integer) - Required - The unique identifier for the target chat or username of the target channel (in the format @channelusername).
- **video** (InputFile or String) - Required - The video to send. Use a file_id string to send a video that exists on Bale servers (recommended), provide an HTTP URL string for Bale to download and send the video, or upload a new video using multipart/form-data.
- **caption** (String) - Optional - Video caption (can also be used when re-sending videos via _file_id_), between 0 and 4096 characters after parsing entities.
- **reply_to_message_id** (Integer) - Optional - If the message is a reply, ID of the original message.
- **reply_markup** (InlineKeyboardButton or ReplyKeyboardMarkup or ReplyKeyboardRemove) - Optional - Additional interface options for the bot. A JSON-serialized object that can be used for an inline keyboard, ReplyMarkup, or instructions to remove the reply keyboard.

### Request Example
```json
{
  "chat_id": "@channelusername",
  "video": "/path/to/your/video.mp4",
  "caption": "A beautiful sunset."
}
```

### Response
#### Success Response (200)
- **message** (object) - The sent message object.

#### Response Example
```json
{
  "ok": true,
  "result": {
    "message_id": 12345,
    "chat": {
      "id": 123456789,
      "type": "private",
      "username": "user1"
    },
    "date": 1678886400,
    "video": {
      "duration": 10,
      "width": 1920,
      "height": 1080,
      "file_id": "BAACAgIAAxkBAAIB_2XyZz...".
      "file_unique_id": "AQAD...".
      "file_size": 5242880
    },
    "caption": "A beautiful sunset."
  }
}
```
```

--------------------------------

### Upload File using Curl

Source: https://docs.bale.ai/safir

Use this cURL command to upload a file. The file is sent as form data, and you need to provide the path to the file and your API access key.

```curl
curl --location 'https://safir.bale.ai/api/v3/upload_file' \
 --header 'api-access-key:<user-access-token>' \
 --form 'file=@"<file-path>"'
```

--------------------------------

### onEvent

Source: https://docs.bale.ai/miniapp

Registers one or more event handlers to receive various events emitted by the mini-app.

```APIDOC
## onEvent(eventType, eventHandler)

### Description
Registers one or more functions (`eventHandler`) to receive different events that the mini-app can receive.

### Parameters
- **eventType** (string) - The type of event to listen for.
- **eventHandler** (function) - The function to be called when the event occurs.
```

--------------------------------

### sendInvoice

Source: https://docs.bale.ai

Sends a payment request as a purchase invoice to users and receives their payments. Returns the sent message upon successful execution.

```APIDOC
## sendInvoice

### Description
Sends a payment request as a purchase invoice to users and receives their payments. Returns the sent message upon successful execution.

### Method
POST

### Endpoint
/sendInvoice

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chat_id** (String or Integer) - Required - The unique identifier for the target chat or channel username (e.g., @channelusername).
- **title** (String) - Required - The product name, between 1 and 32 characters.
- **description** (String) - Required - The product description, between 1 and 255 characters.
- **payload** (String) - Required - An invoice payload defined by the bot, between 1 and 128 bytes. This field is not displayed to the user and is used for internal processes. It is returned in the SuccessfulPayment update upon successful payment, allowing for the differentiation of payment requests.
- **provider_token** (String) - Required - The payment provider token obtained from @botfather.
- **prices** (Array of LabeledPrice) - Required - The purchase invoice, a JSON-serialized list of ordered products including the item title and price. The sum of these prices is considered the final amount.
- **photo_url** (String) - Optional - URL of the product image for the invoice. Including an image of the product can enhance user experience.
- **reply_to_message_id** (Integer) - Optional - The ID of the original message this message is a reply to.

### Request Example
```json
{
  "chat_id": "123456789",
  "title": "Example Product",
  "description": "A detailed description of the example product.",
  "payload": "internal_payload_123",
  "provider_token": "YOUR_PROVIDER_TOKEN",
  "prices": [
    {
      "label": "Product Price",
      "amount": 50000
    }
  ],
  "photo_url": "http://example.com/product.jpg"
}
```

### Response
#### Success Response (200)
- **message** (Message) - The sent message object.

#### Response Example
```json
{
  "message": {
    "message_id": 1,
    "chat": {
      "id": "123456789",
      "type": "private"
    },
    "date": 1678886400,
    "invoice": {
      "title": "Example Product",
      "description": "A detailed description of the example product.",
      "start_parameter": "random_param",
      "currency": "IRR",
      "total_amount": 50000
    }
  }
}
```
```

--------------------------------

### enableClosingConfirmation

Source: https://docs.bale.ai/miniapp

Enables a confirmation dialog that appears when the user attempts to close the mini-app.

```APIDOC
## enableClosingConfirmation()

### Description
Enables a confirmation dialog to appear when the user tries to close the mini-app.
```

--------------------------------

### Registering Event Handler in JavaScript

Source: https://docs.bale.ai/miniapp

Use the Bale.WebApp.onEvent method to register a handler function for specific Mini App events. The 'this' keyword inside the handler refers to Bale.WebApp.

```javascript
Bale.WebApp.onEvent(eventType, eventHandler);
```

--------------------------------

### getWebhookInfo

Source: https://docs.bale.ai

Retrieves the current webhook status. This method requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, the output will be an object with an empty url field.

```APIDOC
## getWebhookInfo

### Description
Retrieves the current webhook status. This method requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, the output will be an object with an empty url field.

### Method
GET

### Endpoint
/getWebhookInfo

### Response
#### Success Response (200)
- **url** (String) - The URL of the webhook. Will be empty if no webhook is set.
```