Telegram Post
Publora MCP 서버를 사용하여 텔레그램 채널 및 그룹에 게시물을 생성하고 예약합니다. 다양한 마크다운 서식, 사진, 동영상 및 메시지 전송 옵션을 지원합니다.
필수 조건
요금제: 무료 Starter 플랜에서 사용 가능합니다. 현재 제한 및 가격: publora.com/pricing
시작하기
- publora.com/register에서 계정 생성 (무료)
- 텔레그램 봇 생성:
- 텔레그램에서 @BotFather에게 메시지 보내기
/newbot명령어를 보내고 안내에 따르기- 봇 토큰 저장하기
- 채널에 봇 추가:
- 채널/그룹에 봇을 관리자로 추가
can_post_messages권한 부여
- Publora에 연결: 대시보드에서 봇 토큰과 채널 이름 입력
- API 키 발급: app.publora.com/dashboard/api에서 API 키 생성
- 에이전트를 MCP 서버에 연결:
https://mcp.publora.com에Authorization: Bearer sk_YOUR_API_KEY로 인증. Claude Code에서는:
claude mcp add publora --transport http https://mcp.publora.com \
--header "Authorization: Bearer sk_YOUR_API_KEY"
Claude Desktop, Cursor, Codex, OpenClaw 및 claude.ai 커넥터는 각각 다른 설정 파일이나 흐름이 필요합니다. 자세한 경로와 코드 조각은 클라이언트 설정을 참고하세요.
REST API 대체 수단
MCP 서버를 사용할 수 없거나 오류가 발생하는 경우 REST API를 직접 사용하세요:
기본 URL: https://api.publora.com/api/v1
인증: x-publora-key 헤더 사용 (Authorization: Bearer 사용 금지):
# 연결된 플랫폼 조회
curl -X GET "https://api.publora.com/api/v1/platform-connections" \
-H "x-publora-key: sk_your_api_key"
# 게시물 생성
curl -X POST "https://api.publora.com/api/v1/create-post" \
-H "x-publora-key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"platforms": ["telegram-1001234567890"],
"content": "*공지사항*\n\n여기에 메시지를 입력하세요",
"scheduledTime": "2026-03-25T10:00:00Z"
}'
플랫폼 ID 형식: telegram-{chat_id}, 여기서 {chat_id}는 /platform-connections에서 확인한 채널/그룹 숫자 ID입니다.
예시 ID: telegram-1001234567890, telegram--1002345678901
📖 전체 API 문서: docs.publora.com
플랫폼 제한 (봇 API)
| 기능 | 제한 |
|---|---|
| 텍스트 메시지 | 4,096자 |
| 미디어 캡션 | 1,024자 (매우 중요한 제한!) |
| 이미지 | 최대 10MB, 미디어 그룹당 10개 |
| 이미지 형식 | JPEG, PNG, GIF, BMP, WebP |
| 동영상 크기 | 최대 50MB (4GB가 아닙니다 - 일반 사용자용!) |
| 동영상 형식 | MP4, MOV, AVI, MKV, WebM |
| 속도 제한 | 전역 30메시지/초, 그룹당 20메시지/분 |
중요: 봇 API는 일반 텔레그램 사용자보다 제한이 훨씬 낮습니다. 50MB를 초과하는 동영상과 1,024자를 초과하는 캡션은 실패합니다.
마크다운 서식
텔레그램은 자체 마크다운 형식을 사용하며, 굵게 표시에 단일 별표를 사용합니다:
| 구문 | 결과 |
|---|---|
*굵게* | 굵게 |
_기울임_ | 기울임 |
`코드` | 인라인 코드 |
코드 | 코드 블록 |
[텍스트](url) | 하이퍼링크 |
> 텍스트 | 인용 블록 |
참고: 표준 마크다운에서는 **이중 별표**가 굵게 표시되지만, 텔레그램은 다릅니다.
사용 가능한 도구
create_post
새 텔레그램 게시물을 생성합니다.
매개변수:
platforms: 텔레그램 연결 ID 배열 (예:["telegram-1001234567890"])content: 메시지 텍스트 (마크다운 지원)scheduledTime: ISO 8601 UTC 날짜/시간. 선택 사항: 생략하면 게시물이 초안으로 생성됩니다. 미래 시간을 보내면 예약됩니다. 5분 이상 과거 시간은SCHEDULED_TIME_IN_PAST오류로 거부되므로, 즉시 게시하려면 현재 시간에 1분을 더한 값을 사용하세요.mediaUrls: 최대 10개의 공개 https 이미지 또는 동영상 URL. Publora가 서버 측에서 다운로드하여 유효성 검사 전에 첨부하므로, 미디어와 예약을 한 번에 처리할 수 있습니다. 이는 초안 작성 후get_upload_url→complete_media흐름을 대체하는 원샷 방식입니다. 수집 속도는 시간당 60개 URL로 제한됩니다.
get_upload_url
미디어 업로드를 위한 사전 서명된 URL을 가져옵니다.
complete_media
사전 서명된 PUT이 성공한 후 get_upload_url을 통해 업로드된 파일을 최종 확정합니다. 선택 사항입니다. 예약 시 대기 중인 미디어도 최종 확정되지만, 게시 전에 형식 및 프로브 오류를 조기에 확인하려면 이 도구를 호출하는 것이 좋습니다. mediaUrls로 첨부된 미디어에는 필요하지 않습니다.
매개변수:
mediaId:get_upload_url이 반환한 ID
list_connections
연결된 계정과 플랫폼 ID를 나열합니다. 항상 먼저 호출하고 ID를 그대로 복사하세요. ID는 절대 추측할 수 없습니다.
list_posts / get_post / update_post / delete_post
예약된 게시물 및 초안을 관리합니다. update_post는 초안 또는 예약된 게시물의 content와 platforms도 수정하므로, 오타 수정이나 대상 변경 시 삭제 후 재생성할 필요가 없습니다. delete_media와 prune_media_reference는 업로드된 파일을 정리합니다.
게시물 옵션 (REST API)
REST API platformSettings.telegram을 통해 사용 가능한 텔레그램 전용 옵션:
| 옵션 | 설명 |
|---|---|
disableNotification | 무음 전송 (소리 없음) |
disableWebPagePreview | 링크 미리보기 카드 없음 |
protectContent | 전달/저장 방지 |
캡션을 미디어 위에 표시하는 것은 설정할 수 없습니다: showCaptionAboveMedia는 허용된 키가 아니며, 보내면 400 PLATFORM_SETTING_UNKNOWN 오류가 반환됩니다.
참고: platformSettings는 MCP의 create_post 및 update_post 도구와 REST에서 모두 허용됩니다. 스키마는 엄격합니다: 잘못 입력된 플랫폼이나 키는 무시되지 않고 유효성 검증 오류와 함께 거부됩니다.
예제
간단한 채널 게시물
내 텔레그램 채널에 다음을 게시해 주세요:
"*제품 업데이트 v2.5*
다음과 같은 개선 사항이 출시되었습니다:
- _더 빠른 API 응답 시간_ (평균 45ms)
- 대량 작업을 위한 새 `batch` 엔드포인트
[변경 로그 읽기](https://example.com/changelog)"
서식이 있는 공지
다음 형식으로 텔레그램 게시물을 작성해 주세요:
"*중요 업데이트*
내일 오전 10시 UTC에 새로운 기능을 출시합니다.
_새로운 기능:_
- 기능 A 개선
- 기능 B 출시
[전체 공지 읽기](https://example.com/update)"
이미지와 함께 게시
내 텔레그램 채널에 이 이미지를 다음 캡션과 함께 게시해 주세요:
"*새로운 대시보드 미리보기*
재설계된 분석 대시보드의 미리보기입니다."
중요: 미디어와 함께 게시할 때 캡션은 1,024자 미만이어야 합니다.
예약 게시물
내일 모스크바 시간 오전 8시에 이것을 예약해 주세요:
"*좋은 아침입니다!* 오늘의 시장 요약입니다..."
중요 제한 사항
-
캡션 제한 1,024자: 미디어(이미지/동영상)와 함께 게시할 때 텍스트는 1,024자로 제한된 캡션으로 전송됩니다. 텍스트 전용 메시지는 4,096자까지 가능합니다.
-
동영상 최대 50MB: 봇 API는 동영상을 50MB로 제한합니다 (일반 사용자의 4GB와 다릅니다). 대용량 동영상은 실패합니다.
-
봇은 관리자여야 함: 봇에
can_post_messages권한이 있는 관리자 역할이 필요합니다. 연결 시 확인됩니다. -
혼합 미디어 불가: 하나의 게시물에 이미지와 동영상을 동시에 포함할 수 없습니다.
-
캡션 초과: 미디어 게시물에서 캡션이 1,024자를 초과하면 잘리지 않고 별도의 답글 메시지로 전송됩니다.
모범 사례
콘텐츠
- 서식 사용: 굵은 제목, 기울임 강조로 가독성 향상
- 링크 미리보기: 기사에 유용하며, 깔끔한 공지에는 비활성화
- 이모지 사용: 텔레그램에서 일반적이고 기대되는 요소
- 게시물 길이: 텍스트 전용 메시지에는 긴 게시물에 불이익 없음
타이밍
- 글로벌 사용자: 텔레그램 사용자는 전 세계에 있으므로 시간대 고려
- 최적 시간: 대상 지역의 오전 8-10시, 오후 12-2시, 오후 7-9시
- 빈도: 채널은 더 자주 게시 가능 (하루 5-10회)
참여
- 토론을 위해 채널 설정에서 댓글 활성화
- 참여 유도를 위해 투표 사용
- 중요한 공지는 고정
문제 해결
| 오류 | 원인 | 해결책 |
|---|---|---|
| "봇이 관리자가 아님" | 봇에 관리자 권한 없음 | can_post_messages 권한으로 봇을 관리자로 추가 |
| "채널을 찾을 수 없음" | 잘못된 채널 이름/ID | @채널명 또는 숫자 채팅 ID 확인 |
MEDIA_CAPTION_TOO_LONG | 캡션이 1,024자 초과 | 캡션 단축 또는 텍스트 전용 게시물 사용 |
| "Bad Request: 파일이 너무 큼" | 파일이 50MB 초과 | 동영상/이미지를 50MB 미만으로 압축 |
| "혼합 미디어 지원 안 함" | 동일 게시물에 이미지+동영상 | 게시물당 하나의 미디어 유형 사용 |