REST API — 여러분의 코드에서 Telm 자동화하기

1API로 할 수 있는 일

Telm REST API를 쓰면 여러분의 코드에서 대시보드와 같은 일을 할 수 있습니다: 어떤 텍스트든 스팸 방지 파이프라인에 넣고, 들여보내기 전에 텔레그램 사용자를 조회하고, 그룹의 보호 설정을 읽고 바꾸고, 커스텀 규칙과 화이트리스트를 관리하고, 모더레이션 기록과 분석 데이터를 가져오고, 실시간 이벤트를 위한 웹훅을 등록합니다.

이로써 Telm은 그룹 안에 사는 봇에서 어디에든 연결할 수 있는 인프라로 바뀝니다 — 웹사이트 가입 양식, CRM 봇, 직접 만든 텔레그램 봇, 또는 백 개의 그룹을 한 번에 설정하는 스크립트까지.

• 기본 URL: api.telm.com/api/public/v1 — 안정적인 버전 경로입니다(v1은 계약 버전).
• 모든 요청과 응답은 HTTPS 위의 JSON입니다.
• 대화형 문서와 기계가 읽을 수 있는 OpenAPI 3.1 명세는 개발자 페이지에 있습니다 — 명세를 Postman, 코드 생성기, AI 에이전트에 불러오면 몇 분 만에 연동의 뼈대를 만들 수 있습니다.
• 측정 대상 호출은 모든 응답에 X-Quota-Limit, X-Quota-Used, X-Quota-Reset 헤더를 반환합니다.

2요청이 Telm을 거치는 과정

공개 API는 대시보드와 분리된 자체 경로 접두사 /api/public/에 있습니다. 각 호출은 브라우저 세션이 아닌 API 키로 인증되고, 플랜과 할당량에 비추어 확인된 뒤, 그룹을 모더레이션하는 것과 같은 실제 엔진에서 처리되어 JSON으로 반환됩니다.

API는 봇과 같은 엔진과 데이터에 접근하므로, 대시보드에서 보거나 바꿀 수 있는 것은 무엇이든 코드로도 할 수 있으며, 코드로 바꾼 내용은 즉시 대시보드에 나타납니다.

• 요청은 상태를 저장하지 않습니다: 각 요청이 자신의 키를 담고 그 자체로 완결됩니다.
• 키는 여러분의 계정을 대신해 작동하며 여러분의 계정이 관리자인 그룹에만 접근할 수 있습니다.
• 스팸 검사 엔드포인트는 실제 운영 중인 규칙 파이프라인과 똑같은 것에 접근하므로, API 판정은 봇이 그룹에서 내릴 판단과 일치합니다.

3API 키 인증

모든 요청은 대시보드 로그인이 아니라 tk_live_ 뒤에 무작위 문자가 붙는 형태의 API 키로 인증됩니다. 키는 계정에서 만들고, Authorization 헤더에 Bearer 토큰으로 넣거나 X-API-Key 헤더로 보냅니다.

전체 비밀 값은 만들 때 한 번만 표시됩니다. 그 뒤로 대시보드는 키를 짧은 접두사로만 표시하므로, 전체 값을 저장하지 않고도 알아볼 수 있습니다. 키가 유출되면 폐기하고 새 키를 발급하세요 — 폐기는 즉시 적용됩니다.

• 키는 Authorization: Bearer tk_live_your_key_here로 보냅니다(X-API-Key 헤더도 작동합니다).
• 키에는 읽기 또는 쓰기 범위가 있습니다 — GET 요청에는 읽기, 데이터를 바꾸는 요청에는 쓰기가 필요합니다. 읽기 전용 키로는 만들거나 수정할 수 없습니다.
• 활성 키는 동시에 최대 10개까지 둘 수 있어, 스크립트나 서비스마다 별도의 키를 쓸 수 있습니다.
• 키가 없거나 올바르지 않으면 401이, 필요한 범위가 없는 키는 403 insufficient_scope가 반환됩니다.

