Telegram Inbox REST API
Telegram Inbox REST API for SMSGatewayCenter APIs
Telegram Inbox REST API
Use the Inbox REST API to fetch incoming Telegram messages for your account over HTTP. Filter by chat ID, Telegram user ID, phone number, read status, and date range. This endpoint is read-only, accepts GET requests, and returns JSON.
Ideal for mobile apps, CRM integrations, and custom dashboards that need to display or process incoming Telegram conversations.
API Endpoint
https://unify.smsgateway.center/rest/tg/v1/inboxLegacy alias without v1 in the path is also supported: /rest/tg/inbox
Authentication
Send your account userid and password as request parameters. Telegram Chat API access must be enabled on your account.
| Parameter | Required | Description | Example/Value |
|---|---|---|---|
| Authentication (Required) | |||
| userid | Yes | Your SMSGatewayCenter account username. | YourUsername |
| password | Yes | Your account password. | ********** |
| output | Yes | Response format. Must be json. | json |
| Optional Parameters | |||
| action | Optional | Defaults to list. Only list is supported in v1. | list |
| fromDate | Optional | Start of received date range. Format YYYY-MM-DD or full date/time. Alias: from. | 2026-07-01 00:00:00 |
| toDate | Optional | End of received date range. Format YYYY-MM-DD or full date/time. Alias: to. | 2026-07-07 23:59:59 |
| chatId | Optional | Filter by Telegram chat ID (numeric). | 123456789 |
| telegramUserId | Optional | Filter by the Telegram user ID of the sender. | 987654321 |
| phoneNumber | Optional | Filter by customer phone number with country code, digits only. Matches contacts who shared their phone with your bot. | 919999999999 |
| isRead | Optional | Filter read status: 0 unread, 1 read. | 0 |
| page | Optional | Page number. Default 1. | 1 |
| limit | Optional | Records per page. Default 50, maximum 200. | 50 |
Sample Request Code (cURL)
curl --location 'https://unify.smsgateway.center/rest/tg/v1/inbox?userid=YourUsername&password=xxxxx&output=json&action=list&fromDate=2026-06-30&toDate=2026-07-07&page=1&limit=50'
Sample Success Response
{
"status": "success",
"inboxList": [
{
"incomingId": "101",
"chatId": "123456789",
"telegramUserId": "987654321",
"firstName": "Rahul",
"username": "rahul_demo",
"phoneNumber": "919999999999",
"message": "Hello",
"msgType": "text",
"mediaUrl": "",
"receivedAt": 1712345678901,
"receivedAtFormatted": "2026-07-07 10:14:38",
"isRead": 0
}
],
"totalRecords": 1,
"page": 1,
"limit": 50,
"fromDate": "2026-07-01 00:00:00",
"toDate": "2026-07-07 23:59:59",
"statusCode": "200",
"reason": "success"
}
Sample Error Response
{
"status": "error",
"inboxList": [],
"statusCode": "403",
"reason": "Telegram API access is not enabled for this account."
}
Notes
- Results are ordered by
receivedAtdescending (newest first). phoneNumberin the response comes from customer mapping when the contact shared their phone with your bot.- This API is read-only. To reply, use the Send Telegram Message API.
Testimonials
Why do Great Businesses Trust SMS Gateway Center?
