{"id":2962,"date":"2026-09-14T11:45:02","date_gmt":"2026-09-14T06:15:02","guid":{"rendered":"https:\/\/www.smsgatewaycenter.com\/blog\/?p=2962"},"modified":"2026-09-14T11:45:05","modified_gmt":"2026-09-14T06:15:05","slug":"telegram-messaging-api-chat-id-model","status":"publish","type":"post","link":"https:\/\/www.smsgatewaycenter.com\/blog\/telegram-messaging-api-chat-id-model\/","title":{"rendered":"Telegram Messaging API: Eight Endpoints, the Chat ID Model, and the Error Shape That Breaks Typed Clients"},"content":{"rendered":"\n

A field by field reference for the SMSGatewayCenter Telegram REST API<\/strong>. Covers the eight endpoints under rest\/tg\/v1<\/code>, the chat ID identity model, the three names one message identifier travels under, the payload type flip on error, and a three way comparison of the Telegram, SMS and RCS delivery rows.<\/p>\n\n\n\n

\"Abstract<\/a>
Three channels on one platform, three different wire contracts underneath.<\/figcaption><\/figure>\n\n\n\n

<\/p>\n\n\n\n

TABLE OF CONTENTS<\/h1>\n\n\n\n
    \n
  1. The Short Answer<\/a><\/li>\n\n\n\n
  2. TL;DR<\/a><\/li>\n\n\n\n
  3. One Base Path, Eight Endpoints, One Bot<\/a><\/li>\n\n\n\n
  4. The Identity Model: Chat IDs, Not Phone Numbers<\/a><\/li>\n\n\n\n
  5. Bot Setup, the Endpoint That Configures Infrastructure<\/a><\/li>\n\n\n\n
  6. Building Your Audience: Recipients Is a Query, Not a Table<\/a><\/li>\n\n\n\n
  7. Sending: One Endpoint, Eleven Message Types<\/a><\/li>\n\n\n\n
  8. One Identifier, Three Names, Two JSON Types<\/a><\/li>\n\n\n\n
  9. Templates: Two Actions, Two Envelopes<\/a><\/li>\n\n\n\n
  10. The Delivery Report Field by Field<\/a><\/li>\n\n\n\n
  11. The Payload Type Flip on Error<\/a><\/li>\n\n\n\n
  12. Telegram, SMS and RCS Side by Side<\/a><\/li>\n\n\n\n
  13. The Inbox and the Webhook That Is Not Yours<\/a><\/li>\n\n\n\n
  14. Summary and Analytics: Which Number to Trust<\/a><\/li>\n\n\n\n
  15. Endpoint Reference Table<\/a><\/li>\n\n\n\n
  16. Your First Telegram Send in Six Steps<\/a><\/li>\n\n\n\n
  17. Working Code in Four Languages<\/a><\/li>\n\n\n\n
  18. Ten Mistakes That Cost a Sprint<\/a><\/li>\n\n\n\n
  19. Choosing Between Telegram, SMS and RCS<\/a><\/li>\n\n\n\n
  20. Production Checklist<\/a><\/li>\n\n\n\n
  21. Unspecified Behaviour and How to Code Around It<\/a><\/li>\n\n\n\n
  22. FAQs<\/a><\/li>\n<\/ol>\n\n\n\n

    <\/p>\n\n\n\n

    The Short Answer<\/h2>\n\n\n\n

    The SMSGatewayCenter Telegram API<\/strong><\/a> is eight REST endpoints under a single base path, https:\/\/unify.smsgateway.center\/rest\/tg\/v1\/<\/code>. You connect one bot per account with a token from Telegram BotFather, the platform registers an inbound webhook with Telegram on your behalf, and from that point you address people by Telegram chatId<\/code> rather than by mobile number. Sends go to \/send<\/code> as form encoded POST. Everything else is a GET: \/setup<\/code>, \/recipients<\/code>, \/templates<\/code>, \/inbox<\/code>, \/dlr<\/code>, \/summary<\/code> and \/analytics<\/code>. All eight take output=json<\/code> and all eight accept an apikey<\/code> request header in place of the password, which is the variant to use everywhere.<\/p>\n\n\n\n

    The part that costs people a day is not the endpoint list. It is that every Telegram endpoint returns its main payload as an object or array on success and as an empty array<\/strong> on error. A Go, Rust, Java or C# client that binds setup<\/code> to a struct will unmarshal the success case cleanly and throw on the 403. Bind the payload loosely, branch on the top level status<\/code> string before you touch anything else, and the family becomes easy.<\/p>\n\n\n\n

    TL;DR<\/h2>\n\n\n\n