CollabOps

채널 읽기

수신 웹훅의 URL 과 시크릿으로 그 채널의 메시지를 읽는 방법 — 허용, 요청, 응답, 페이지 넘기기, 오류

수신 웹훅으로 메시지를 보내는 외부 도구는 같은 URL 과 시크릿으로 그 채널의 메시지를 읽어 갈 수도 있습니다. 배포 스크립트가 채널에 남은 승인 답글을 확인하거나, 에이전트가 최근 대화를 읽고 요약하는 식으로 씁니다. 읽기는 웹훅마다 따로 허용해야 합니다. 보내는 방법은 수신 웹훅에 있습니다.

읽기 허용 켜기

발급할 때 채널 대화 읽기 허용을 켜거나, 이미 만든 웹훅이면 웹훅 관리하기 창의 ⋯ 메뉴에서 켭니다. 채널 관리자만 바꿀 수 있습니다. 끄면 그 즉시 읽기가 막히고, 보내기와 URL·시크릿은 그대로입니다.

읽기를 허용하면 시크릿 하나로 그 채널의 대화를 읽을 수 있습니다. 알림을 보내기만 하는 도구에는 켜지 마세요. 시크릿이 샜다면 웹훅을 삭제하고 새로 발급합니다.

요청 형식

항목값필수
메서드GET예
주소https://collabops.ai/api/v2/integration/webhook/<토큰>/messages예
Authorization 헤더Bearer <시크릿> (보낼 때와 같은 값)예

쿼리

이름필수설명
since예이 시각부터 읽습니다 (포함). 시간대를 붙인 ISO 8601 시각이나 unix 초.
until아니오이 시각 전까지 읽습니다 (제외). 생략하면 지금입니다. since 와의 간격은 7일까지입니다.
limit아니오한 번에 받을 메시지 수. 1~100.
after아니오다음 쪽을 받을 때 직전 응답의 next_after_cursor 값.
curl -G "https://collabops.ai/api/v2/integration/webhook/<토큰>/messages" \
  -H "Authorization: Bearer <시크릿>" \
  --data-urlencode "since=2026-10-12T09:00:00+09:00" \
  --data-urlencode "limit=50"

시각의 +09:00 에 든 + 는 쿼리 문자열에서 공백으로 읽힙니다. 위처럼 --data-urlencode 로 보내거나 %2B 로 적으세요. unix 초로 쓰면 이 문제가 없습니다.

응답

200 과 함께 채널의 메시지 목록이 옵니다. 스레드 답글은 목록에 나오지 않고, 원글의 reply_count 로 개수만 보입니다. 읽어도 읽음 표시는 남지 않습니다.

{
  "messages": [
    {
      "id": "01a12efa-1da6-75f1-b4e2-6d3349b44b8e",
      "parent_message_id": null,
      "type": "user",
      "created_at": "2026-10-12T07:18:25.958881Z",
      "edited_at": null,
      "deleted_at": null,
      "reply_count": 1,
      "blocks": [
        {
          "id": "054968bf-26fa-490e-968e-49f29f85bb44",
          "type": "paragraph",
          "parentId": null,
          "attrs": null,
          "children": [{"text": "야간 배치 시작", "marks": [{"type": "bold"}]}]
        }
      ],
      "author": {
        "user_id": "37b6a1ef-35c3-454b-b610-929e5fc99384",
        "full_name": "배포 알림",
        "email": "37b6a1ef-35c3-454b-b610-929e5fc99384@hooks.collabops.bot"
      }
    }
  ],
  "has_more": true,
  "next_after_cursor": "01a12efa-1da6-75f1-b4e2-6d3349b44b8e"
}
필드설명
messages메시지 배열. 쪽은 오래된 범위부터 차례로 넘어가지만 한 쪽 안의 순서는 정해져 있지 않으므로 created_at 으로 정렬해 쓰세요.
has_more같은 범위에 메시지가 더 있으면 true.
next_after_cursor다음 쪽을 받을 때 after 로 넘길 값. 더 없으면 null.

