POST Telegram OTP

This endpoint sends a one-time password to the specified phone number via Telegram. You can either provide your own verification code or let the system generate one. The response returns a unique message identifier and a request_id from the Telegram Gateway, which you use to check verification status or revoke the code later.

Configure the API Endpoint

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

• 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

{
  "to": "+38761444555",
  "code": "482910",
  "ttl": 300,
  "callback_url": "https://yourapp.com/telegram/callback"
}

Field	Type	Required	Description
to	string	Yes	Recipient's phone number in E.164 format (e.g., +38761444555).
code	string	Yes	Verification code to send (4–8 digits).
ttl	integer	No	Time in seconds before the code expires (30–3600, default: 300).
sender_username	string	No	Verified Telegram channel username to send from.
callback_url	string	No	URL to receive Telegram Gateway delivery callbacks (max 256 characters).

tip

Phone Number Formatting:

Phone numbers must be in full E.164 format including the + prefix (e.g., +38761444555).

Code Snippets

cUrl

Example - cURL

curl --location 'https://api.betatel.com/api/v1/connect-hub/telegram' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-account-id: YOUR_ACCOUNT_ID' \
--data '{
  "to": "+38761444555",
  "code": "482910",
  "ttl": 300,
  "callback_url": "https://yourapp.com/telegram/callback"
}'

Python

Example - Python

import http.client
import json

conn = http.client.HTTPSConnection("api.betatel.com")
payload = json.dumps({
  "to": "+38761444555",
  "code": "482910",
  "ttl": 300,
  "callback_url": "https://yourapp.com/telegram/callback"
})
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", 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({
  "to": "+38761444555",
  "code": "482910",
  "ttl": 300,
  "callback_url": "https://yourapp.com/telegram/callback"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.betatel.com/api/v1/connect-hub/telegram',
  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',
  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 => '{"to":"+38761444555","code":"482910","ttl":300,"callback_url":"https://yourapp.com/telegram/callback"}',
  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")
  .header("Content-Type", "application/json")
  .header("x-api-key", "YOUR_API_KEY")
  .header("x-account-id", "YOUR_ACCOUNT_ID")
  .body("{\"to\":\"+38761444555\",\"code\":\"482910\",\"ttl\":300,\"callback_url\":\"https://yourapp.com/telegram/callback\"}")
  .asString();

C#

Example - C#

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

Understanding the Response

{
  "uuid": "01JV5V54KPYK9GB29265EQRZ2P",
  "request_id": "tgr_01JV5V54KPYK9GB29265EQRZ2P",
  "to": "+38761444555",
  "status": "SENT",
  "request_cost": 0.01,
  "is_refunded": false,
  "remaining_balance": 9.99
}

Field	Type	Description
uuid	string	Unique identifier for this message in our system. Use this to retrieve the TDR.
request_id	string	Telegram Gateway request ID. Use this for status checks and revocation.
to	string	The recipient's phone number as provided in the request.
status	string	Initial delivery status.
request_cost	number	Charge incurred for this request (optional).
is_refunded	boolean	Whether the fee was refunded (optional).
remaining_balance	number	Account balance after this request (optional).

tip

After sending, use Check Verification Status to confirm the code was entered correctly, or Get TDR by UUID to poll the delivery status.

Message Status Lifecycle

Status	Description
PENDING	Message accepted and queued.
SENT	Message dispatched to the Telegram Gateway.
DELIVERED	Message delivered to the recipient's device.
READ	Recipient has opened the message.
EXPIRED	Message expired before delivery was confirmed.
REVOKED	Verification was explicitly revoked.
FAILED	Message could not be delivered.

Error Handling

• 400 - Bad Request: Invalid parameters or malformed request
• 401 - Unauthorized: Authentication failed
• 402 - Payment Required: Insufficient account balance
• 429 - Too Many Requests: Telegram Gateway rate limit reached
• 500 - Internal Server Error: An unexpected error occurred on the server