REST API — ทำงานอัตโนมัติกับ Telm จากโค้ดของคุณเอง

1API ทำอะไรได้บ้าง

Telm REST API ให้โค้ดของคุณเข้าถึงได้เท่ากับแดชบอร์ด: ส่งข้อความใดก็ได้ผ่านไปป์ไลน์ป้องกันสแปม ตรวจสอบผู้ใช้ Telegram ก่อนให้เข้ากลุ่ม อ่านและเปลี่ยนการตั้งค่าการปกป้องของกลุ่ม จัดการกฎที่กำหนดเองและรายการอนุญาต ดึงบันทึกการกลั่นกรองและข้อมูลการวิเคราะห์ และลงทะเบียนเว็บฮุกสำหรับเหตุการณ์แบบเรียลไทม์

สิ่งนี้เปลี่ยน Telm จากบอทที่อยู่ในกลุ่มของคุณให้กลายเป็นโครงสร้างพื้นฐานที่คุณเชื่อมต่อได้ทุกที่ — แบบฟอร์มลงทะเบียนบนเว็บไซต์ บอท CRM บอท Telegram ของคุณเอง หรือสคริปต์ที่ตั้งค่าร้อยกลุ่มพร้อมกัน

• URL ฐาน: api.telm.com/api/public/v1 — เส้นทางที่เสถียรและมีเวอร์ชัน (v1 คือเวอร์ชันของสัญญา API)
• ทุกคำขอและการตอบกลับเป็น JSON ผ่าน HTTPS
• เอกสารแบบโต้ตอบและสเปก OpenAPI 3.1 ที่เครื่องอ่านได้อยู่ในหน้านักพัฒนา — โหลดสเปกเข้า Postman ตัวสร้างโค้ด หรือเอเจนต์ AI เพื่อวางโครงการเชื่อมต่อได้ในไม่กี่นาที
• การเรียกที่นับโควตาจะคืนเฮดเดอร์ X-Quota-Limit, X-Quota-Used และ X-Quota-Reset ในทุกการตอบกลับ

2คำขอเดินทางผ่าน Telm อย่างไร

API สาธารณะอยู่บนคำนำหน้าเส้นทางของตัวเอง คือ /api/public/ แยกจากแดชบอร์ด ทุกการเรียกยืนยันตัวตนด้วยคีย์ API แทนเซสชันเบราว์เซอร์ ถูกตรวจสอบกับแพ็กเกจและโควตาของคุณ ประมวลผลด้วยเอนจินตัวเดียวกับที่กลั่นกรองกลุ่มของคุณอยู่จริง และส่งผลกลับเป็น JSON

เนื่องจาก API เข้าถึงเอนจินและข้อมูลชุดเดียวกับบอท ทุกอย่างที่คุณดูหรือเปลี่ยนได้ในแดชบอร์ดก็ทำได้ในโค้ดเช่นกัน — และการเปลี่ยนแปลงที่คุณทำผ่านโค้ดจะปรากฏในแดชบอร์ดทันที

• คำขอเป็นแบบ stateless: แต่ละคำขอพกคีย์ของตัวเองและเป็นอิสระจากคำขออื่น
• คีย์ทำงานในนามบัญชีของคุณ และแตะได้เฉพาะกลุ่มที่บัญชีของคุณเป็นแอดมิน
• endpoint ตรวจสอบสแปมใช้ไปป์ไลน์กฎตัวเดียวกับที่ทำงานจริงบนโปรดักชัน ผลตัดสินจาก API จึงตรงกับสิ่งที่บอทจะทำในกลุ่ม

3การยืนยันตัวตนด้วยคีย์ API

ทุกคำขอยืนยันตัวตนด้วยคีย์ API ในรูปแบบ tk_live_ ตามด้วยอักขระสุ่ม — ไม่ใช่การล็อกอินแดชบอร์ดของคุณ คุณสร้างคีย์ในบัญชีของคุณ แล้วส่งคีย์ในเฮดเดอร์ Authorization เป็น Bearer token หรือในเฮดเดอร์ X-API-Key

ความลับเต็มจะแสดงเพียงครั้งเดียวตอนสร้าง หลังจากนั้นแดชบอร์ดจะแสดงคีย์ด้วยคำนำหน้าสั้น ๆ เท่านั้น เพื่อให้คุณจดจำคีย์ได้โดยไม่ต้องเก็บค่าเต็มไว้ หากคีย์รั่ว ให้เพิกถอนแล้วออกคีย์ใหม่ — การเพิกถอนมีผลทันที

• ส่งคีย์เป็น Authorization: Bearer tk_live_your_key_here (ใช้เฮดเดอร์ X-API-Key ก็ได้)
• คีย์มีขอบเขตสิทธิ์ read หรือ write — read สำหรับคำขอ GET และ write สำหรับทุกอย่างที่เปลี่ยนข้อมูล คีย์แบบอ่านอย่างเดียวจะสร้างหรือแก้ไขอะไรไม่ได้
• คุณมีคีย์ที่ใช้งานอยู่ได้สูงสุดสิบคีย์พร้อมกัน จึงใช้คีย์แยกสำหรับแต่ละสคริปต์หรือบริการได้
• คีย์ที่หายไปหรือไม่ถูกต้องจะคืน 401 ส่วนคีย์ที่ไม่มีขอบเขตสิทธิ์ที่ต้องการจะคืน 403 insufficient_scope

