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

1API ให้คุณทำอะไรได้

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

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

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

2คำขอไหลผ่าน Telm อย่างไร

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

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

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

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

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

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

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

4เอนด์พอยต์ที่มีให้ใช้

API จัดระเบียบรอบการตรวจสแปมและผู้ใช้ การจัดการกลุ่ม และการบริการตนเองของบัญชี เอนด์พอยต์ตรวจสแปมเดี่ยวเปิดให้ทุกแพ็กเกจ ส่วนที่เหลือของ 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 — ตรวจสอบโควตาและข้อมูลคีย์ของคุณ สิ่งเหล่านี้ไม่ใช้โควตา (ทุกแพ็กเกจ)

5เอนด์พอยต์ตรวจสแปมโดยละเอียด

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

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

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

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

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

• Free — 100 การเรียก/วัน ตรวจสแปมเท่านั้น
• Basic — 1,000 การเรียก/วัน ตรวจสแปมเท่านั้น
• Pro — 10,000 การเรียก/วัน API แบบเต็มและเว็บฮุก บวกโควตาการตรวจ AI รายวัน
• Business — 50,000 การเรียก/วัน API แบบเต็มและเว็บฮุก โควตา AI ที่ใหญ่กว่า
• ขีดจำกัดอัตราต่อนาทีก็ปรับด้วย — แพ็กเกจสูงกว่าได้เพดานการเบิร์สต์ที่ใหญ่กว่ามาก

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

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

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

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

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

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

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

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

API ถูกใช้เพื่ออะไรมากกว่าการกลั่นกรองข้อความ Telegram มาก

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