TelegramTelegram 채널채널 스크래퍼API 가이드

Telegram 채널 API: 채널 정보, 게시물, 댓글, 검색

공개 Telegram 채널을 위한 SocQ 신규 엔드포인트 6종을 소개합니다. 채널 정보, 게시물 피드, 개별 게시물, 토론 댓글, 유사 채널, 채널 내 검색의 요청 방법과 결과당 가격을 정리했습니다.

SocQ2026년 11월 19일 업데이트약 7분 소요

SocQ는 2026-11-17에 공개 Telegram 채널을 위한 엔드포인트 6개와 함께 Telegram 플랫폼을 추가했습니다. 이 엔드포인트들로 리서치 과정 전체를 처리할 수 있습니다. 채널을 검증하고, 피드를 읽고, 특정 게시물을 가져오고, 게시물 아래의 토론을 읽고, 관련 채널을 찾고, 채널의 전체 기록에서 단어를 검색합니다.

이 가이드에서는 각 엔드포인트가 반환하는 데이터, 요청 형식, 비용, 적합한 사용 시점을 정리합니다. 모든 엔드포인트는 공개 t.me 링크로 동작하며 비동기 SocQ 작업으로 실행됩니다.

빠른 답변: 공개 채널 또는 게시물 링크를 Authorization: Bearer $SOCQ_API_KEY와 함께 6개의 POST /v1/telegram/... 엔드포인트 중 하나로 보내세요. 반환된 task_id를 저장하고 status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링한 다음 data.results.items의 레코드를 읽습니다. 모든 엔드포인트는 결과 단위로 과금되며, 행당 0.3 또는 0.5크레딧입니다. 크레딧당 $0.005 기준으로 $0.0015 또는 $0.0025입니다.

새로운 Telegram 엔드포인트 6종

엔드포인트반환 데이터입력가격
Channel Info제목, 설명, 아바타, 인증 배지, 구독자 수채널 링크 최대 50개채널당 0.5크레딧($0.0025)
Channel Scraper최신순 게시물과 텍스트, 시각, 조회수, 반응 합계, 사진, 동영상채널 링크 1개게시물당 0.3크레딧($0.0015)
Post Detail지정한 게시물의 전체 텍스트, 시각, 조회수, 반응, 미디어게시물 링크 최대 50개게시물당 0.5크레딧($0.0025)
Comments연결된 토론 그룹의 댓글 최대 100개와 작성자, 텍스트, 시각, 반응, 답글 대상게시물 링크 1개댓글당 0.3크레딧($0.0015)
Similar ChannelsTelegram이 채널 옆에 추천하는 채널과 사용자 이름, 제목, 배지, 구독자 수채널 링크 1개채널당 0.5크레딧($0.0025)
Channel Search한 채널의 전체 기록 중 단어나 문구와 일치하는 게시물채널 링크 1개 + 검색어일치 게시물당 0.5크레딧($0.0025)

6개 모두 반환된 행에 대해서만 과금되며, 요청당 기본 요금은 없습니다.

Telegram Channel Info: 채널을 대량으로 검증하기

Telegram Channel Info API는 t.me/name 또는 t.me/s/name 링크로 공개 채널을 조회하고 채널마다 한 행을 반환합니다. 이름, 설명, 아바타, 인증 배지, 구독자 수(metrics.followers_count)가 포함됩니다. 스폰서십 전에 채널을 검증하거나, 뉴스·암호화폐 채널 관심 목록을 갱신하거나, 다른 곳에서 수집한 채널 링크를 보강할 때 사용하세요. 원본 결과 파일에는 각 채널이 공유한 사진, 동영상, 링크 수도 들어 있습니다.

curl -X POST "https://api.socq.ai/v1/telegram/channel-info" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://t.me/durov", "https://t.me/tginfo"]
  }'

