การตั้งค่า webhook ของบอท Telegram: คู่มือฉบับสมบูรณ์สำหรับนักพัฒนา

การตั้งค่า webhook ของบอท Telegram เชื่อมต่อเซิร์ฟเวอร์ของคุณกับสตรีมการอัปเดตของ Telegram เพื่อให้ข้อความมาถึงแบบเรียลไทม์แทนที่จะเป็นแบบ polling loop หากคุณกำลังสร้างบอทที่กำหนดเองด้วย Bot API webhooks เป็นเส้นทางมาตรฐานในการผลิต: Telegram POSTs การอัปเดตแต่ละรายการไปยังปลายทาง HTTPS ของคุณ และโค้ดของคุณจะตอบสนอง

คู่มือนี้จะอธิบายถึงข้อกำหนดเบื้องต้น, การลงทะเบียน, ตัวอย่าง handler ที่ใช้งานได้, การตรวจสอบ, การแก้ไขปัญหา และเมื่อแพลตฟอร์มที่มีการจัดการเช่น TeleClaw มีความเหมาะสมมากกว่าการโฮสต์ด้วยตนเอง

ประเด็นสำคัญ

• Webhooks และ long polling ไม่สามารถใช้ร่วมกันได้ การตั้งค่า webhook จะปิดใช้งาน getUpdates จนกว่าคุณจะลบออก
• HTTPS เป็นสิ่งจำเป็น ปลายทางของคุณต้องมี TLS 1.2+, ใบรับรองที่ตรงกัน และพอร์ต 443, 80, 88 หรือ 8443
• ลงทะเบียนด้วย setWebhook, ตรวจสอบด้วย getWebhookInfo ตรวจสอบ last_error_message เมื่อการอัปเดตหยุดไหล
• ใช้ secret_token เพื่อยืนยันว่าคำขอมาจาก Telegram ไม่ใช่จากสแกนเนอร์สุ่มที่เข้าถึง URL ของคุณ
• ทางเลือกแบบไม่ต้องเขียนโค้ด: TeleClaw จัดการการโฮสต์และการส่งมอบเพื่อให้คุณข้ามเลเยอร์เซิร์ฟเวอร์ไปได้เลย

Webhooks vs long polling: ควรเลือกแบบไหน

Telegram มีสองวิธีในการรับการอัปเดต ตาม Bots FAQ คุณเลือกหนึ่งวิธีต่อบอท คุณไม่สามารถเรียกใช้ทั้งสองวิธีพร้อมกันได้

Long polling เป็นวิธีที่เร็วที่สุดในการสร้างต้นแบบ บอทของคุณเรียกใช้ getUpdates ในลูป ประมวลผลแต่ละชุด และเลื่อน offset ไม่มีโดเมน ไม่มีใบรับรอง ไม่มีพอร์ตเปิด

Webhooks พลิกโมเดล Telegram ส่ง HTTPS POST ไปยัง URL ของคุณเมื่อมีคนส่งข้อความถึงบอท สิ่งนี้จะลบคำขอ polling ที่ไม่ได้ใช้งานและลดเวลาตอบสนอง ซึ่งสำคัญสำหรับบอทสนับสนุน, การไหลของการชำระเงิน และการดูแลกลุ่มในขนาดใหญ่

หากคุณยังคงลงทะเบียนบอทอยู่ ให้เริ่มต้นด้วย คู่มือการสร้างบอท Telegram เพื่อรับโทเค็นจาก BotFather ก่อนดำเนินการต่อที่นี่

ข้อกำหนดเบื้องต้นสำหรับการตั้งค่า webhook ของบอท Telegram

ก่อนที่คุณจะเรียกใช้ setWebhook ให้ยืนยันว่าโครงสร้างพื้นฐานของคุณตรงตามข้อกำหนดของ Telegram จาก คู่มือ webhook อย่างเป็นทางการ:

• โทเค็นบอท จาก @BotFather (ดูคู่มือการสร้างบอทที่เชื่อมโยงด้านบน)
• โดเมนสาธารณะ พร้อมใบรับรอง TLS ที่ถูกต้อง ใบรับรองที่ลงนามด้วยตนเองจะใช้งานได้ก็ต่อเมื่อคุณอัปโหลดคีย์สาธารณะผ่านพารามิเตอร์ certificate
• พอร์ตที่รองรับ บนเซิร์ฟเวอร์ของคุณ: 443 (ค่าเริ่มต้น), 80, 88 หรือ 8443 พอร์ตอื่น ๆ จะถูกปฏิเสธ
• Certificate CN หรือ SAN ต้องตรงกับโดเมนใน URL webhook ของคุณ ใบรับรอง Wildcard อาจไม่ทำงาน ไม่รองรับการเปลี่ยนเส้นทาง
• การเข้าถึง POST ขาเข้า จากซับเน็ต Telegram 149.154.160.0/20 และ 91.108.4.0/22

