telegram-gateway

README

Telegram Gateway

Telegram Gateway is a Go HTTP server which exchanges Telegram messages over the HTTP protocol.

The idea is to provide a simple way to send and receive messages from/to Telegram without the need to use the Telegram API, but instead using a simple HTTP request. Of course, you need to protect the access to this server because it has access as your Telegram bot: whoever can post messages to this server, can send messages as your bot. At the same time, this makes very simple to integrate Telegram notifications in your applications, whatever the language they are written in.

Authentication

Set the GATEWAY_TOKEN environment variable to a secret string. When set, every request to /sendmessage must include an Authorization header:

Authorization: Bearer <GATEWAY_TOKEN>

Requests without a valid header receive 401 Unauthorized. When GATEWAY_TOKEN is empty or unset, auth is disabled (backward compatible). Use a long random string. Rotate by changing the env var and restarting.

Send a message

Send a POST request to /sendmessage with a JSON body describing what to send. All media fields are optional and mutually exclusive: if more than one is set, the first match wins in the order image, voice, audio, then plain text.

Text

{
  "chat_id": 123456789,
  "text": "Hello from the gateway"
}

Image

image is a base64-encoded image. text is used as the caption.

{
  "chat_id": 123456789,
  "text": "Look at this",
  "image": "<base64>",
  "image_name": "photo.jpg"
}

Voice note

voice is a base64-encoded OGG/OPUS audio file. Telegram rejects voice notes that are not OGG/OPUS. text is used as the caption. duration is the length in seconds.

{
  "chat_id": 123456789,
  "text": "Voice caption",
  "voice": "<base64>",
  "voice_name": "note.ogg",
  "duration": 12
}

Audio file

audio is a base64-encoded audio file (MP3 or MPEG recommended). text is used as the caption. duration is the length in seconds. performer and title populate the music-player UI.

{
  "chat_id": 123456789,
  "text": "Track caption",
  "audio": "<base64>",
  "audio_name": "song.mp3",
  "duration": 210,
  "performer": "Artist",
  "title": "Track title"
}

Response

{ "success": true, "message": "Message sent successfully" }

On error, success is false and message describes the failure. Malformed base64 payloads return 400 Bad Request; Telegram API failures return 500 Internal Server Error.

Limits

Telegram Bot API limits apply: up to 50 MB per file (10 MB recommended). HTTP clients must encode binary payloads as base64 inside the JSON body, so plan request sizes accordingly.