MINARALINE
LINE Messaging API를 통한 아웃바운드 푸시 메시징 및 서명된 webhook 이벤트. 일본과 대만 운영자에게 널리 사용됩니다.
🟡 아웃바운드 준비 완료, 푸시 전용. Minara는 LINE의 푸시 API를 사용합니다（월별 과금）. 응답 token（무료）은 아직 연결되지 않아 모든 아웃바운드 메시지가 플랜 할당량에 포함됩니다. 인바운드 webhook 이벤트는 HMAC-SHA256 서명 검증과 함께 완전히 지원됩니다.
제공 기능
POST /v2/bot/message/push를 통한 푸시 메시징. userId, groupId, roomId로 전송 가능합니다.X-Line-SignatureHMAC-SHA256 서명이 적용된 인바운드 webhook (/webhooks/line). LINE의 공식 방식에 따라 원시 본문을 검증합니다.- 현재는 텍스트만 지원합니다. 첨부 파일（이미지, 스티커, 동영상）은 향후 지원될 예정입니다.
- 텍스트 메시지당 5000자 제한.
send_message는 도구 경계에서 초과 텍스트를 잘라냅니다.
설정
1. LINE 채널 생성
- LINE Developers Console로 이동합니다.
- Provider를 생성한 후, 그 안에 Messaging API 채널을 만듭니다.
- 채널 페이지에서 Channel access token（장기 유효, 비어 있으면 "Issue" 클릭）과 Channel secret을 복사합니다.
2. 사용자 / 그룹 ID 확인
사용자가 봇을 추가하면 webhook이 follow 이벤트와 함께 해당 사용자의 userId（불투명한 U... 문자열）를 수신합니다. 그룹의 경우, 그룹에 메시지를 보낸 후 인바운드 페이로드에서 groupId를 읽어옵니다. 모든 연락처를 조회하는 셀프 서비스 방법은 없으며, 첫 번째 상호작용 시 ID를 직접 캡처해야 합니다.
3. Minara 설정
가장 빠른 방법은 대화형 메뉴를 사용하는 것입니다.
minara auth messaging add
# 목록에서 `line`을 선택하고, 프롬프트에 따라 access token + channel secret +
# 기본 userId / groupId를 입력합니다.또는 프로젝트 루트의 .env 파일에 환경 변수를 직접 설정합니다.
LINE_CHANNEL_ACCESS_TOKEN=<long-lived bearer token>
LINE_CHANNEL_SECRET=<signing key>
LINE_DEFAULT_USER_ID=<default Uxxxxxxxxxxxxxx>4. 테스트
minara auth messaging test line봇 계정에 "✅ Minara gateway test ping"이 1초 이내에 수신되어야 합니다.
인바운드 webhook
LINE 채널이 다음 주소로 이벤트를 POST하도록 설정합니다.
https://<your-host>/webhooks/lineLINE은 LINE_CHANNEL_SECRET을 사용하여 원시 바이트에 대해 HMAC-SHA256으로 모든 webhook 본문에 서명하며, 이는 X-Line-Signature 헤더에 담겨 전달됩니다. Minara는 본문을 파싱하기 전에 서명을 검증하므로, 변조된 POST 요청은 401을 반환하고 Agent로 전달되지 않습니다.
현재 인바운드에서 처리하는 webhook 이벤트 유형은 message.type === "text"인 message입니다. 그 외 유형（스티커, 미디어, follow / unfollow 이벤트）은 무시됩니다.
제한 사항 및 주의 사항
- 푸시 API는 월별 과금입니다. 개발자 체험 등급의 무료 플랜은 푸시를 월 500건으로 제한하며, 유료 플랜은 더 높은 한도를 제공합니다. 프로덕션 알림에는 절약하여 사용하십시오.
- 응답 token은 무료이지만 아직 연결되지 않았습니다. 향후 Minara가
replyToken（인바운드 메시지 수신 후 30초 이내）을 통해 응답하여 푸시 할당량을 소비하지 않도록 지원할 예정입니다. - 5000자 텍스트 제한. 초과 텍스트는 잘립니다.
문제 해결
"테스트 메시지가 도착하지 않음"
- 수신 계정에서 봇이 친구로 추가되었는지（또는 그룹에 속해 있는지）확인합니다.
LINE_DEFAULT_USER_ID형식을 확인합니다. 앞의U문자가 필요합니다.~/.minara/logs/에서api.line.me의 HTTP 4xx 응답을 확인합니다.
"인바운드 webhook이 401을 반환함"
- 환경 변수의
LINE_CHANNEL_SECRET값이 LINE 콘솔의 channel secret과 일치하지 않습니다. - 서명 헤더는 원시 본문을 기준으로 계산됩니다. 역방향 프록시나 CDN이 바이트를 수정하지 않는지 확인하십시오.
"푸시 API가 429를 반환함"
- 월별 푸시 할당량을 소진했습니다. 플랜을 업그레이드하거나, 알림 외 메시지에는 응답 token으로 전환하십시오.