4endpoint ที่มีให้ใช้

API จัดกลุ่มตามการตรวจสอบสแปมและผู้ใช้ การจัดการกลุ่ม และการจัดการบัญชีด้วยตนเอง endpoint ตรวจสอบสแปมเดี่ยวเปิดให้ทุกแพ็กเกจ ส่วนที่เหลือของ API เป็นส่วนหนึ่งของ Pro และ Business

• POST /spam/check — ส่งข้อความหนึ่งข้อความผ่านเอนจินกฎตัวเดียวกับที่กลั่นกรองทราฟฟิกจริง (ทุกแพ็กเกจ) เปิดการตรวจด้วย AI เพิ่มเติมได้บน Pro ขึ้นไป
• POST /spam/check-batch — ตรวจได้สูงสุด 20 ข้อความในการเรียกเดียว ใช้เฉพาะกฎ (Pro+)
• POST /users/check — ตรวจสอบผู้ใช้ Telegram: สถานะ CAS สัญญาณจากการตัดสินสแปมของ Telm และชื่อเสียงในกลุ่มของคุณ (Pro+)
• GET /groups และ GET /groups/{id} — แสดงรายการและอ่านข้อมูลกลุ่มของคุณ (Pro+)
• GET และ PATCH /groups/{id}/settings — อ่านและเปลี่ยนการตั้งค่าการปกป้องของกลุ่ม (Pro+)
• GET/POST/PUT/DELETE /groups/{id}/rules — จัดการกฎการกลั่นกรองที่กำหนดเอง (Pro+)
• GET/POST/DELETE /groups/{id}/whitelist — จัดการรายการอนุญาตของกลุ่ม (Pro+)
• GET /groups/{id}/journal และ GET /groups/{id}/analytics — อ่านบันทึกการกลั่นกรองและข้อมูลการวิเคราะห์ (Pro+)
• GET/POST/PATCH/DELETE /webhooks — จัดการเว็บฮุกสำหรับเหตุการณ์แบบเรียลไทม์ (Pro+)
• GET /usage และ GET /me — ตรวจสอบโควตาและข้อมูลคีย์ของคุณ สองตัวนี้ไม่ใช้โควตาเลย (ทุกแพ็กเกจ)

5endpoint ตรวจสอบสแปมโดยละเอียด

POST /spam/check คือหัวใจของ API และเป็น endpoint เดียวที่คุณลองได้บนทุกแพ็กเกจ ส่งเนื้อคำขอ JSON พร้อมข้อความที่ต้องการตรวจ การตอบกลับจะคืนผลตัดสิน คะแนนเชิงตัวเลข ค่าความมั่นใจ และการดำเนินการที่แนะนำ ซึ่งคุณนำไปใช้ในผลิตภัณฑ์ของคุณเองได้

ข้อความหนึ่งข้อความยาวได้สูงสุด 10,000 อักขระ บน Pro ขึ้นไปคุณเลือกเปิดการตรวจด้วย AI สำหรับกรณีที่ยากกว่าได้ โดยใช้โควตาการตรวจด้วย AI รายวันที่แยกต่างหาก สำหรับปริมาณสูง endpoint แบบชุดตรวจได้สูงสุด 20 ข้อความในการเรียกเดียวและนับโควตาต่อรายการ

• ใช้ผลตัดสินและคะแนนเพื่อกำหนดว่าผลิตภัณฑ์ของคุณจะทำอะไร — บล็อกการส่งแบบฟอร์ม ทำเครื่องหมายลีด หรือลบข้อความอัตโนมัติในบอทของคุณเอง
• endpoint แบบชุดใช้เฉพาะกฎ ลำดับขั้นการตรวจด้วย AI มีให้เฉพาะ endpoint ข้อความเดี่ยว
• ขนาดเนื้อคำขอมีเพดาน (ประมาณ 64 KB สำหรับการตรวจเดี่ยว และ 256 KB สำหรับแบบชุด) เนื้อคำขอที่ใหญ่เกินจะคืน 413

6แพ็กเกจ ขีดจำกัดอัตรา และโควตารายวัน

การเข้าถึงถูกนับสองแบบ คือ ขีดจำกัดอัตราต่อนาที (เพดานสำหรับการส่งพุ่งพรวด) และโควตาการเรียกรายวันที่รีเซ็ตตอนเที่ยงคืน UTC ทั้งสองนับต่อบัญชีและใช้ร่วมกันทุกคีย์ API ของคุณ คุณลอง endpoint ตรวจสอบสแปมเดี่ยวได้บนทุกแพ็กเกจ แต่การเชื่อมต่อจริงที่ใช้กฎ การตั้งค่า การตรวจสอบเป็นชุด และเว็บฮุก ต้องใช้ Pro ขึ้นไป

