1나머지 스택과 대화하는 모더레이션
전적으로 텔레그램 안에서만 사는 모더레이션 봇은 유용하지만, 동시에 하나의 섬이기도 합니다. 그 봇이 내리는 결정 — 삭제하는 모든 메시지, 심사하는 모든 사용자, 되돌려 보내는 모든 레이드 — 은 누군가 텔레그램을 열어 들여다보지 않는 한 채팅 창 안에 갇혀 있습니다. 커뮤니티 하나라면 그것으로 괜찮습니다. 하지만 더 큰 운영의 일부로 모더레이션을 돌리는 팀에게는, 누가 여러분의 공간을 악용하는지 가장 많이 아는 그 시스템이, 여러분이 운영하는 다른 어떤 것과도 대화할 수 없는 시스템이라는 뜻이 됩니다.
공개 REST API와 웹훅은 그 간극을 메웁니다. 이들은 Telm을 자기완결적인 봇에서, 여러분이 이미 가진 도구에 연결할 수 있는 구성 요소로 바꿉니다: 여러분의 모니터링과 온콜 체계, 컴플라이언스 아카이브, 여러분 자신의 제품, 내부 대시보드로요. 여러분의 그룹을 보호하는 바로 그 엔진이, 여러분의 다른 시스템이 질의하고, 수신하고, 구동할 수 있는 대상이 됩니다.
이 안내서는 API와 웹훅이 실제로 무엇을 노출하는지 — 엔드포인트, 이벤트, 보안 모델 — 그리고 팀들이 그것으로 무엇을 만드는지 구체적으로 짚어 봅니다. 아래의 모든 것은 오늘 사용할 수 있는 실제 기능입니다; 기다려야 할 SDK도 없고, 제품이 계획만 하고 있는 것을 설명한 부분도 없습니다.
2REST API와 여러분의 키
API는 `https://api.telm.com/api/public/v1`에 있습니다. 평범한 REST 인터페이스로 — 어떤 언어에서든 일반적인 HTTPS 요청과 JSON으로 호출하며, 특별한 클라이언트 라이브러리가 필요 없습니다. 여러분의 코드가 HTTP 요청을 보낼 수 있다면, Telm과 대화할 수 있습니다.
인증은 API 키로 합니다. 대시보드의 Settings → API & Webhooks에서 키를 생성하며, 각 키는 생성 시 정확히 한 번만 표시됩니다 — 그 자리에서 여러분의 시크릿 저장소에 복사해 두세요, 이후에는 다시 가져올 수 없기 때문입니다. 키에는 `tk_live_` 접두사가 붙어 로그와 설정에서 알아보기 쉽습니다. 모든 키는 범위 — 읽기 또는 쓰기 — 를 가지므로, 결정 로그만 가져오면 되는 서비스는 읽기 전용 키를 보유하고, 설정을 변경하는 자동화에는 쓰기 키를 줍니다. 시스템마다 키를 하나씩 발급하면, 유출되거나 폐기된 키를 취소해도 다른 키들은 전혀 영향을 받지 않습니다.
사용량은 플랜에 연동된 일일 요청 할당량으로 관리되므로, 처리량이 예측 가능하고 폭주하는 스크립트 하나가 전부를 소진할 수 없습니다. 가장 가벼운 검사 — 텍스트 스팸 스캔 — 는 그 할당량 범위 안에서 모든 플랜에서 제공되고; 결정 저널부터 설정 관리, 웹훅까지 더 넓은 기능은 Pro와 Business 플랜의 일부입니다. 정확한 수치는 끝부분에 정리되어 있습니다.
3필요할 때 텍스트와 사용자 심사하기
두 개의 엔드포인트로 Telm의 판단을 필요할 때마다 여러분 자신의 코드에서 실행할 수 있습니다 — 메시지가 텔레그램 그룹을 거치지 않고도요.
`POST /spam/check`는 텍스트 한 조각을 여러분의 커뮤니티를 지키는 바로 그 운영 엔진에 통과시켜 — 공유 스패머 신호, 패턴 규칙, 분류기 — 판정을 반환합니다. 이것이 모든 플랜에서 제공되는 유일한 호출이며, 그래서 여러분 자신의 제품을 위한 자연스러운 스팸 필터가 됩니다: 댓글, 가입 소개글, 지원 티켓, 마켓플레이스 목록을 여러분의 텔레그램 공간을 보호하는 것과 동일한 탐지로 심사하세요. 더 어렵고 모호한 경우를 위해 `include_ai`를 더하면 AI 판정을 포함할 수 있으며(Pro와 Business에서 제공), 그 플랜에서는 항목마다 한 번씩 호출하는 대신 한 요청에 최대 스무 개의 텍스트를 배치로 처리할 수 있습니다.
`POST /users/check`는 메시지가 아니라 사람을 심사합니다. 전역 CAS 차단 목록과, 여러 커뮤니티의 모더레이션에서 구축된 Telm 자체 데이터셋을 결합해 위험 등급을 반환하므로(Pro와 Business에서), 얼마만큼의 마찰을 적용할지 결정할 수 있습니다 — 깨끗한 계정은 곧바로 통과시키고, 위험한 계정은 검토를 위해 붙잡아 두세요. 이것을 여러분 자신의 온보딩에 연결하면, 텔레그램 그룹에 가입한 뒤가 아니라 여러분의 웹사이트나 앱의 문턱에서 알려진 악성 행위자를 잡아낼 수 있습니다.
두 호출 모두 즉석에서 답합니다: 텍스트나 사용자를 보내면 응답으로 평가를 돌려받습니다. 폴링할 큐도, 기다릴 콜백도 없습니다 — 결정이 응답과 함께 옵니다.
4그 일이 일어나는 순간 밀려 들어오기
저널을 폴링하는 것은 아카이빙에는 좋지만, 무언가가 발생하는 즉시 그것에 *반응*하고 싶을 때는 물어보는 게 아니라 밀려 받고 싶어집니다. 웹훅(Pro와 Business에서)이 바로 그 일을 합니다: 여러분이 엔드포인트를 등록하면, 관련 이벤트가 발동하는 순간 Telm이 그곳으로 HTTP 요청을 보냅니다. 이벤트는 중요한 순간들을 아우릅니다 — 콘텐츠에 대한 `spam.detected`와 `message.suspicious`, 그리고 멤버십에 대한 `user.banned`, `user.kicked`, `user.muted`, `user.joined`, `user.left`.
가장 뚜렷한 용도는 스팸 물결을 알림으로 바꾸는 것입니다. `spam.detected`를 여러분의 모니터링이나 온콜 시스템에 연결하면, 갑작스러운 급증이 여러분의 다른 인시던트가 도착하는 바로 그곳에서 당직자에게 가는 호출이 됩니다 — 공격이 시작되는 것을 알아채기 위해 누구도 텔레그램을 지켜보고 있을 필요가 없습니다. 동일한 스트림이 실시간 대시보드를 채우고, 외부 시스템을 차단 상태와 동기화하며, 여러분이 원하는 어떤 워크플로든 촉발합니다.
이 요청들은 바깥 세상에서 여러분의 인프라로 들어오는 것이므로, 모든 전달에 서명이 붙습니다. 각 요청에는 `v1=hex(hmac_sha256(secret, "timestamp.body"))` 형태의 `X-Telm-Signature` 헤더가 실려 있습니다 — 타임스탬프와 원시 본문에 대한 HMAC-SHA256이며, 오직 여러분과 Telm만 공유하는 시크릿으로 키가 지정됩니다. 여러분 쪽에서 그 서명을 다시 계산하면 요청이 진짜 Telm에서 왔고 전송 중에 위조되거나 변조되지 않았음이 증명됩니다; 타임스탬프는 오래된 재전송을 거부하게 해 줍니다. 페이로드를 신뢰하기 전에 서명을 검증하세요 — 몇 줄의 코드이며, 안전한 웹훅 수신기에서 가장 중요한 단 하나의 단계입니다.
5믿고 의지할 수 있는 전달
푸시 모델은 여러분의 엔드포인트가 느리거나, 재시작 중이거나, 잠시 다운된 순간을 감당할 수 있어야만 신뢰할 수 있습니다 — 그리고 Telm의 것은 그렇습니다. 전달은 최소 한 번 방식입니다: 모든 이벤트에는 안정적인 `id`가 실려 있고, Telm은 여러분의 엔드포인트가 확인할 때까지 계속 시도합니다. 최소 한 번이라는 것은 같은 이벤트가 정당하게 두 번 도착할 수 있다는 뜻이므로, 그 `id`로 중복을 제거하세요 — 이미 처리한 것을 기록하고 반복은 무시하세요 — 그러면 전달이 몇 번 재시도되든 여러분의 처리는 정확하게 유지됩니다.
재시도는 곤경에 빠진 엔드포인트를 두들기는 대신 점점 넓어지는 일정을 따릅니다: 즉시, 그다음 1분, 5분, 30분, 2시간, 6시간 후 — 총 여섯 번의 시도로, 회복 중인 서비스가 돌아올 여유를 주도록 간격을 벌려 놓았습니다. 엔드포인트가 계속 망가진 상태라면 — 연속 스무 번 실패에 성공적인 전달 없이 일흔두 시간이 지나면 — Telm은 그곳으로 보내는 것을 자동으로 멈추고 텔레그램으로 알려 주므로, 죽은 URL이 쌓여 가는 실패의 조용한 홍수가 아니라 수신기를 고치라는 분명한 알림이 됩니다.
새 연동을 제대로 만들기 위해, 실제 이벤트를 유발해 테스트할 필요는 없습니다. 테스트 핑으로 여러분의 엔드포인트에 샘플 전달을 원할 때마다 쏘아 서명 검사와 핸들러가 작동하는지 확인할 수 있고, 전달 이력은 무엇이 보내졌고 각 시도가 어떻게 됐는지 보여줍니다 — 그래서 오작동하는 수신기를 추측이 아니라 기록으로 디버깅할 수 있습니다.
6모든 결정에 대한 질의 가능한 기록
엔진이 결정하는 모든 것은 기록되며, `GET journal`이 그 기록을 여러분의 코드에 건네줍니다. 각 항목은 결정 하나입니다: 판정, 그 뒤의 점수, 어떤 규칙이 발동했는지, 그리고 뒤따른 조치. 커서 페이지네이션이 적용되어 있어, 전체 이력을 신뢰성 있게 — 페이지에서 페이지로, 공백이나 중복 없이 — 훑어 여러분이 기록을 보관하는 곳으로 가져올 수 있습니다.
그래서 저널은 컴플라이언스 아카이브의 근간이 됩니다. 플랫폼 정책, 고객 계약, 규제 기관을 위해 왜 회원이 제거되었는지 보여줘야 하는 팀은, 정해진 일정에 따라 로그를 자신들의 장기 저장소로 내보내, 텔레그램을 거슬러 스크롤하는 데 의존하지 않는, 모든 집행 조치에 대한 독립적이고 질의 가능한 기록을 갖습니다. 이는 대시보드의 감사 로그가 사람에게 보여주는 바로 그 증거를, 여러분의 시스템이 이용할 수 있게 만든 것입니다.
그와 함께, 분석 엔드포인트는 일별 시계열 — 시간에 따른 양과 추세 — 을 반환하므로, 모더레이션 부하를 화면에서 읽는 대신 여러분이 추적하는 다른 모든 것 옆에서 여러분 자신의 비즈니스 인텔리전스 도구로 도표화할 수 있습니다. 저널과 분석 모두 Pro와 Business 플랜의 일부입니다.
7코드로 여러 그룹 관리하기
API는 읽고 수신하기만 하는 것이 아니라 — 씁니다. Pro와 Business에서는 그룹의 설정을 `PATCH`하고, 그 규칙과 화이트리스트에 대해 완전한 생성/읽기/수정/삭제를 프로그램으로 실행할 수 있습니다. 대시보드에서 손으로 구성하던 무엇이든, 스크립트로 구성할 수 있습니다.
그것이 대규모 모더레이션 운영을 현실적으로 만드는 요소입니다. 수십 개의 커뮤니티를 관리하는 에이전시나 대형 운영자는 각 그룹을 하나씩 열어 같은 변경을 클릭해 넣고 싶어 하지 않습니다; 정책을 한 번 정의해 어디에나 적용하고 싶어 합니다. API를 쓰면 새 규칙을 배포하고, 임계값을 조정하고, 전체 그룹의 모든 화이트리스트에 주소를 추가하는 일을 자동화된 한 번의 실행으로 처리하고, 기준이 발전하는 대로 그룹들을 발맞춰 유지할 수 있습니다.
또한 모더레이션 정책이 여러분 자신의 소스 관리 안에서 살게 해 줍니다. 원하는 구성을 코드로 두고 API를 통해 적용하면, 여러분의 그룹이 어떻게 통제되는지에 대한 모든 변경이 나머지 인프라와 마찬가지로 검토되고 버전 관리됩니다 — 어느 채팅에서 어떤 설정을 토글했는지 기억하는 것과는 거리가 먼 방식이지요.
8각 플랜에 포함된 것
구분선은 단순합니다. 텍스트 스팸 검사는 모든 플랜에서 제공되므로, 무료 등급조차 Telm의 탐지를 자기 제품의 필터로 사용할 수 있습니다. 전체 기능 — 위험 등급이 포함된 사용자 심사, 결정 저널과 분석, 설정과 규칙 관리, 그리고 웹훅 — 은 Pro와 Business 플랜의 일부입니다.
모든 플랜에는 일일 요청 할당량이 주어지며, 더 무거운 연동이 더 무거운 플랜에 자리하도록 크기가 정해져 있습니다:
- **Free** — 하루 100 API 요청, 스팸 검사 전용.
- **Basic** — 하루 1,000 API 요청, 스팸 검사 전용.
- **Pro** — 하루 10,000 API 요청, 여기에 전체 API 기능과 웹훅.
- **Business** — 하루 50,000 API 요청, 여기에 전체 API 기능과 웹훅.
- Settings → API & Webhooks에서 키를 생성해 시크릿 저장소에 보관하고, 모든 웹훅의 서명을 검증하세요. 그러면 여러분의 그룹을 지키는 바로 그 엔진이 여러분 자신의 스택의 일부가 됩니다.