채널 프로필
1 크레딧/v1/telegram/profile이름과 소개글, 프로필 이미지, 인증 배지, 정확한 구독자 수를 반환합니다. 그룹은 같은 필드로 멤버 수를 반환합니다. 공개 미리보기가 없는 채널은 404를 반환하며 과금되지 않습니다.
handle
SocialCrawl이 제공하는 텔레그램 엔드포인트
공개 텔레그램 채널과 그룹을 읽는 엔드포인트 3개가 운영 중입니다. 채널 프로필과 게시물 기록, 주소로 조회하는 개별 게시물을 제공합니다.
채널 게시물
1 크레딧/v1/telegram/profile/posts공개 게시물 한 페이지를 본문과 작성 시각, 조회 수, 이모지별 반응 수, 사진과 영상 주소와 함께 반환합니다. 커서를 넘기면 더 과거로 이동합니다. 페이지 크기는 일정하지 않으므로 커서가 사라질 때까지 계속 요청해야 합니다.
handle, cursor
개별 게시물
1 크레딧/v1/telegram/postt.me 주소로 게시물 하나를 목록 행과 같은 필드로 반환합니다. 사진 묶음은 첫 장만이 아니라 전부 반환됩니다. 조회 수와 반응 수는 텔레그램 공개 화면에서 반올림된 값입니다.
url
Telegram API4개 엔드포인트 지원
문서 보기Profiles
공개 텔레그램 채널이나 그룹의 프로필을 반환합니다. 표시 이름과 소개글, 프로필 이미지 URL, 인증 배지, 정확한 구독자 수가 담깁니다.
핸들만 있고 채널 개요를 보고 싶을 때, 또는 글을 넘겨보기 전에 공개 채널인지 확인할 때 사용하세요.
1크레딧
GET/v1/telegram/profile?handle=telegram
handle · Public Telegram handle, with or without the leading @, or a t.me channel URL
$ curl https://www.socialcrawl.dev/v1/telegram/profile?handle=telegram \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다SocialCrawl 텔레그램 API의 동작 방식
텔레그램은 일반적인 SocialCrawl 소셜 엔드포인트입니다. API 키로 GET /v1/telegram/… 을 호출하면 라이브 미스에만 크레딧이 차감되고 단일 JSON 응답이 반환됩니다. 봇 토큰과 전화번호, MTProto 세션은 필요하지 않습니다.
모든 호출에 인증
x-api-key 헤더에 키를 담아 보냅니다. 같은 키가 SocialCrawl 카탈로그 전 구간에서 동작합니다.
쿼리 파라미터로 GET 요청
모든 경로는 GET입니다. 핸들과 게시물 주소, 커서를 쿼리 문자열로 전달합니다. 과금 전에 형식을 검증하므로 비공개 초대 링크는 크레딧 없이 거부됩니다.
좌석이 아닌 크레딧 과금
텔레그램 경로는 라이브 미스 기준 모두 1 크레딧입니다. 캐시 적중은 0 크레딧입니다. 조회 실패와 잘못된 입력은 과금되지 않습니다.
단일 JSON 응답 구조
모든 응답은 success, data, credits_used, credits_remaining, request_id, cached로 동일한 형태입니다.
일반적인 연동 순서
대부분의 제품은 채널을 확인하고 기록을 페이지 단위로 받은 뒤 필요한 게시물만 자세히 조회합니다.
01채널
GET /v1/telegram/profile정확한 구독자 수가 담긴 Author 형태 프로필
핸들을 한 번 확인하고 공개 채널인지 확정합니다.
02기록
GET /v1/telegram/profile/posts최근 공개 게시물의 PostList
커서가 사라질 때까지 페이지를 넘깁니다.
03과거 데이터
GET /v1/telegram/profile/posts같은 커서로 이어지는 이전 페이지
짧은 페이지는 채널의 끝을 의미하지 않으므로 계속 요청합니다.
04게시물
GET /v1/telegram/postt.me 주소 하나에 대한 전체 Post
이미 주소를 가지고 있고 피드가 필요 없을 때 사용합니다.
요청
GET /v1/telegram/profile
?handle=telegram
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here응답 봉투
{
"success": true,
"data": { "/* Author | Post | PostList */": true },
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}data에 담기는 내용
아키타입이 일치하는 구간에서는 필드 이름이 다른 SocialCrawl 엔드포인트와 같습니다.
Authorprofile
id, username, display_name, avatar_url, bio, followers, verified, url
PostListprofile/posts
items[].post 안의 id, url, content, engagement, author, published_at, ext
Postpost
id, url, content.text, content.media_urls, engagement.views, published_at
Reactionsprofile/posts
post.ext.reaction_counts 안의 반응별 이모지와 개수
게이트웨이 내부 동작
다른 /v1 플랫폼 엔드포인트와 요청 처리 흐름이 같습니다.
- 01
엣지에서 요청 수신
Next.js 캐치올 라우트가 Hono 소셜 API로 전달합니다. request_id를 발급하고 키를 인증한 뒤 요청 한도와 동시성을 적용합니다.
- 02
검증 후 차감
레지스트리에서 경로를 찾습니다. 핸들과 주소 형식을 먼저 검사하므로 잘못된 핸들이나 초대 링크는 과금 없이 400을 반환합니다.
- 03
캐시 확인 또는 원본 조회
플랫폼과 리소스, 파라미터로 결정적 캐시 키를 만듭니다. 적중하면 credits_used가 0입니다. 미스면 재시도와 서킷 브레이커를 거쳐 원본을 조회합니다.
- 04
정규화 후 반환
원본 JSON을 Author와 Post, PostList로 매핑하고 검증한 뒤 성공 응답으로 감싸고 과금 감사를 위해 기록합니다.
운영에서 중요한 과금 규칙
- 채널 프로필: 1 크레딧
- 채널 게시물: 페이지당 1 크레딧
- 개별 게시물: 1 크레딧
- 캐시 적중: 0 크레딧
- 채널 조회 실패: 404이며 과금되지 않습니다
- 잘못된 핸들 또는 텔레그램이 아닌 주소: 400이며 과금되지 않습니다
- 비공개 또는 초대 전용 링크: 원본 호출 전에 400으로 거부됩니다
- 크레딧 부족: 402이며 과금되지 않습니다
- 중지된 경로: 503이며 과금되지 않습니다
SocialCrawl이 텔레그램 데이터를 가져오는 방식
텔레그램은 SocialCrawl에서 공개 읽기 전용 데이터입니다. 공개 채널 화면을 공유 스키마로 정규화하므로 Bot API나 MTProto를 따로 익힐 필요가 없습니다.
이 API에서 다루는 텔레그램의 범위
공개 미리보기를 제공하는 공개 채널과 그룹입니다. 조사와 모니터링, 제품 작업을 위한 읽기 전용입니다.
SocialCrawl이 접근하는 방식
게이트웨이 뒤의 소셜 읽기 업스트림을 통해 조회합니다. 읽으려는 채널에 봇이 관리자로 있을 필요가 없습니다.
엣지에서 나가는 형태
success, data, credits_used, request_id, cached로 구성된 통합 JSON 응답입니다. 미디어는 바로 내려받거나 삽입할 수 있는 주소로 반환됩니다.
제공하지 않는 범위
쓰기 엔드포인트와 비공개 채널, 다이렉트 메시지, 멤버 목록은 제공하지 않습니다. 게시물 댓글은 별도의 토론 그룹에 있어 노출되지 않습니다.
필드 매핑
public channel profile→ author.*채널 식별 정보와 구독자 수, 프로필 이미지
public channel post→ post.* / items[].post게시물 본문과 조회 수, 미디어, 작성 시각
per emoji reaction counts→ post.ext.reaction_counts이모지별 반응 수
텔레그램 API의 활용 분야
이 API가 가장 많이 쓰이는 작업입니다.
3active Telegram endpoints in the registry
1 / 1 / 1프로필과 게시물, 개별 게시물의 크레딧
텔레그램 채널 모니터링과 콘텐츠 보관
호출은 채널 게시물 기록에 집중되며, 이미 주소를 가진 개별 게시물을 이어서 조회합니다. 재개 가능한 커서로 채널 기록 전체를 페이지당 1 크레딧에 받고, 봇 토큰 없이 바로 열리는 미디어 주소를 함께 얻습니다.
채널 조회는 라이브 미스 기준 보통 수 초가 걸립니다. 캐시 적중은 즉시 반환됩니다.
활용 사례
팀이 이 데이터를 실제로 활용하는 방식과 주로 쓰는 스택입니다.
채널 모니터링
Python, cron, Slack 봇채널의 최신 페이지를 주기적으로 조회하고 새 게시물이 올라오거나 조회 수가 급증할 때 알립니다.
조사와 보관
Node, 노트북, BI 적재커서로 채널 기록 전체를 한 번 수집한 뒤 첫 페이지만으로 최신 상태를 유지합니다.
백엔드 제품 작업
Go, 워커, Explorer채널을 확인하고 게시물을 페이지 단위로 받아 미디어 주소를 그대로 자체 파이프라인에 넣습니다.
텔레그램 API 호출 방법
라이브 미스는 1 크레딧이 차감됩니다. 캐시 적중은 무료입니다. 조회 실패와 잘못된 입력은 과금되지 않습니다.
curl "https://www.socialcrawl.dev/v1/telegram/profile?handle=telegram" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/telegram/profile/posts?handle=telegram" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
Telegram API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
비교
SocialCrawl과 공식 텔레그램 API, 뭐가 다른가요?
같은 Telegram 데이터를 받는 두 가지 방법을 나란히 비교했어요. 인증부터 비용까지 한눈에 확인해 보세요.
| 항목 | SocialCrawl | 공식 텔레그램 API |
|---|---|---|
| 공개 채널 읽기 | 핸들이나 t.me 주소만 있으면 가능 | 봇이 관리자인 채널만 읽을 수 있음 |
| 필요한 인증 | x-api-key 하나 | 봇 토큰, MTProto는 실제 전화번호 계정 필요 |
| 게시물 기록 | 커서로 공개 기록 전체를 넘겨보기 | 실시간으로 받은 메시지 외에는 조회 불가 |
| 미디어 | 사진과 영상 모두 바로 열리는 주소 | 파일 id를 받아 인증 다운로드를 한 번 더 |
| 응답 형태 | 다른 플랫폼과 동일한 표준 JSON | 프로토콜 플래그와 int64 id가 섞인 원본 객체 |
| 호출 제한 | 계정 기본 한도, 채널별 제한 없음 | 봇·채팅 단위 플러드 제한이 걸림 |
공개 채널 읽기
SocialCrawl
핸들이나 t.me 주소만 있으면 가능
공식 텔레그램 API
봇이 관리자인 채널만 읽을 수 있음
필요한 인증
SocialCrawl
x-api-key 하나
공식 텔레그램 API
봇 토큰, MTProto는 실제 전화번호 계정 필요
게시물 기록
SocialCrawl
커서로 공개 기록 전체를 넘겨보기
공식 텔레그램 API
실시간으로 받은 메시지 외에는 조회 불가
미디어
SocialCrawl
사진과 영상 모두 바로 열리는 주소
공식 텔레그램 API
파일 id를 받아 인증 다운로드를 한 번 더
응답 형태
SocialCrawl
다른 플랫폼과 동일한 표준 JSON
공식 텔레그램 API
프로토콜 플래그와 int64 id가 섞인 원본 객체
호출 제한
SocialCrawl
계정 기본 한도, 채널별 제한 없음
공식 텔레그램 API
봇·채팅 단위 플러드 제한이 걸림
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기텔레그램 채널 데이터는 어떻게 수집하나요?
SocialCrawl에서 채널 프로필, 채널 게시물 기록, 개별 게시물까지 텔레그램 엔드포인트 4개를 쓰실 수 있어요. 채널 핸들이나 t.me 주소를 x-api-key와 함께 GET으로 보내면 정규화된 JSON이 바로 옵니다. 봇 토큰을 만들 필요도, 전화번호를 등록할 필요도 없어요.
봇 토큰이나 전화번호가 있어야 하나요?
아니요. 공식 Bot API는 봇이 관리자로 있는 채널만 읽을 수 있고, MTProto는 실제 전화번호로 개통한 계정이 필요해요. SocialCrawl은 공개 채널 화면을 그대로 읽기 때문에 핸들만 알면 어떤 공개 채널이든 가져올 수 있습니다.
어떤 텔레그램 채널을 읽을 수 있나요?
공개 미리보기 페이지가 열려 있는 공개 채널과 그룹입니다. 비공개 채널, 초대 전용 그룹, 소유자가 미리보기를 꺼둔 채널은 읽을 수 없고, 빈 결과 대신 명확한 not found 응답이 돌아와요.
조회 수와 반응 수는 정확한 값인가요?
채널 프로필의 구독자 수는 정확한 값이에요. 다만 개별 게시물의 조회 수와 반응 수는 텔레그램 공개 화면에서 유효숫자 세 자리로 반올림돼서, 실제 931,193회가 931,000회로 보입니다. 시간 단위 증감 추적보다는 순위 비교에 쓰시는 편이 맞아요.
채널 기록 전체는 어떻게 넘겨보나요?
응답에 담긴 커서를 다음 호출에 넘기고, 커서가 비어 돌아올 때까지 반복하시면 됩니다. 사진 묶음이 한 건으로 세어지고 시스템 메시지는 빠지기 때문에 페이지 크기가 들쭉날쭉해요. 짧은 페이지가 끝을 뜻하지는 않습니다. 게시물 546건짜리 채널을 끝까지 넘겨보니 24페이지에 426건이 중복 없이 나왔어요.
텔레그램 API 요금은 어떻게 되나요?
텔레그램 엔드포인트 4개 모두 호출당 1 credit입니다. 캐시된 응답과 존재하지 않는 채널 조회는 과금되지 않고, 새 계정에는 크레딧 100개가 들어 있어서 결제 전에 전체를 먼저 시험해 보실 수 있어요.
Telegram 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Telegram 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Telegram 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
Telegram 스크래핑 API와 공식 Telegram API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Telegram 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.
AI에게 SocialCrawl을 물어보세요