4사용할 수 있는 엔드포인트

API는 스팸 및 사용자 검사, 그룹 관리, 계정 셀프서비스를 중심으로 구성됩니다. 단일 스팸 검사 엔드포인트는 모든 플랜에 열려 있으며, 나머지는 Pro와 Business에 포함됩니다.

• POST /spam/check — 텍스트 하나를 실제 트래픽을 모더레이션하는 것과 같은 규칙 엔진에 넣습니다(모든 플랜). Pro 이상에서는 선택적으로 AI 검사를 켤 수 있습니다.
• POST /spam/check-batch — 한 번의 호출로 최대 20개 텍스트를 규칙만으로 검사합니다(Pro 이상).
• POST /users/check — 텔레그램 사용자를 조회합니다: 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 자정에 초기화되는 일일 호출 할당량입니다. 둘 다 계정 단위로 집계되며 모든 API 키가 공유합니다. 단일 스팸 검사 엔드포인트는 어떤 플랜에서든 써 볼 수 있지만, 규칙, 설정, 배치 검사, 웹훅을 다루는 실제 연동에는 Pro 이상이 필요합니다.

• Free — 하루 100회, 스팸 검사만.
• Pro — 하루 10,000회, 전체 API와 웹훅, 그리고 하루 1,000회 AI 검사.
• Business — 하루 50,000회, 전체 API와 웹훅, 그리고 하루 10,000회 AI 검사.
• 분당 속도 제한도 함께 올라갑니다 — Free는 분당 60건, Pro는 600건, Business는 1,800건.
• GET /usage와 GET /me는 할당량에서 차감되지 않으므로 언제든 남은 한도를 확인할 수 있습니다.

7오류 처리와 상태 코드

API는 표준 HTTP 상태 코드를 쓰며 본문에 기계가 읽을 수 있는 오류 코드를 담습니다. 무작정 재시도하는 대신 이 코드를 읽어 잠시 기다리거나 업그레이드를 안내하도록 클라이언트를 만드세요.

일일 할당량을 넘으면 측정 대상 호출은 daily_quota_exceeded 코드, Retry-After 헤더, 그리고 플랜, 한도, 사용량, 초기화 시각, 업그레이드 안내가 담긴 본문과 함께 429를 반환합니다. 더 높은 플랜이 필요한 엔드포인트는 필요한 플랜과 함께 403 plan_required를 반환합니다.

• 401 — API 키가 없거나 올바르지 않음.
• 403 plan_required — 해당 엔드포인트에는 Pro 이상이 필요함.
• 403 insufficient_scope — 변경 호출에 필요한 쓰기 범위가 키에 없음.
• 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에서는 재시도하지 말고 업그레이드 안내를 보여 주세요.
• 실시간으로 대응하려면 폴링보다 웹훅을 택하세요 — Telm이 이벤트를 보내도록 하세요.
• 키는 주기적으로 교체하고, 유출되었을 수 있다면 즉시 교체하세요.

9자주 쓰이는 연동 시나리오

API는 텔레그램 메시지 모더레이션보다 훨씬 다양한 곳에 쓰입니다.

• 웹사이트와 앱 가입: 가입이나 댓글을 받기 전에 제출된 텍스트나 사용자 이름을 POST /spam/check에 넣어 보세요.
• 직접 만든 텔레그램 봇: 핸들러에서 검사 엔드포인트를 호출해 Telm이 관리하지 않는 봇에서도 Telm의 판단력을 재사용하세요.
• 일괄 설정: 설정 및 규칙 엔드포인트로 같은 규칙, 화이트리스트, 설정을 수십 개 그룹에 스크립트로 적용하세요.
• 데이터와 알림: 웹훅을 등록해 모더레이션 이벤트를 데이터 웨어하우스, 대시보드, 알림 채널로 실시간 전송하세요.