요청당 최대 50개의 링크를 보낼 수 있습니다. 공개되지 않은 채널의 링크는 건너뛰며, 읽을 수 있는 링크가 하나도 없을 때만 작업이 실패하고 환불됩니다. Channel Info 문서를 참고하세요.

Telegram Channel Scraper: 채널 피드 읽기

Telegram Channel Scraper API는 공개 채널을 최신 게시물부터 거꾸로 읽습니다. 각 게시물에는 텍스트, 게시 시각, 조회수, 이모지 반응과 Star 반응의 합계, 첨부된 사진과 동영상이 함께 제공됩니다. 일일 요약에는 최근 며칠 치를 가져오고, 채널의 과거 기록을 채우려면 한도를 높이세요.

curl -X POST "https://api.socq.ai/v1/telegram/channel-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://t.me/durov",
    "results_limit": 20
  }'

results_limit의 기본값은 20이며 1부터 1,000까지 받습니다. 읽을 수 없는 채널은 작업이 실패하고 환불됩니다. Channel Scraper 문서를 참고하세요.

Telegram Post Detail: 알고 있는 게시물 갱신하기

중요한 게시물을 이미 알고 있다면 Telegram Post Detail API에 링크를 넘기세요. 텍스트, 게시 시각, 조회수, 반응 합계, 사진, 동영상을 포함한 각 게시물의 전체 정보를 반환합니다. 여러 채널의 게시물을 한 요청에 섞어 보낼 수 있어, 추적 중인 공지나 캠페인 게시물의 수치를 갱신하는 데 적합합니다. 원본 결과 파일에는 이모지별 반응 수와 전달 출처가 보존됩니다.

curl -X POST "https://api.socq.ai/v1/telegram/post-detail" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://t.me/durov/510"]
  }'

t.me/channel/post_id 형식의 링크를 최대 50개 보내세요. 삭제된 게시물과 비공개 채널의 게시물은 건너뜁니다. Post Detail 문서를 참고하세요.

Telegram Comments: 게시물 아래의 토론 읽기

토론 그룹을 연결한 채널에서는 독자가 각 게시물 아래에 댓글을 달 수 있습니다. Telegram Comments API는 게시물 하나의 댓글 스레드를 읽고, 각 댓글의 작성자 이름, 텍스트, 시각, 반응 합계, 답글 대상 댓글(parent_id)을 반환합니다. 공지에 커뮤니티가 어떻게 반응했는지 확인하거나, 댓글을 고객 지원이나 리서치 워크플로에 넣을 때 사용하세요.

curl -X POST "https://api.socq.ai/v1/telegram/post-comments" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://t.me/tginfo/4455",
    "results_limit": 100
  }'

results_limit의 기본값은 100이며 이 값이 최대값이기도 합니다. 반환된 댓글에 대해서만 비용을 냅니다. Comments 문서를 참고하세요.

Telegram Similar Channels: 니치 지도 그리기

Telegram은 모든 공개 채널에 관련 채널 목록을 한 줄로 보여 줍니다. Telegram Similar Channels API는 채널 하나에 대한 이 목록을 Telegram이 나열한 순서대로 반환하며, 보통 10개 안팎입니다. 각 채널에는 사용자 이름, 제목, 인증 배지, 구독자 수가 포함됩니다. 경쟁 채널이나 이미 광고 중인 채널에서 시작해 미디어 목록을 넓혀 보세요.

curl -X POST "https://api.socq.ai/v1/telegram/similar-channels" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://t.me/durov"
  }'

Similar Channels 문서를 참고하세요.

Telegram Channel Search: 채널 기록 검색하기

Telegram Channel Search API는 공개 채널의 전체 기록에서 단어나 문구를 검색하고, 일치하는 게시물을 텍스트, 날짜, 조회수, 반응과 함께 반환합니다. 영향력 있는 채널이 특정 프로젝트를 언급한 적이 있는지 확인하거나, 채널이 어떤 출시에 관해 올린 게시물을 모두 모을 때 사용하세요.

