Panduan API Telegram
Bot Telegram Anda bisa berjalan di WiTalk dengan kode yang sama. Anda hanya mengganti dua hal:
| Di Telegram | Di WiTalk | |
|---|---|---|
| Alamat | https://api.telegram.org | https://<server>/api/v2 |
| Token | dari BotFather | dari admin WiTalk |
Bentuk tokennya sama (angka:rahasia), jadi tetap lolos pengecekan pustaka.
Coba dalam 2 Menit
Siapkan dua nilai ini dulu:
export BASE="https://chat.perusahaan.co.id/api/v2"
export TOKEN="123456789012:isi-token-dari-admin"
1. Pastikan token berjalan.
curl "$BASE/bot$TOKEN/getMe"
Bila berhasil, jawabannya berisi "ok": true dan nama bot Anda.
2. Kirim pesan pertama. Ganti budi dengan nama pengguna WiTalk Anda sendiri.
curl "$BASE/bot$TOKEN/sendMessage" -d chat_id=@budi -d text="Halo dari bot"
Buka aplikasi WiTalk. Pesannya sudah masuk.
3. Balas dari aplikasi, lalu baca balasannya. Di aplikasi, kirim /start ke bot itu.
curl "$BASE/bot$TOKEN/getUpdates"
Jawabannya berisi pesan Anda, lengkap dengan chat.id. Simpan angka itu: itulah alamat karyawan tersebut untuk pesan berikutnya.
Selesai. Semua metode lain bekerja dengan cara yang sama.
Memasang di Pustaka Anda
Pustaka populer menyediakan pengaturan alamat server. Kode bot lainnya tidak perlu berubah.
python-telegram-bot
app = (
Application.builder()
.token(TOKEN)
.base_url("https://chat.perusahaan.co.id/api/v2/bot")
.base_file_url("https://chat.perusahaan.co.id/api/v2/file/bot")
.build()
)
aiogram
from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
server = TelegramAPIServer.from_base("https://chat.perusahaan.co.id/api/v2")
bot = Bot(TOKEN, session=AiohttpSession(api=server))
pyTelegramBotAPI
from telebot import apihelper
apihelper.API_URL = "https://chat.perusahaan.co.id/api/v2/bot{0}/{1}"
apihelper.FILE_URL = "https://chat.perusahaan.co.id/api/v2/file/bot{0}/{1}"
grammY
const bot = new Bot(TOKEN, {
client: { apiRoot: "https://chat.perusahaan.co.id/api/v2" },
});
Telegraf
const bot = new Telegraf(TOKEN, {
telegram: { apiRoot: "https://chat.perusahaan.co.id/api/v2" },
});
Kelima pustaka ini sudah kami uji pada python-telegram-bot 22.8, aiogram 3.31, pyTelegramBotAPI 4.37, grammY 1.46, dan Telegraf 4.16. Pada Telegraf di Node 26, mengunggah berkas macet karena masalah di sisi pustakanya, bukan di server. Kirim berkas lewat alamat https atau file_id bila Anda memakai kombinasi itu.
Menerima Pesan
Ada dua cara, sama seperti di Telegram. Pilih satu.
| Cara | Cocok untuk | Cara memakai |
|---|---|---|
getUpdates | percobaan, atau server tanpa alamat publik | bot bertanya terus ke server |
| Webhook | program yang berjalan terus di server publik | server mengirim ke alamat https Anda |
Webhook dipasang seperti biasa:
curl "$BASE/bot$TOKEN/setWebhook" \
-d url=https://bot.perusahaan.co.id/hook \
-d secret_token=rahasia_anda
Setiap kiriman membawa header X-Telegram-Bot-Api-Secret-Token. Cocokkan dengan nilai di atas. Jawab dengan HTTP 2xx dalam 30 detik. Bila gagal, kiriman dicoba lagi dengan jeda 15 detik sampai 1 jam, dan antrean bot menunggu sampai berhasil. Pesan juga bisa dibalas langsung di jawaban webhook, dengan JSON berisi method.
Selama webhook terpasang, getUpdates dijawab 409. Hapus dulu dengan deleteWebhook. Pesan yang belum diambil disimpan selama 24 jam.
Yang diterima bot: message, edited_message, callback_query, poll_answer, my_chat_member, dan message_reaction bila diminta lewat allowed_updates.
Yang Paling Sering Dipakai
Mengirim ke Karyawan
chat_id boleh berisi dua bentuk:
- Angka dari update, seperti di Telegram.
@namapengguna, tambahan dari WiTalk. Bot bisa mengirim duluan tanpa menunggu karyawan menyapa.
Tombol
curl "$BASE/bot$TOKEN/sendMessage" -H "Content-Type: application/json" -d '{
"chat_id": "@budi",
"text": "Hadir di rapat besok?",
"reply_markup": { "inline_keyboard": [[
{ "text": "Hadir", "callback_data": "hadir" },
{ "text": "Izin", "callback_data": "izin" }
]] }
}'
Saat karyawan menekan tombol, bot menerima callback_query. Jawab dengan answerCallbackQuery, seperti biasa.
Keyboard balasan (keyboard) juga bisa: tekanannya sampai ke bot sebagai teks biasa. Tombol url tampil sebagai tautan.
Berkas
Kirim dengan tiga cara yang sama seperti Telegram: berkas dari komputer, alamat internet, atau file_id yang pernah dilihat bot.
curl "$BASE/bot$TOKEN/sendDocument" --form-string chat_id=@budi -F document=@slip.pdf -F caption="Slip gaji Oktober"
Untuk mengambil berkas dari karyawan, panggil getFile, lalu unduh dari https://<server>/api/v2/file/bot<token>/<file_path>. Batas ukuran 95 MB, atau 16 MB untuk foto.
Grup
Tambahkan akun resmi sebagai anggota grup di aplikasi. Bot langsung menerima my_chat_member berisi chat.id grup, yang berawalan -100.
Di grup, bot hanya mendengar perintah (/lapor), balasan ke pesannya, sebutan namanya (@nama.bot), dan pesan layanan. Ini sama dengan privacy mode Telegram, dan selalu menyala.
Daftar Metode
| Kelompok | Metode |
|---|---|
| Bot | getMe, logOut, close, setMyCommands, getMyCommands, deleteMyCommands, getMyName, setMyName, getMyDescription, setMyDescription, getMyShortDescription, setMyShortDescription, getUserProfilePhotos |
| Update | getUpdates, setWebhook, deleteWebhook, getWebhookInfo |
| Kirim | sendMessage, sendPhoto, sendDocument, sendAudio, sendVoice, sendVideo, sendAnimation, sendVideoNote, sendSticker, sendMediaGroup, sendLocation, sendVenue, sendContact, sendPoll, sendChatAction |
| Teruskan | forwardMessage, forwardMessages, copyMessage, copyMessages |
| Ubah | editMessageText, editMessageCaption, editMessageReplyMarkup, deleteMessage, deleteMessages, setMessageReaction, stopPoll, answerCallbackQuery |
| Berkas | getFile |
| Grup | getChat, getChatMember, getChatMemberCount, getChatAdministrators, leaveChat, pinChatMessage, unpinChatMessage, unpinAllChatMessages |
Nama metode boleh huruf besar atau kecil. Parameter boleh lewat alamat, form, JSON, atau multipart. Metode lain dijawab 404, misalnya pembayaran, inline mode, stories, games, dan moderasi grup.
Yang Berbeda dari Telegram
Bagian ini penting dibaca sebelum pindah.
| Hal | Di WiTalk | Yang perlu Anda lakukan |
|---|---|---|
Chat ID dan file_id lama | Tidak berlaku, WiTalk punya angka sendiri | Simpan ulang dari update baru, unggah ulang berkas |
| Penerima | Hanya karyawan di server ini | Tidak ada |
| Format teks | Tampil sebagai teks biasa. parse_mode tetap diterima, tandanya dibuang, dan tautan menjadi teks (alamat) | Tidak ada |
| Panjang pesan | Paling panjang 4.000 karakter, bukan 4.096 | Potong teks yang lebih panjang |
| Tombol ditekan | Tampil juga sebagai pesan karyawan di chat | Tidak ada |
Teks answerCallbackQuery | Belum muncul di aplikasi | Kirim sebagai pesan bila penting |
| Video, animasi, audio selain Ogg/Opus | Tampil sebagai dokumen yang bisa diunduh | Tidak ada |
| Stiker | Tampil sebagai foto | Tidak ada |
sendMediaGroup | Satu pesan untuk tiap berkas, bukan album | Tidak ada |
| Mengubah pesan | Dalam 15 menit, bukan 48 jam | Tangani error message can't be edited |
| Menghapus pesan | Dalam 5 menit, bukan 48 jam | Tangani error message can't be deleted |
Daftar perintah (setMyCommands) | Disimpan, belum tampil di aplikasi | Tulis perintahnya di pesan sambutan |
Kalau Ada Masalah
Bentuk error sama dengan Telegram: { "ok": false, "error_code": 400, "description": "..." }.
| Yang muncul | Artinya | Yang dilakukan |
|---|---|---|
401 Unauthorized | Token salah, sudah dicabut, atau token WhatsApp | Minta token Telegram ke admin |
403 the Business API is not enabled | API belum dinyalakan di server | Minta admin menyalakannya |
403 this bot was disabled | Akun resmi dinonaktifkan admin | Hubungi admin |
400 chat not found | Chat ID dari Telegram lama, atau nama pengguna salah | Pakai chat.id dari update WiTalk |
403 bot was blocked by the user | Karyawan memblokir akun resmi | Tidak bisa dikirimi |
403 bot is not a member | Bot belum masuk grup itu | Tambahkan ke grup |
404 method ... is not available | Metode tidak tersedia di WiTalk | Lihat daftar metode di atas |
409 Conflict | Memanggil getUpdates saat webhook terpasang | Panggil deleteWebhook |
429 Too Many Requests | Terlalu cepat | Tunggu sesuai retry_after |
| Pesan grup tidak sampai ke bot | Privacy mode | Pakai perintah, sebutan nama, atau balasan |
Batas kecepatan per akun resmi: 600 pesan per menit, 10 pesan per menit ke satu chat, 600 permintaan per menit, dan 120 unggahan per 10 menit.