Panduan API Telegram

Bot Telegram Anda bisa berjalan di WiTalk dengan kode yang sama. Anda hanya mengganti dua hal:

Di TelegramDi WiTalk
Alamathttps://api.telegram.orghttps://<server>/api/v2
Tokendari BotFatherdari 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.

CaraCocok untukCara memakai
getUpdatespercobaan, atau server tanpa alamat publikbot bertanya terus ke server
Webhookprogram yang berjalan terus di server publikserver 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

KelompokMetode
BotgetMe, logOut, close, setMyCommands, getMyCommands, deleteMyCommands, getMyName, setMyName, getMyDescription, setMyDescription, getMyShortDescription, setMyShortDescription, getUserProfilePhotos
UpdategetUpdates, setWebhook, deleteWebhook, getWebhookInfo
KirimsendMessage, sendPhoto, sendDocument, sendAudio, sendVoice, sendVideo, sendAnimation, sendVideoNote, sendSticker, sendMediaGroup, sendLocation, sendVenue, sendContact, sendPoll, sendChatAction
TeruskanforwardMessage, forwardMessages, copyMessage, copyMessages
UbaheditMessageText, editMessageCaption, editMessageReplyMarkup, deleteMessage, deleteMessages, setMessageReaction, stopPoll, answerCallbackQuery
BerkasgetFile
GrupgetChat, 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.

HalDi WiTalkYang perlu Anda lakukan
Chat ID dan file_id lamaTidak berlaku, WiTalk punya angka sendiriSimpan ulang dari update baru, unggah ulang berkas
PenerimaHanya karyawan di server iniTidak ada
Format teksTampil sebagai teks biasa. parse_mode tetap diterima, tandanya dibuang, dan tautan menjadi teks (alamat)Tidak ada
Panjang pesanPaling panjang 4.000 karakter, bukan 4.096Potong teks yang lebih panjang
Tombol ditekanTampil juga sebagai pesan karyawan di chatTidak ada
Teks answerCallbackQueryBelum muncul di aplikasiKirim sebagai pesan bila penting
Video, animasi, audio selain Ogg/OpusTampil sebagai dokumen yang bisa diunduhTidak ada
StikerTampil sebagai fotoTidak ada
sendMediaGroupSatu pesan untuk tiap berkas, bukan albumTidak ada
Mengubah pesanDalam 15 menit, bukan 48 jamTangani error message can't be edited
Menghapus pesanDalam 5 menit, bukan 48 jamTangani error message can't be deleted
Daftar perintah (setMyCommands)Disimpan, belum tampil di aplikasiTulis perintahnya di pesan sambutan

Kalau Ada Masalah

Bentuk error sama dengan Telegram: { "ok": false, "error_code": 400, "description": "..." }.

Yang munculArtinyaYang dilakukan
401 UnauthorizedToken salah, sudah dicabut, atau token WhatsAppMinta token Telegram ke admin
403 the Business API is not enabledAPI belum dinyalakan di serverMinta admin menyalakannya
403 this bot was disabledAkun resmi dinonaktifkan adminHubungi admin
400 chat not foundChat ID dari Telegram lama, atau nama pengguna salahPakai chat.id dari update WiTalk
403 bot was blocked by the userKaryawan memblokir akun resmiTidak bisa dikirimi
403 bot is not a memberBot belum masuk grup ituTambahkan ke grup
404 method ... is not availableMetode tidak tersedia di WiTalkLihat daftar metode di atas
409 ConflictMemanggil getUpdates saat webhook terpasangPanggil deleteWebhook
429 Too Many RequestsTerlalu cepatTunggu sesuai retry_after
Pesan grup tidak sampai ke botPrivacy modePakai 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.