본문으로 건너뛰기

캠페인

캠페인(발송)의 진행 상태와 성공·실패 건수를 읽는 조회 API입니다. 삭제되지 않은 캠페인만 반환하며, 메시지 본문과 타깃·A/B 설정은 응답에 포함하지 않습니다.

목록 조회​

GET /campaigns — 캠페인 목록을 cursor pagination으로 조회합니다.

  • Scope: campaigns:read
  • 쿼리: limit(기본 50, 최대 100), cursor

최신 캠페인부터(created_at 내림차순) 반환하고, 상태 필터는 없습니다. 특정 상태만 필요하면 응답의 status로 직접 거르세요.

curl "https://api.talk.zeroworks.ai/api/public/v1/campaigns?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "c1a2b3d4-...",
      "name": "5월 신규 가입 안내",
      "status": "completed",
      "campaign_type": "chat",
      "trigger_type": "scheduled",
      "scheduled_at": "2026-05-01T09:00:00Z",
      "started_at": "2026-05-01T09:00:03Z",
      "completed_at": "2026-05-01T09:04:21Z",
      "sent_count": 1280,
      "failed_count": 4,
      "created_at": "2026-04-28T11:00:00Z",
      "updated_at": "2026-05-01T09:04:21Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

응답 필드

필드타입설명
idstring캠페인 UUID
namestring캠페인 이름
statusstring발송 진행 단계. draft | scheduled | sending | completed | canceled
campaign_typestring발송 유형. popup | chat | email (기본 chat)
trigger_typestring발송 시점을 정하는 방식. immediate | scheduled | event
scheduled_atstring예약 시각(RFC3339). 값이 없으면 키가 생략됩니다.
started_atstring발송을 시작한 시각(RFC3339). 시작 전에는 키가 생략됩니다.
completed_atstring발송을 마친 시각(RFC3339). 끝나기 전에는 키가 생략됩니다.
sent_countinteger발송한 건수
failed_countinteger발송에 실패한 건수
created_atstring생성 시각(RFC3339)
updated_atstring마지막 수정 시각(RFC3339)

scheduled_at·started_at·completed_at은 값이 없으면 null이 아니라 키 자체가 생략됩니다. "key" in obj로 존재 여부를 판별하세요.

단건 조회​

GET /campaigns/{id} — 캠페인 하나를 조회합니다. {id}는 캠페인 UUID입니다.

  • Scope: campaigns:read
curl "https://api.talk.zeroworks.ai/api/public/v1/campaigns/c1a2b3d4-..." \
  -H "Authorization: Bearer ztpat_..."

응답 — data에 목록 조회와 같은 필드의 캠페인 객체 하나가 들어 있습니다.

{
  "success": true,
  "data": {
    "id": "c1a2b3d4-...",
    "name": "5월 신규 가입 안내",
    "status": "completed",
    "campaign_type": "chat",
    "trigger_type": "scheduled",
    "scheduled_at": "2026-05-01T09:00:00Z",
    "started_at": "2026-05-01T09:00:03Z",
    "completed_at": "2026-05-01T09:04:21Z",
    "sent_count": 1280,
    "failed_count": 4,
    "created_at": "2026-04-28T11:00:00Z",
    "updated_at": "2026-05-01T09:04:21Z"
  }
}

오류​

HTTPcode발생 조건
400INVALID_QUERYlimit이 1~100 범위를 벗어남(값을 보정하지 않습니다), 또는 cursor가 만료되었거나 형식이 틀림
400INVALID_INPUT{id}가 UUID 형식이 아님
404NOT_FOUND캠페인이 없거나 이 워크스페이스에 속하지 않음, 또는 삭제됨

공통 오류는 에러 문서를 참고하세요.