curl -X POST "https://api.socq.ai/v1/telegram/channel-search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://t.me/durov",
    "query": "TON",
    "results_limit": 20
  }'

results_limit의 기본값은 20이며 1부터 100까지 받습니다. 일치하는 결과가 없는 검색은 비용이 들지 않습니다. 검색 결과의 사진은 해당 사진이 표시되는 게시물로 연결됩니다. Channel Search 문서를 참고하세요.

인증과 비동기 작업 흐름

모든 요청에는 API 키와 JSON 콘텐츠 유형이 포함됩니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

제출 호출마다 백그라운드 작업이 시작됩니다.

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

제출 응답은 data.task_id와 data.status를 반환합니다. 같은 키로 작업을 폴링하세요.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

작업이 queued, running, failed 상태인 동안에는 응답에 작업 메타데이터만 들어 있으며, failed이면 error_message를 확인하세요. succeeded가 되면 같은 응답의 data.results.items에 정규화된 레코드의 첫 페이지가 포함됩니다. limit의 기본값은 50이고 최대 500까지 지정할 수 있습니다. has_more가 true이면 results.next_cursor를 cursor로 넘겨 다음 페이지를 읽습니다. 더 작은 프로젝션이 필요할 때는 fields에 쉼표로 구분한 필드나 점 경로를 최대 50개까지 지정할 수 있습니다.

클라이언트 쪽 타임아웃은 작업을 취소하지 않습니다. 다시 제출해 중복 비용을 내지 말고 같은 task_id로 조회를 이어가세요. 폴링을 피하려면 제출 본문에 callback_url을 추가하세요. 작업이 끝나면 SocQ가 작업 요약을 담은 POST를 한 번 보내며, 레코드는 작업 엔드포인트에서 읽습니다.

일반적인 작업 비용

  • Channel Info로 채널 50개 검증: 50 × 0.5 = 25크레딧, $0.125.
  • 채널 하나에서 게시물 1,000개 백필: 1,000 × 0.3 = 300크레딧, $1.50.
  • 공지 아래 댓글 100개 읽기: 30크레딧, $0.15.
  • 채널 하나를 검색해 일치 결과 20개 받기: 10크레딧, $0.05.

자주 묻는 질문(FAQ)

비공개 채널이나 그룹에서도 동작하나요?

아니요. 이 엔드포인트들은 t.me 링크로 공개 채널을 읽습니다. Channel Info와 Post Detail은 읽을 수 없는 링크를 건너뛰고, Comments는 공개 채널이 게시물에 연결한 토론 그룹을 읽습니다.

Channel Scraper는 얼마나 과거까지 읽을 수 있나요?

최신순으로 읽으며, results_limit은 요청당 최대 1,000개의 게시물을 받습니다. 특정 주제의 오래된 게시물을 찾으려면 채널의 전체 기록을 대상으로 하는 Channel Search를 사용하세요.

반응 수에는 무엇이 포함되나요?

채널 게시물의 metrics.likes_count에는 이모지 반응과 Star 반응의 합계가 들어 있습니다. Post Detail의 원본 결과 파일에는 이모지별 반응 수가 보존됩니다.

찾지 못한 채널이나 게시물에도 비용을 내나요?

아니요. 반환된 행 단위로 과금되며 기본 요금은 없습니다. 일치 결과가 없는 Channel Search는 비용이 들지 않고, 링크를 하나도 읽지 못한 작업은 실패하며 환불됩니다.

추적할 새 채널은 어떻게 찾나요?

알고 있는 채널 하나에서 시작해 Similar Channels를 호출한 다음, 반환된 링크를 Channel Info에 넘겨 구독자 수를 비교하세요. 모든 엔드포인트는 Telegram 플랫폼 페이지에서, 현재 요금은 요금 페이지에서 확인할 수 있습니다.

TELEGRAM API

공개 Telegram URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

Telegram API 살펴보기