### Authorization Parameter Example

Source: https://core.telegram.org/gateway/api

Shows how to pass your access token as a query parameter in API requests.

```HTTP
access_token=<token>
```

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

### Authorization Header Example

Source: https://core.telegram.org/gateway/api

Demonstrates how to include your access token in the Authorization header for API requests.

```HTTP
Authorization: Bearer <token>
```

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

### API Base URL Example

Source: https://core.telegram.org/gateway/api

This is the base URL for all API requests. Ensure you append the specific method name to this base.

```HTTP
https://gatewayapi.telegram.org/sendVerificationMessage
```

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

### VerificationStatus Object

Source: https://core.telegram.org/gateway/api

Represents the verification status of a code, including its current state, the time of the last update, and optionally, the code that was entered.

```APIDOC
## VerificationStatus Object

### Description
This object represents the verification status of a code.

### Fields
- **status** (String) - The current status of the verification process. Possible values: `code_valid`, `code_invalid`, `code_max_attempts_exceeded`, `expired`.
- **updated_at** (Integer) - The timestamp for this particular status. Represents the time when the status was last updated.
- **code_entered** (String) - _Optional._ The code entered by the user.
```

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

### __checkSendAbility

Source: https://core.telegram.org/gateway/api

Checks the ability to send a verification message to a specified phone number. If successful, a fee may apply, and a request_id is returned for subsequent use with sendVerificationMessage. This method is free when checking your own number.

```APIDOC
## __checkSendAbility

### Description
Use this method to optionally check the ability to send a verification message to the specified phone number. If the ability to send is confirmed, a fee will apply according to the pricing plan. After checking, you can send a verification message using the sendVerificationMessage method, providing the _request_id_ from this response. Within the scope of a _request_id_ , only one fee can be charged. Calling sendVerificationMessage once with the returned _request_id_ will be free of charge, while repeated calls will result in an error. Conversely, calls that don't include a _request_id_ will spawn new requests and incur the respective fees accordingly. Note that this method is always free of charge when used to send codes to your own phone number.
In case the message can be sent, returns a RequestStatus object. Otherwise, an appropriate error will be returned.

### Method
POST (assumed, as it modifies state or requires parameters)

### Endpoint
/checkSendAbility

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **phone_number** (String) - Yes - The phone number for which you want to check our ability to send a verification message, in the E.164 format.

### Request Example
```json
{
  "phone_number": "+1234567890"
}
```

### Response
#### Success Response (200)
- **RequestStatus** (Object) - Represents the status of a verification message request.

#### Response Example
```json
{
  "request_id": "some_unique_request_id",
  "phone_number": "+1234567890",
  "request_cost": 0.05,
  "is_refunded": false,
  "remaining_balance": 1.95,
  "delivery_status": {
    "status": "sent",
    "updated_at": 1678886400
  },
  "verification_status": "pending",
  "payload": "optional_payload"
}
```
```

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

### sendVerificationMessage

Source: https://core.telegram.org/gateway/api

Sends a verification message to a specified phone number. Charges apply for successful deliveries, but requests can be free if a `request_id` from `checkSendAbility` is provided. The method returns a `RequestStatus` object upon success.

```APIDOC
## sendVerificationMessage

### Description
Use this method to send a verification message. Charges will apply according to the pricing plan for each successful message delivery. Note that this method is always free of charge when used to send codes to your own phone number. On success, returns a RequestStatus object.

### Method
GET, POST

### Endpoint
`https://gatewayapi.telegram.org/sendVerificationMessage`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **phone_number** (String) - Yes - The phone number to which you want to send a verification message, in the E.164 format.
- **request_id** (String) - Optional - The unique identifier of a previous request from checkSendAbility. If provided, this request will be free of charge.
- **sender_username** (String) - Optional - Username of the Telegram channel from which the code will be sent. The specified channel, if any, must be verified and owned by the same account who owns the Gateway API token.
- **code** (String) - Optional - The verification code. Use this parameter if you want to set the verification code yourself. Only fully numeric strings between 4 and 8 characters in length are supported. If this parameter is set, `code_length` is ignored.
- **code_length** (Integer) - Optional - The length of the verification code if Telegram needs to generate it for you. Supported values are from 4 to 8. This is only relevant if you are not using the `code` parameter to set your own code. Use the checkVerificationStatus method with the `code` parameter to verify the code entered by the user.
- **callback_url** (String) - Optional - An HTTPS URL where you want to receive delivery reports related to the sent message, 0-256 bytes.
- **payload** (String) - Optional - Custom payload, 0-128 bytes. This will not be displayed to the user, use it for your internal processes.
- **ttl** (Integer) - Optional - Time-to-live (in seconds) before the message expires. If the message is not delivered or read within this time, the request fee will be refunded. Supported values are from 30 to 3600.

### Request Example
```json
{
  "phone_number": "+1234567890",
  "request_id": "unique_request_id",
  "sender_username": "@your_channel",
  "code": "123456",
  "code_length": 6,
  "callback_url": "https://your.callback.url/report",
  "payload": "custom_payload_data",
  "ttl": 300
}
```