메시지 하나

필드설명
id메시지 ID.
parent_message_id스레드 답글이면 원글의 메시지 ID. 지금은 답글이 목록에 나오지 않아 늘 null 입니다.
typeuser 는 사람·봇이 쓴 글, system 은 멤버 추가 같은 안내입니다. system 은 blocks 가 null 입니다. 값이 늘어날 수 있으니 모르는 값은 건너뛰세요.
created_at · edited_at쓴 시각과 마지막으로 고친 시각 (UTC).
deleted_at삭제된 메시지면 삭제 시각. 이때 blocks 는 null 입니다.
reply_count스레드 답글 수.
blocks본문. 수신 웹훅의 blocks 형식과 같은 모양이고, 값이 없는 칸은 null 로 옵니다. 받은 그대로 다시 보낼 수 있습니다. 모양은 표현 레퍼런스에 있습니다.
author쓴 사람의 user_id · full_name · email. 웹훅이 쓴 글은 웹훅 이름과 봇 전용 주소가 옵니다. 찾지 못하면 null.

리액션과 첨부 파일은 싣지 않습니다.

다음 쪽 받기

has_more 가 true 면 같은 since · until 에 next_after_cursor 를 after 로 더해 다시 부릅니다. until 을 생략하면 부를 때마다 "지금" 이 바뀌므로, 여러 쪽을 받을 때는 첫 요청부터 until 을 적어 범위를 고정하세요.

# 첫 쪽 — 범위를 고정해 둔다
SINCE="2026-10-12T09:00:00+09:00"
UNTIL="2026-10-12T18:00:00+09:00"
curl -sS -G "https://collabops.ai/api/v2/integration/webhook/<토큰>/messages" -H "Authorization: Bearer <시크릿>" \
  --data-urlencode "since=$SINCE" --data-urlencode "until=$UNTIL" > page1.json

# 다음 쪽 — 같은 since·until 에 after 만 더한다
AFTER=$(sed -n 's/.*"next_after_cursor":"\([^"]*\)".*/\1/p' page1.json)
curl -sS -G "https://collabops.ai/api/v2/integration/webhook/<토큰>/messages" -H "Authorization: Bearer <시크릿>" \
  --data-urlencode "since=$SINCE" --data-urlencode "until=$UNTIL" \
  --data-urlencode "after=$AFTER" > page2.json

7일보다 긴 기간은 7일씩 끊어서 차례로 읽습니다.

오류 응답

오류 본문은 보낼 때와 같은 모양입니다 (수신 웹훅 — 오류 응답). error.title 의 사유로 원인을 가립니다.

상태언제어떻게 하나
401시크릿이 틀렸거나, 웹훅이 꺼져 있거나, 읽기 허용이 꺼져 있을 때. 읽기 허용이 꺼져 있으면 error.title 이 read not allowed 로 끝납니다.시크릿을 고치거나 웹훅·읽기 허용을 켭니다.
403웹훅의 채널을 읽을 수 없을 때 (채널이 삭제된 경우 등)채널 상태를 확인합니다.
404URL 의 토큰에 해당하는 웹훅이 없을 때새로 발급한 URL 로 부릅니다.
422since 가 없거나 형식이 틀렸을 때, since 가 until 보다 늦을 때, 간격이 7일을 넘을 때, limit 이 1~100 밖일 때쿼리를 고칩니다.
429웹훅 하나에 분당 10회를 넘었을 때. 보내기 한도(분당 60회)와 따로 셉니다.Retry-After 헤더의 초만큼 기다린 뒤 부릅니다.
503 · 502 · 504일시적인 내부 오류나 응답 지연잠시 뒤 다시 부릅니다.

읽기 요청은 전송 기록에 남지 않습니다.

목차

읽기 허용 켜기요청 형식쿼리응답메시지 하나다음 쪽 받기오류 응답