POST Telegram TDRs

This endpoint returns a paginated list of Telegram Delivery Records (TDRs) for your account. Use it to browse message history, filter by status or recipient, and sort results by any record field.

Configure the API Endpoint

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

• 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

{
  "page": 1,
  "rows_per_page": 20,
  "sort_by": "timestamp",
  "sort_direction": "DESC",
  "filter": {
    "status": "DELIVERED"
  }
}

Field	Type	Required	Description
page	integer	No	Page number to retrieve, starting from 1 (default: 1).
rows_per_page	integer	No	Number of records per page, between 1 and 100 (default: 20).
sort_by	string	No	Field name to sort results by (e.g. "timestamp", "status", "to").
sort_direction	string	No	Sort order: "ASC" or "DESC".
filter	object	No	Optional filter criteria applied to the result set (e.g. filter by status or to).

Code Snippets

cUrl

Example - cURL

curl --location 'https://api.betatel.com/api/v1/connect-hub/telegram/tdr' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-account-id: YOUR_ACCOUNT_ID' \
--data '{
  "page": 1,
  "rows_per_page": 20,
  "sort_by": "timestamp",
  "sort_direction": "DESC",
  "filter": {
    "status": "DELIVERED"
  }
}'

Python

Example - Python

import http.client
import json

conn = http.client.HTTPSConnection("api.betatel.com")
payload = json.dumps({
  "page": 1,
  "rows_per_page": 20,
  "sort_by": "timestamp",
  "sort_direction": "DESC",
  "filter": {
    "status": "DELIVERED"
  }
})
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/tdr", 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({
  "page": 1,
  "rows_per_page": 20,
  "sort_by": "timestamp",
  "sort_direction": "DESC",
  "filter": {
    "status": "DELIVERED"
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://api.betatel.com/api/v1/connect-hub/telegram/tdr',
  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/tdr',
  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 => '{"page":1,"rows_per_page":20,"sort_by":"timestamp","sort_direction":"DESC","filter":{"status":"DELIVERED"}}',
  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/tdr")
  .header("Content-Type", "application/json")
  .header("x-api-key", "YOUR_API_KEY")
  .header("x-account-id", "YOUR_ACCOUNT_ID")
  .body("{\"page\":1,\"rows_per_page\":20,\"sort_by\":\"timestamp\",\"sort_direction\":\"DESC\",\"filter\":{\"status\":\"DELIVERED\"}}")
  .asString();

C#

Example - C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.betatel.com/api/v1/connect-hub/telegram/tdr");
request.Headers.Add("x-api-key", "YOUR_API_KEY");
request.Headers.Add("x-account-id", "YOUR_ACCOUNT_ID");
var content = new StringContent("{\"page\":1,\"rows_per_page\":20,\"sort_by\":\"timestamp\",\"sort_direction\":\"DESC\",\"filter\":{\"status\":\"DELIVERED\"}}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Understanding the Response

{
  "page": 1,
  "rows_per_page": 20,
  "sort_by": "timestamp",
  "sort_direction": "DESC",
  "total": 243,
  "total_pages": 13,
  "has_next_page": true,
  "has_previous_page": false,
  "list": [
    {
      "uuid": "01JV5V54KPYK9GB29265EQRZ2P",
      "to": "+38761444555",
      "code": "482910",
      "status": "DELIVERED",
      "request_id": "187259537046478",
      "country": "Bosnia and Herzegovina",
      "country_code": 387,
      "network": "BH Telecom",
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Pagination fields:

Field	Type	Description
page	integer	The current page number.
rows_per_page	integer	Number of records returned per page.
sort_by	string	The field results are sorted by.
sort_direction	string	The sort direction (ASC or DESC).
total	integer	Total number of records matching the filter.
total_pages	integer	Total number of pages available.
has_next_page	boolean	Whether a next page exists.
has_previous_page	boolean	Whether a previous page exists.

TDR record fields:

Field	Type	Description
uuid	string	Unique identifier for the message.
to	string	Recipient's phone number (E.164 format).
code	string	Verification code that was sent.
status	string	Current delivery status (see table below).
request_id	string	Telegram Gateway request identifier.
country	string	Destination country name.
country_code	integer	Destination country dialing code.
network	string	Recipient's mobile network operator.
timestamp	string	ISO 8601 timestamp of when the message was created.

Message Status Values

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 pagination parameters or malformed filter
• 401 - Unauthorized: Authentication failed
• 500 - Internal Server Error: An unexpected error occurred on the server