Cutiezy Telegram Gateway

Aturan penting

Gunakan X-API-Key pada header (disarankan) atau api_key pada body/query. Parameter sender adalah Bot ID yang tampil di Dashboard. Untuk mengirim notifikasi buyer, gunakan chat_id / telegram_user_id hasil proses pairing, bukan username Telegram. Bot tidak dapat memulai chat ke user yang belum pernah menekan /start.

Koneksi Telegram Buyer

Flow: website membuat pairing token → buyer membuka deep_link → buyer menekan Start → gateway menangkap ID Telegram → website mengecek status token → gateway mengembalikan chat_id dan telegram_user_id. Pairing token berlaku selama 600 detik / 10 menit.

POST /telegram-link/create

Membuat sesi pairing Telegram untuk buyer.

curl -X POST "/telegram-link/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: API_KEY_ANDA" \
  -d '{
    "sender": "123456789",
    "external_ref": "buyer-25"
  }'

external_ref opsional. Disarankan isi dengan ID buyer/user dari website agar hasil pairing mudah dicocokkan.

{
  "success": true,
  "message": "Link koneksi Telegram dibuat.",
  "data": {
    "sender": "123456789",
    "bot_username": "NamaBot",
    "pairing_token": "web_xxxxxxxxxxxxxxxxxxxxxxxx",
    "start_parameter": "web_xxxxxxxxxxxxxxxxxxxxxxxx",
    "deep_link": "https://t.me/NamaBot?start=web_xxxxxxxxxxxxxxxxxxxxxxxx",
    "expires_in": 600
  }
}

Alias endpoint: POST /api/telegram-link/create.

GET / POST /telegram-link/status

Dipakai website untuk mengecek apakah buyer sudah menekan Start dan mengambil ID Telegram.

curl -X POST "/telegram-link/status" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: API_KEY_ANDA" \
  -d '{
    "sender": "123456789",
    "pairing_token": "web_xxxxxxxxxxxxxxxxxxxxxxxx"
  }'

Bisa memakai pairing_token, token, atau start_parameter. Endpoint boleh dipanggil dengan GET atau POST.

Response saat masih menunggu Start

{
  "success": true,
  "message": "Menunggu buyer menekan Start di Telegram.",
  "data": {
    "status": "pending",
    "linked": false,
    "external_ref": "buyer-25",
    "chat_id": null,
    "telegram_user_id": null,
    "telegram_username": null,
    "first_name": null,
    "last_name": null,
    "linked_at": null,
    "expires_at": "2026-08-19T..."
  }
}

Response setelah buyer menekan Start

{
  "success": true,
  "message": "Telegram buyer sudah terhubung.",
  "data": {
    "status": "linked",
    "linked": true,
    "external_ref": "buyer-25",
    "chat_id": "987654321",
    "telegram_user_id": "987654321",
    "telegram_username": "buyerusername",
    "first_name": "Buyer",
    "last_name": null,
    "linked_at": "2026-08-19T...",
    "expires_at": "2026-08-19T..."
  }
}

Setelah linked=true, website harus menyimpan chat_id dan/atau telegram_user_id ke akun buyer. Username Telegram hanya metadata dan jangan dipakai sebagai identitas utama untuk pengiriman notifikasi.

Alias endpoint: GET/POST /api/telegram-link/status.

Contoh flow website

1. POST /telegram-link/create
2. Simpan pairing_token sementara di session/database website
3. Arahkan buyer ke data.deep_link
4. Buyer tekan Start di bot Telegram
5. Poll GET/POST /telegram-link/status dengan pairing_token yang sama
6. Jika data.linked === true:
   - simpan data.chat_id
   - simpan data.telegram_user_id
   - opsional simpan data.telegram_username
7. Hapus pairing_token dari sisi website jika sudah selesai

POST /send-message

curl -X POST "/send-message" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: API_KEY_ANDA" \
  -d '{
    "sender": "123456789",
    "chat_id": "987654321",
    "message": "Halo dari Cutie Telegram Gateway"
  }'

Opsional: parse_mode = HTML atau MarkdownV2. Untuk buyer yang sudah pairing, isi chat_id dari hasil /telegram-link/status.

POST /send-media

{
  "api_key": "API_KEY_ANDA",
  "sender": "123456789",
  "chat_id": "-1001234567890",
  "media_type": "image",
  "url": "https://example.com/image.jpg",
  "caption": "Foto terbaru"
}

Tipe: image/photo, video, audio, voice, animation/gif, document, pdf, xls, xlsx, doc, docx, zip.

POST /schedule-message

{
  "api_key": "API_KEY_ANDA",
  "sender": "123456789",
  "numbers": ["987654321", "-1001234567890"],
  "message": "Pesan terjadwal",
  "scheduled_at": "2026-07-30 09:00:00",
  "timezone": "Asia/Jakarta",
  "request_id": "invoice-1001"
}

Endpoint lain

POST /telegram-link/create

GET/POST /telegram-link/status

GET /scheduled-messages

GET /schedule-message/:id

POST /schedule-message/:id/cancel

GET /api-ping

Telegram API Docs