• Free — 100 การเรียกต่อวัน เฉพาะการตรวจสอบสแปม
• Pro — 10,000 การเรียกต่อวัน API เต็มรูปแบบและเว็บฮุก พร้อมการตรวจด้วย AI 1,000 ครั้งต่อวัน
• Business — 50,000 การเรียกต่อวัน API เต็มรูปแบบและเว็บฮุก พร้อมการตรวจด้วย AI 10,000 ครั้งต่อวัน
• ขีดจำกัดอัตราต่อนาทีก็เพิ่มตามแพ็กเกจ — 60 คำขอต่อนาทีบน Free, 600 บน Pro และ 1,800 บน Business
• GET /usage และ GET /me ไม่นับรวมในโควตาของคุณ คุณจึงตรวจสอบงบประมาณที่เหลือได้ทุกเมื่อ

7การจัดการข้อผิดพลาดและรหัสสถานะ

API ใช้รหัสสถานะ HTTP มาตรฐานพร้อมรหัสข้อผิดพลาดที่เครื่องอ่านได้ในเนื้อการตอบกลับ ออกแบบไคลเอนต์ให้อ่านรหัสเหล่านี้ แล้วรอก่อนลองใหม่หรือแนะนำให้อัปเกรด แทนที่จะลองใหม่ซ้ำ ๆ โดยไม่ดูเหตุผล

เมื่อคุณใช้เกินโควตารายวัน การเรียกที่นับโควตาจะคืน 429 พร้อมรหัส daily_quota_exceeded เฮดเดอร์ Retry-After และเนื้อการตอบกลับที่ระบุแพ็กเกจ ขีดจำกัด จำนวนที่ใช้ไป เวลารีเซ็ต และคำแนะนำให้อัปเกรด ส่วน endpoint ที่ต้องใช้แพ็กเกจสูงกว่าจะคืน 403 plan_required พร้อมระบุแพ็กเกจที่ต้องใช้

• 401 — คีย์ API หายไปหรือไม่ถูกต้อง
• 403 plan_required — endpoint ต้องใช้ Pro ขึ้นไป
• 403 insufficient_scope — คีย์ไม่มีขอบเขตสิทธิ์ write สำหรับการเรียกที่เปลี่ยนข้อมูล
• 429 daily_quota_exceeded หรือ rate_limit_exceeded — รอจนถึงเวลารีเซ็ตหรืออัปเกรด และปฏิบัติตามเฮดเดอร์ Retry-After
• อ่านเฮดเดอร์ X-Quota-* ในการตอบกลับเพื่อรู้ล่วงหน้าก่อนถึงขีดจำกัด

8แนวปฏิบัติที่ดีสำหรับการเชื่อมต่อที่มั่นคง

นิสัยไม่กี่อย่างช่วยให้การเชื่อมต่อเชื่อถือได้และปลอดภัยแม้ขยายตัวขึ้น

• เก็บคีย์ไว้ในตัวจัดการความลับ ห้ามเก็บในโค้ดฝั่งไคลเอนต์หรือคลัง git ใช้คีย์แยกต่อบริการ เพื่อให้เพิกถอนคีย์หนึ่งได้โดยไม่กระทบคีย์อื่น
• ติดตามเฮดเดอร์ X-Quota-Used และ X-Quota-Limit (หรือเรียก GET /usage เป็นระยะ) และชะลอคำขอก่อนชนขีดจำกัด ไม่ใช่หลังจากนั้น
• เมื่อได้ 429 ให้ปฏิบัติตาม Retry-After และรอก่อนลองใหม่ เมื่อได้ 403 plan_required ให้แสดงข้อความแนะนำให้อัปเกรดแทนการลองใหม่
• สำหรับการตอบสนองแบบเรียลไทม์ ให้ใช้เว็บฮุกแทนการ poll — ให้ Telm ส่งเหตุการณ์มาหาคุณ
• หมุนคีย์เป็นระยะ และหมุนทันทีหากคีย์อาจรั่วไหล

9สถานการณ์การเชื่อมต่อที่พบบ่อย

API ใช้ทำได้มากกว่าการกลั่นกรองข้อความ Telegram

• การลงทะเบียนบนเว็บไซต์และแอป: ส่งข้อความหรือชื่อผู้ใช้ที่ส่งเข้ามาผ่าน POST /spam/check ก่อนยอมรับการลงทะเบียนหรือความคิดเห็น
• บอท Telegram ของคุณเอง: นำความสามารถของ Telm ไปใช้ในบอทที่ Telm ไม่ได้จัดการ โดยเรียก endpoint ตรวจสอบจากโค้ดที่จัดการข้อความของบอทคุณ
• การตั้งค่าจำนวนมาก: เขียนสคริปต์ใช้กฎ รายการอนุญาต และการตั้งค่าชุดเดียวกันกับกลุ่มหลายสิบกลุ่มผ่าน endpoint การตั้งค่าและกฎ
• ข้อมูลและการแจ้งเตือน: ลงทะเบียนเว็บฮุกเพื่อสตรีมเหตุการณ์การกลั่นกรองเข้าสู่คลังข้อมูล แดชบอร์ด หรือช่องแจ้งเตือนแบบเรียลไทม์