v1 · stabil

Dokumentasi API

Endpoint publik untuk meneruskan pesan ke Telegram Bot API. Bentuk payload identik dengan Bot API resmi, tinggal ganti host dan ganti token dengan API key.

Overview

Tiap bot punya botId internal (ULID). Anda kirim request ke endpoint kami menggunakan botId + nama method Telegram, dan kami forward ke Telegram dengan token bot yang sudah disimpan terenkripsi di server.

Base URL

https://your-host/api/v1

Auth

Header X-API-Key

Format

JSON · multipart

Autentikasi

Sertakan API key pada header X-API-Key atau Authorization: Bearer <key>. Buat key di /dashboard/api-keys. Format key: tgm_live_<random>.

http

X-API-Key: tgm_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Endpoint

http

POST /api/v1/bots/{botId}/{method}
GET  /api/v1/bots/{botId}/{method}

botId — ULID internal yang ditampilkan di halaman detail bot. Bukan token, bukan ID numerik Telegram.
method — nama method Telegram Bot API, mis. sendMessage, sendPhoto, editMessageText.

Contoh request

Kirim pesan dengan inline keyboard

bash

curl -X POST https://your-host/api/v1/bots/01H.../sendMessage \
  -H "X-API-Key: tgm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Halo dunia!",
    "reply_markup": {
      "inline_keyboard": [[
        { "text": "Buka", "url": "https://example.com" },
        { "text": "Aksi", "callback_data": "do_action" }
      ]]
    }
  }'

Kirim foto via multipart

bash

curl -X POST https://your-host/api/v1/bots/01H.../sendPhoto \
  -H "X-API-Key: tgm_live_..." \
  -F "chat_id=123456789" \
  -F "caption=Foto liburan" \
  -F "photo=@./gambar.jpg"

Edit pesan

bash

curl -X POST https://your-host/api/v1/bots/01H.../editMessageText \
  -H "X-API-Key: tgm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "message_id": 42,
    "text": "Pesan terbaru"
  }'

Format respons

Respons dari Telegram diteruskan apa adanya. Pada error internal (auth/rate limit/bot tidak ditemukan), bentuknya dibuat kompatibel dengan respons error Telegram:

json

{
  "ok": false,
  "error_code": 429,
  "description": "Rate limit exceeded",
  "parameters": { "retry_after": 42 }
}

Kode error

HTTP	Penyebab
`401`	API key kosong, salah, atau dicabut.
`403`	Bot dinonaktifkan, atau method tidak diizinkan.
`404`	Bot tidak ditemukan atau bukan milik Anda.
`429`	Rate limit. Tunggu sesuai `retry_after`.
`502`	Gagal menghubungi Telegram.

Rate limit

Default 60 request per menit per API key. Tiap respons membawa header berikut:

http

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 58
X-RateLimit-Reset:     1716988800

X-RateLimit-Reset dalam epoch detik (UTC). Atur limit lewat env RATE_LIMIT_PER_MINUTE.

Webhook & callback

Untuk menangani klik tombol callback_data atau pesan masuk, daftarkan webhook URL Anda di halaman detail bot dashboard. Telegram Manager akan auto-acknowledge callback (biar spinner hilang) lalu forward update mentahan ke URL Anda.

Setup

Set WEBHOOK_BASE_URL di .env ke URL publik aplikasi (lokal: ngrok / cloudflared tunnel).
Buka Dashboard → Bots → detail bot → Webhook.
Isi URL endpoint Anda (HTTPS), klik Aktifkan. Salin webhook secret yang ditampilkan untuk verifikasi HMAC.

Alur

text

User klik tombol di Telegram
   ↓
Telegram → POST <WEBHOOK_BASE_URL>/api/v1/tg-webhook/<pathToken>
   ↓
Telegram Manager → answerCallbackQuery (spinner hilang)
                 → forward update mentah ke webhook Anda
   ↓
POST https://your-app.example.com/api/v1/telegram_webhook
  X-Webhook-Bot-Id:    <botId>
  X-Webhook-Signature: sha256=<HMAC-SHA256(rawBody, secret)>

Pola callback_data untuk konfirmasi pesanan

Saat kirim pesan konfirmasi, encode action + status + id ke dalam callback_data:

bash

curl -X POST https://your-host/api/v1/bots/<botId>/sendMessage \
  -H "X-API-Key: tgm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 523067421,
    "text": "Ada orderan masuk #2437234. Konfirmasi?",
    "reply_markup": {
      "inline_keyboard": [[
        { "text": "Ya",    "callback_data": "order:confirm:2437234" },
        { "text": "Tidak", "callback_data": "order:reject:2437234" }
      ]]
    }
  }'

Saat user klik tombol, webhook Anda menerima callback_query.data = "order:confirm:2437234". Split : menjadi { action, status, order_id } lalu update database Anda.

Verifikasi signature (Node.js)

import crypto from "node:crypto";

const SECRET = process.env.TGM_WEBHOOK_SECRET!;

const expected = crypto
  .createHmac("sha256", SECRET)
  .update(rawBody) // body MENTAH, sebelum JSON.parse
  .digest("hex");

const got = req.headers["x-webhook-signature"]?.replace(/^sha256=/, "");
if (got !== expected) return res.status(403).end();

Penting: hitung HMAC dari raw body, bukan hasil JSON.parse yang di-stringify ulang. Whitespace dan urutan field bisa berbeda.