### Response
#### Success Response (200)
- **ok** (Boolean) - Indicates if the request was successful.
- **result** (Object) - Contains the result of the query, typically a RequestStatus object.

#### Response Example
```json
{
  "ok": true,
  "result": {
    "request_id": "unique_request_id",
    "status": "pending",
    "sent_at": "2025-02-26T10:00:00Z",
    "is_refunded": false
  }
}
```

#### Error Response
- **ok** (Boolean) - Always false for errors.
- **error** (Object) - Contains error details, e.g., {"code": "ACCESS_TOKEN_INVALID", "message": "Invalid access token provided."}

```

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

### Report Delivery Callback

Source: https://core.telegram.org/gateway/api

The Telegram Gateway API can send delivery reports to a user-specified callback URL. When a `callback_url` is provided, the API sends an HTTP POST request to that URL with the delivery report as a JSON object representing the RequestStatus object. The URL must respond with HTTP 200 to confirm receipt.

```APIDOC
## POST /callback_url

### Description
Receives delivery reports from the Telegram Gateway API.

### Method
POST

### Endpoint
`callback_url` (provided by user)

### Request Body
- **status** (String) - The current status of the verification process. One of: `code_valid`, `code_invalid`, `code_max_attempts_exceeded`, `expired`.
- **updated_at** (Integer) - The timestamp for the status update.
- **code_entered** (String) - _Optional._ The code entered by the user.

### Response
#### Success Response (200)
- Acknowledges receipt of the delivery report.

### Headers
- **X-Request-Timestamp** (Unix timestamp) - Indicates when the server submitted the report.
- **X-Request-Signature** (String) - Server-generated signature to authenticate the report.
```

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

### __checkVerificationStatus

Source: https://core.telegram.org/gateway/api

Checks the status of a previously sent verification message. It can also verify the correctness of a user-entered code if the code was generated by Telegram. Returns a RequestStatus object on success.

```APIDOC
## __checkVerificationStatus

### Description
Use this method to check the status of a verification message that was sent previously. If the code was generated by Telegram for you, you can also verify the correctness of the code entered by the user using this method. Even if you set the code yourself, it is recommended to call this method after the user has successfully entered the code, passing the correct code in the _code_ parameter, so that we can track the conversion rate of your verifications. On success, returns a RequestStatus object.

### Method
POST (assumed, as it modifies state or requires parameters)

### Endpoint
/checkVerificationStatus

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **request_id** (String) - Yes - The unique identifier of the verification request whose status you want to check.
- **code** (String) - Optional - The code entered by the user. If provided, the method checks if the code is valid for the relevant request.

### Request Example
```json
{
  "request_id": "some_unique_request_id",
  "code": "123456"
}
```

### Response
#### Success Response (200)
- **RequestStatus** (Object) - Represents the status of a verification message request.

#### Response Example
```json
{
  "request_id": "some_unique_request_id",
  "phone_number": "+1234567890",
  "request_cost": 0.05,
  "is_refunded": false,
  "remaining_balance": 1.95,
  "delivery_status": {
    "status": "delivered",
    "updated_at": 1678886460
  },
  "verification_status": "verified",
  "payload": "optional_payload"
}
```
```

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

### Send Verification Message Parameters

Source: https://core.telegram.org/gateway/api

This snippet outlines the parameters for the sendVerificationMessage method. Use this to send verification codes to users. Ensure phone_number is in E.164 format. The ttl parameter controls message expiration and refund eligibility.

```JSON
{
  "phone_number": "+1234567890",
  "request_id": "unique_request_id",
  "sender_username": "@your_channel",
  "code": "123456",
  "code_length": 6,
  "callback_url": "https://your.domain.com/callback",
  "payload": "custom_payload_data",
  "ttl": 300
}
```

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

### Verify Telegram Gateway Report Signature

Source: https://core.telegram.org/gateway/api

Use this code to verify the integrity and origin of delivery reports received from the Telegram Gateway API. It compares the provided signature with a calculated HMAC-SHA-256 signature of the data-check-string.

```pseudocode
data_check_string = X-Request-Timestamp + '\n' + post_body
secret_key = SHA256(api_token)
if (hex(HMAC_SHA256(data_check_string, secret_key)) == X-Request-Signature) {
  // data is from Telegram
}
```

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

### __revokeVerificationMessage

Source: https://core.telegram.org/gateway/api

Revokes a previously sent verification message. Returns True if the revocation request was received, though actual deletion is not guaranteed if the message was already delivered or read.

```APIDOC
## __revokeVerificationMessage

### Description
Use this method to revoke a verification message that was sent previously. Returns _True_ if the revocation request was received. However, this does not guarantee that the message will be deleted. For example, if the message has already been delivered or read, it will not be removed.

### Method
POST (assumed, as it modifies state or requires parameters)

### Endpoint
/revokeVerificationMessage

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **request_id** (String) - Yes - The unique identifier of the request whose verification message you want to revoke.

### Request Example
```json
{
  "request_id": "some_unique_request_id"
}
```

### Response
#### Success Response (200)
- **True** (Boolean) - Indicates if the revocation request was received.

#### Response Example
```json
true
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.