본문으로 건너뛰기

페이지네이션

목록을 반환하는 엔드포인트는 cursor 기반 pagination을 사용합니다. 첫 페이지를 요청하고, 응답의 meta.next_cursor를 다음 요청의 cursor로 넘겨 마지막 페이지까지 이어서 읽습니다.

웹훅 전달 로그(GET /outbound-webhooks/{id}/delivery-logs)만 예외로 offset 기반이며, offset은 0~9,999입니다 — 전달 로그를 참고하세요.

파라미터​

파라미터설명
limit페이지 크기. 기본 50, 최소 1, 최대 100
cursor이전 응답의 meta.next_cursor 값. 내용을 해석하지 말고 받은 값 그대로 보내세요.

limit이 1~100 범위를 벗어나거나 정수가 아니면 값을 보정하지 않고 400 INVALID_QUERY를 반환합니다.

응답 meta​

{ "has_more": true, "next_cursor": "eyJ..." }

meta는 한 방향으로만 넘어갑니다. 다음 페이지로 가는 next_cursor만 제공하고, 이전 페이지로 돌아가는 cursor는 없습니다. has_more가 false이면 마지막 페이지이고 next_cursor는 생략됩니다.

아래 명령은 첫 페이지를 읽은 다음, 응답의 meta.next_cursor로 다음 페이지를 읽습니다.

# 첫 페이지
curl "https://api.talk.zeroworks.ai/api/public/v1/contacts?limit=50" -H "Authorization: Bearer ztpat_..."
# 응답의 meta.next_cursor로 다음 페이지
curl "https://api.talk.zeroworks.ai/api/public/v1/contacts?limit=50&cursor=eyJ..." -H "Authorization: Bearer ztpat_..."

cursor는 목록에서의 위치만 담고 조회 조건은 담지 않습니다. q, tags, tag_match처럼 조건을 넘기는 목록은 다음 페이지를 요청할 때도 같은 조건을 다시 보내야 합니다. 조건을 빼면 조건이 풀린 전체 목록이 이어집니다.

페이지네이션이 없는 목록도 있습니다. 연락처 태그(GET /contacts/{id}/tags)와 워크플로(GET /workflows)는 전체를 한 번에 반환하고 meta를 포함하지 않습니다.

Cursor 만료​

cursor 만료 정책은 종류에 따라 다릅니다.

  • 연락처·채널 등 keyset cursor: 발급 후 24시간 동안 유효합니다. 만료되었거나 형식이 틀린 cursor를 보내면 400 INVALID_QUERY를 반환하며, 이때는 첫 페이지부터 다시 조회해야 합니다.
  • 메시지 cursor: 내부 저장소(DynamoDB)의 토큰을 그대로 쓰므로 만료가 없습니다.

메시지 전용 제약​

메시지 목록(GET /channels/{id}/messages)은 시간 범위를 반드시 지정해야 합니다.

  • since (RFC3339): 필수
  • until (RFC3339): 선택, 기본값은 현재 시각이며 since보다 뒤여야 합니다.
  • until - since는 30일 이내여야 합니다.

since가 없거나, 형식이 틀리거나, until이 since보다 뒤가 아니거나, 범위가 30일을 넘으면 400 INVALID_QUERY를 반환합니다. 30일보다 오래된 메시지까지 읽으려면 since를 앞으로 옮겨 가며 여러 번 조회하세요.

검색​

검색(GET /search)은 cursor 없이 한 페이지(최대 100건)만 반환합니다.