สำหรับการพัฒนาในเครื่อง ให้เปิดเผย localhost ผ่านอุโมงค์ (ngrok, Cloudflare Tunnel หรือคล้ายกัน) ที่ให้ URL HTTPS สาธารณะแก่คุณ ทดสอบว่าอุโมงค์ส่งคืน HTTP 200 สำหรับคำขอ POST ก่อนลงทะเบียน webhook

ขั้นตอนที่ 1: สร้างปลายทาง webhook ของคุณ

เซิร์ฟเวอร์ของคุณต้องการเส้นทางที่ยอมรับคำขอ POST, แยกวิเคราะห์ออบเจกต์ JSON Update และส่งคืน HTTP 200 อย่างรวดเร็ว Handler ที่ช้าทำให้ Telegram พยายามใหม่และในที่สุดก็รายงานข้อผิดพลาดใน getWebhookInfo

ตัวอย่าง Node.js ขั้นต่ำด้วย Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python ด้วย Flask ทำตามรูปแบบเดียวกัน: อ่าน JSON จาก request, ตรวจสอบส่วนหัวลับหากกำหนดค่าไว้, ประมวลผลการอัปเดต, ส่งคืน 200

ตอบสนองอย่างรวดเร็ว งานหนัก (การเขียนฐานข้อมูล, การเรียกใช้ AI API) ควรไปที่คิวพื้นหลัง Telegram คาดหวังการรับทราบอย่างรวดเร็ว คุณยังสามารถตอบกลับแบบอินไลน์โดยส่งคืนเนื้อหา JSON พร้อมฟิลด์ method แทนที่จะเรียกใช้ API แยกต่างหาก ตามที่อธิบายไว้ใน บันทึก webhook ของ Bot API

ขั้นตอนที่ 2: กำหนดค่า webhook ของบอท Telegram ด้วย setWebhook

เมื่อปลายทางของคุณใช้งานได้แล้ว ให้ลงทะเบียนกับ Bot API แทนที่ <TOKEN> และ URL ด้วยค่าของคุณ

ใช้ curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

การอ้างอิงพารามิเตอร์:

• url (จำเป็น): ปลายทาง HTTPS ของคุณ ใช้สตริงว่างเพื่อลบ webhook
• secret_token (ไม่บังคับ): 1-256 อักขระ (A-Z, a-z, 0-9, _, -) Telegram ส่งในส่วนหัว X-Telegram-Bot-Api-Secret-Token
• max_connections (ไม่บังคับ): 1-100 การเชื่อมต่อพร้อมกัน ค่าเริ่มต้นคือ 40
• allowed_updates (ไม่บังคับ): จำกัดประเภทการอัปเดตที่คุณได้รับ ลดขนาดเพย์โหลดหากคุณจัดการเฉพาะข้อความ
• drop_pending_updates (ไม่บังคับ): ตั้งค่า true เพื่อทิ้งการอัปเดตที่ค้างอยู่เมื่อเปลี่ยน webhooks
• certificate (ไม่บังคับ): อัปโหลดไฟล์คีย์สาธารณะของคุณสำหรับใบรับรองที่ลงนามด้วยตนเอง

การตอบสนองที่สำเร็จจะมีลักษณะดังนี้ {"ok":true,"result":true,"description":"Webhook was set"}

ขั้นตอนที่ 3: ตรวจสอบด้วย getWebhookInfo

ยืนยันการลงทะเบียนทันทีเสมอ นี่คือเครื่องมือแก้ไขปัญหาแรกของคุณเมื่อการอัปเดตหยุดมาถึง

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

ตัวอย่างการตอบสนอง:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

ดูฟิลด์เหล่านี้:

• url: ว่างเปล่าหมายถึงไม่มี webhook ทำงานอยู่ (บอทอยู่ใน long polling)
• pending_update_count: การอัปเดตที่ค้างอยู่รอการส่งมอบ จำนวนที่เพิ่มขึ้นบ่งบอกถึงความล้มเหลวในการส่งมอบ
• last_error_date และ last_error_message: เหตุผลความล้มเหลวล่าสุด แก้ไขสาเหตุหลัก จากนั้น Telegram จะลองใหม่โดยอัตโนมัติ
• ip_address: IP ของ Telegram ที่กำลังเข้าถึงปลายทางของคุณ

ส่งข้อความทดสอบไปยังบอทของคุณจากบัญชี Telegram จริง หาก pending_update_count ยังคงเป็นศูนย์และบันทึกเซิร์ฟเวอร์ของคุณแสดง POST แสดงว่าการตั้งค่า webhook ของบอท Telegram ทำงานอยู่

ตัวอย่าง webhook ของบอท Telegram: ตัวจัดการคำขอเข้าร่วม

บอทคำขอเข้าร่วม (การไหลของการรับเข้าแบบ Guardian) ต้องการประเภทการอัปเดต chat_join_request คู่มือบอท Guardian ของเรา ครอบคลุมด้านผลิตภัณฑ์ นี่คือการเชื่อมต่อ webhook

