POST Check Verification Status

This endpoint checks the current status of a Telegram OTP verification. Use it after sending an OTP to determine whether the message was delivered, whether the user has entered a code, and whether that code was correct. Optionally, pass the code the user entered to have the Telegram Gateway validate it.

Configure the API Endpoint

https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status

• Method: POST

Set Up the Headers

Param	Value	Description
Content-type	application/json	Specifies the payload format.
x-api-key	{{x-api-key}}	API key for authorization.
x-account-id	{{x-account-id}}	User identifier for added security and tracking.

Craft the Request Body

Example of body

{
  "request_id": "tgr_01JV5V54KPYK9GB29265EQRZ2P",
  "code": "482910"
}

Field	Type	Required	Description
request_id	string	Yes	The request_id returned from the Telegram Gateway when the OTP was sent.
code	string	No	The verification code entered by the user (4–8 digits). If provided, the Gateway validates the code and returns the result.

tip

The request_id is stored on the TDR record. You can retrieve it at any time via the Get TDR by UUID endpoint.

Code Snippets

cUrl

Example - cURL

curl --location 'https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-account-id: YOUR_ACCOUNT_ID' \
--data '{
  "request_id": "tgr_01JV5V54KPYK9GB29265EQRZ2P",
  "code": "482910"
}'

Python

Example - Python

import http.client
import json

conn = http.client.HTTPSConnection("api.betatel.com")
payload = json.dumps({
  "request_id": "tgr_01JV5V54KPYK9GB29265EQRZ2P",
  "code": "482910"
})
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY',
  'x-account-id': 'YOUR_ACCOUNT_ID'
}
conn.request("POST", "/api/v1/connect-hub/telegram/check-verification-status", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Node.js

Example - Node.js

const axios = require('axios');
let data = JSON.stringify({
  "request_id": "tgr_01JV5V54KPYK9GB29265EQRZ2P",
  "code": "482910"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
    'x-account-id': 'YOUR_ACCOUNT_ID'
  },
  data: data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

PHP

Example - PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{"request_id":"tgr_01JV5V54KPYK9GB29265EQRZ2P","code":"482910"}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'x-api-key: YOUR_API_KEY',
    'x-account-id: YOUR_ACCOUNT_ID'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Java

Example - Java

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status")
  .header("Content-Type", "application/json")
  .header("x-api-key", "YOUR_API_KEY")
  .header("x-account-id", "YOUR_ACCOUNT_ID")
  .body("{\"request_id\":\"tgr_01JV5V54KPYK9GB29265EQRZ2P\",\"code\":\"482910\"}")
  .asString();

C#

Example - C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.betatel.com/api/v1/connect-hub/telegram/check-verification-status");
request.Headers.Add("x-api-key", "YOUR_API_KEY");
request.Headers.Add("x-account-id", "YOUR_ACCOUNT_ID");
var content = new StringContent("{\"request_id\":\"tgr_01JV5V54KPYK9GB29265EQRZ2P\",\"code\":\"482910\"}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Understanding the Response

{
  "request_id": "187259537046478",
  "phone_number": "+38761444555",
  "request_cost": 0.01,
  "delivery_status": {
    "status": "delivered",
    "updated_at": 1700000045
  },
  "verification_status": {
    "status": "code_valid",
    "updated_at": 1700000102
  }
}

Field	Type	Description
request_id	string	Unique identifier for the verification request.
phone_number	string	The recipient's phone number.
request_cost	number	Cost charged for this status check.
delivery_status	object	Current delivery state of the message (see below).
verification_status	object	Result of the code verification attempt (see below).

Delivery status values:

Status	Description
sent	Message dispatched to the Telegram Gateway.
delivered	Message delivered to the recipient's device.
read	Message has been opened by the recipient.
expired	Message TTL elapsed before delivery.
revoked	Message was revoked before delivery.

Verification status values:

Status	Description
code_valid	The code entered by the user is correct.
code_invalid	The code entered by the user is incorrect.
code_max_attempts_exceeded	Too many incorrect attempts — verification failed.
expired	The verification window has elapsed.

Error Handling

• 400 - Bad Request: Invalid or missing request_id
• 401 - Unauthorized: Authentication failed
• 404 - Not Found: The request_id does not exist
• 500 - Internal Server Error: An unexpected error occurred on the server