보관한 기록을,
내 서비스와 연결하세요
필요한 대화는 API로 조회하고,
새로운 기록은 Webhook으로 확인하세요.
빠르게 시작하기
- 01
API 키 만들기
계정 설정에서 연동에 사용할 키를 만드세요.
- 02
인증 헤더 보내기
요청에 Bearer API 키를 포함하세요.
- 03
기록 조회하기
대화를 조회하고 필요한 첨부를 다운로드하세요.
curl -H "Authorization: Bearer YOUR_API_KEY" "https://messeum.moram.net/api/v1/messages?limit=100"인증과 접근 권한
계정 설정에서 키를 만들고 Authorization: Bearer YOUR_API_KEY헤더를 전송하세요. 로그인 비밀번호와 수집기 토큰은 사용할 수 없습니다.
데이터는 서버에서 복호화됩니다. 연동 프로그램의 접근 권한과 보관 책임을 확인하세요.
대화 조회
/api/v1/messagesread:messages권한이 필요합니다. limit은 1~100입니다. conversation, channel, q로 검색합니다.
| 매개변수 | 값 | 용도 |
|---|---|---|
limit | 1~100 | 한 번에 조회할 대화 수 |
conversation | 대화 식별자 | 대화별 조회 |
channel | 채널 | 채널별 조회 |
q | 검색어 | 대화 검색 |
before | nextCursor.sentAt | 다음 페이지의 기준 시각 |
beforeId | nextCursor.id | 다음 페이지의 기준 ID |
cursorRevision | nextCursor.revision | 조회 중 대화 변경 확인 |
다음 페이지 조회
hasMore가 true이면 nextCursor.sentAt을 before, nextCursor.id를 beforeId, nextCursor.revision을 cursorRevision으로 전송합니다.
ARCHIVE_CURSOR_STALE (409)이면 첫 페이지부터 다시 조회하세요.
첨부 다운로드
/api/v1/attachments/{id}첨부 식별자는 대화 조회 응답에서 확인합니다. read:attachments권한이 필요합니다.
GET /api/v1/attachments/{id}한도와 오류
계정 전체 요청 한도
분당 요청 한도
월 한도는 UTC 기준 매월 초기화됩니다. 한도 초과 시 Retry-After헤더를 확인하세요.
| 상태 코드 | 의미와 대응 |
|---|---|
401 | 잘못되거나 폐기·만료된 키 |
403 | 이용 기간 또는 권한 부족 |
404 | 본인 첨부 없음 |
409 | ARCHIVE_CURSOR_STALE · 첫 페이지부터 다시 조회 |
429 | 한도 초과 · Retry-After 헤더 확인 |
새로운 기록을 알림으로
계정에서 HTTPS 수신 URL을 등록하세요. 일반 새 기록 알림(archive.messages.created)의 본문은 id, type (archive.messages.created), createdAt, messageCount만 제공합니다. 이벤트 ID로 중복을 제거하고 필요할 때 API로 내용을 조회하세요.
HMAC-SHA256(secret, timestamp + "." + eventId + "." + rawBody)서명 검증 순서
X-Messeum-Timestamp가 현재 시각에서 5분 이내인지 확인한 후, 등록 시 받은 비밀키로 HMAC-SHA256(timestamp + "." + eventId + "." + 원본 요청 본문)을 계산해 X-Messeum-Signature의 sha256=뒤 값과 상수 시간 비교하세요.
X-Messeum-Event-Id도 서명에 사용합니다. JSON을 다시 직렬화하면 서명이 달라집니다.
재시도와 중복 처리
2xx 응답이 성공입니다. 실패 시 지수 간격으로 최대 8회 시도하며, 동일 이벤트가 여러 번 도착할 수 있습니다.
수신 URL당 대기 1,000개를 넘으면 변경 알림을 합산하며 archive.changed·coalesced·resyncRequired가 포함됩니다. 합산 건수는 변경량 안내이며 본문은 API로 다시 동기화하세요.
전송과 보관 시 알아둘 점
수집 데이터 저장은 알림 장애로 중단하지 않으므로, 알림 누락 가능성을 대비해 정기적으로 API를 조회하세요. 성공·재시도 종료 후 30일이 지난 처리 기록을 정기 정리합니다.
리다이렉트와 내부망 주소는 지원하지 않습니다. 프리미엄 기간이 끝나면 전송하지 않습니다.