ลงทะเบียนโดยเปิดใช้งานคำขอเข้าร่วม:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

ตรรกะของ Handler (รหัสเทียม):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // เรียกใช้ตรรกะการคัดกรอง จากนั้นอนุมัติหรือปฏิเสธผ่าน Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram ส่งคำขอเข้าร่วมเป็นการอัปเดตแบบพุช ดังนั้น webhooks จึงเหมาะอย่างยิ่งสำหรับบอทรับเข้าที่ต้องตอบสนองก่อนที่คำขอจะหมดอายุ

บอท Telegram ลบ webhook และเปลี่ยนกลับไปใช้ polling

ต้องการดีบักในเครื่องด้วย getUpdates? ลบ webhook ก่อน

ตัวเลือก A ด้วย deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

ตัวเลือก B ด้วย setWebhook และ URL ว่างเปล่า:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

ทั้งสองวิธีจะเปิดใช้งาน long polling อีกครั้ง หากคุณข้ามขั้นตอนนี้ getUpdates จะไม่ส่งคืนอะไรเลยเนื่องจาก webhook ยังคงลงทะเบียนกับ URL การผลิตของคุณ

การแก้ไขข้อผิดพลาด webhook ทั่วไป

เมื่อ getWebhookInfo แสดงข้อผิดพลาด ให้จับคู่ข้อความกับวิธีแก้ไข:

เรียกใช้ getWebhookInfo ตามกำหนดเวลาในการผลิต การจับ last_error_message ตั้งแต่เนิ่นๆ จะช่วยป้องกันการสูญเสียข้อความเงียบเป็นเวลาหลายชั่วโมง

ข้ามเซิร์ฟเวอร์: บอทที่มีการจัดการด้วย TeleClaw

ไม่ใช่ทุกบอทที่ต้องการโครงสร้างพื้นฐาน webhook ที่กำหนดเอง หากเป้าหมายของคุณคือผู้ช่วย AI สำหรับกลุ่มหรือช่องทางธุรกิจ การโฮสต์และการส่งการอัปเดตเป็นปัญหาที่แก้ไขได้แล้ว

TeleClaw เชื่อมต่อโทเค็น BotFather ของคุณกับรันไทม์ที่มีการจัดการซึ่งขับเคลื่อนโดย OpenClaw คุณกำหนดค่าบุคลิกภาพ, ฐานความรู้ และกฎการดูแลในแดชบอร์ด แพลตฟอร์มจัดการปลายทาง HTTPS, การปรับขนาด และการกำหนดเส้นทางโมเดล AI เพิ่ม @claw เป็นผู้ดูแลกลุ่มและใช้งานได้โดยไม่ต้องเขียน handler webhook

สำรวจสิ่งที่บอทที่มีการจัดการสามารถทำได้ใน หน้าคุณสมบัติ TeleClaw สำหรับคำแนะนำแบบไม่ต้องเขียนโค้ดทั้งหมด โปรดดู คู่มือแชทบอท Telegram แบบไม่ต้องเขียนโค้ด ของเรา

Webhooks ที่กำหนดเองยังคงสมเหตุสมผลเมื่อคุณต้องการการควบคุมเต็มรูปแบบ: แบ็กเอนด์ที่เป็นกรรมสิทธิ์, การจัดเก็บข้อมูลที่มีการควบคุม หรือการประมวลผลการอัปเดตที่ไม่เป็นไปตามมาตรฐาน สำหรับสิ่งอื่น ๆ ค่าใช้จ่ายในการดำเนินงานของการจัดการใบรับรอง, การตรวจสอบ และการจัดการการลองใหม่จะเพิ่มขึ้นอย่างรวดเร็ว

สรุป

การตั้งค่า webhook ของบอท Telegram ประกอบด้วยสี่ขั้นตอน: ปรับใช้ปลายทาง HTTPS, เรียกใช้ setWebhook, ตรวจสอบด้วย getWebhookInfo และตรวจสอบข้อผิดพลาด ใช้ secret_token สำหรับการตรวจสอบคำขอ, จำกัด allowed_updates ให้กับสิ่งที่คุณประมวลผล และทำให้ handler ทำงานได้อย่างรวดเร็ว

นักพัฒนาที่ต้องการการส่งแบบพุชในการผลิตโดยไม่ต้องเรียกใช้เซิร์ฟเวอร์สามารถใช้ TeleClaw แทนได้ วางโทเค็นของคุณ, กำหนดค่าพฤติกรรม AI และมุ่งเน้นไปที่สิ่งที่บอทพูดมากกว่าวิธีการอัปเดตมาถึง

พร้อมที่จะเปิดตัวบอท AI โดยไม่ต้องจัดการ webhooks แล้วหรือยัง? เพิ่ม @claw ไปยังกลุ่ม Telegram ของคุณ →