본문으로 건너뛰기

연동

워크스페이스에 연결된 채널 연동의 목록과 상태를 읽는 조회 API입니다. 연동을 추가하거나 바꾸려면 대시보드를 사용하세요.

목록 조회​

GET /integrations — 채널 연동(Kakao/Naver/LINE/email 등) 목록을 cursor pagination으로 조회합니다.

  • Scope: integrations:read
  • 쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
  • 최신순(created_at 내림차순)으로 정렬됩니다.

범위를 벗어난 limit은 자동 보정 없이 400 INVALID_QUERY로 거부합니다. 발급 후 24시간이 지난 cursor도 같은 오류를 반환합니다. 자세한 규칙은 페이지네이션을 참고하세요.

음성 기능이 꺼진 워크스페이스에서는 voice 연동이 목록에서 제외됩니다. 대시보드의 연동 목록과 같은 기준입니다.

아래 요청은 연동 50건을 조회합니다.

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

응답

{
  "success": true,
  "data": [
    {
      "id": "e1f2a3b4-...",
      "provider": "kakao",
      "name": "카카오 상담톡",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

필드​

필드타입설명
idstring연동 UUID
providerstring연동 공급사 (아래 provider 값 참조)
namestring사용자가 지정한 연동 이름
statusstring연동 상태 (아래 값 집합 참조)
created_at·updated_atstringRFC 3339 시각

값 집합​

필드값 집합
statusactive · inactive · error · pending · awaiting_setup · awaiting_activation

완전히 연결되어 사용할 수 있는 상태는 active뿐입니다. 나머지 값은 설정 대기·비활성·오류 등을 나타냅니다.

provider 값​

응답에 나올 수 있는 provider 값과 각 값의 연동이 생기는 경로입니다. 워크스페이스에서 실제로 받는 값은 그 워크스페이스가 연결한 채널에 따라 다릅니다. 표의 「서비스 연동」은 대시보드 연동 설정에서 「연동 추가」를 누르면 열리는 창입니다.

값생기는 경로·조건
web대시보드의 「서비스 연동」에서 「웹사이트」를 연결할 때
kakao대시보드의 「서비스 연동」에서 「카카오톡」을 연결할 때
naver대시보드의 「서비스 연동」에서 「네이버 톡톡」을 연결할 때
line대시보드의 「서비스 연동」에서 「라인」을 연결할 때
email대시보드의 「서비스 연동」에서 「이메일」을 연결할 때
email_mailbox대시보드의 「서비스 연동」에서 「네이버 메일」을 연결할 때
whatsapp대시보드의 「서비스 연동」에서 「WhatsApp」을 연결할 때
messenger대시보드의 「서비스 연동」에서 「페이스북 메신저」를 연결할 때
instagram서버가 받는 값입니다. 대시보드의 「서비스 연동」에서는 일부 워크스페이스만 「Instagram」을 연결할 수 있습니다
shopline기능이 켜진 워크스페이스에서 SHOPLINE 연동을 설치할 때
shopify기능이 켜진 워크스페이스에서 Shopify 앱을 설치할 때
godomall기능이 켜진 워크스페이스에서 고도몰을 연결할 때
makeshop기능이 켜진 워크스페이스에서 메이크샵을 연결할 때
shopby기능이 켜진 워크스페이스에서 샵바이를 연결할 때
voice워크스페이스의 첫 전화 상담이 생길 때 하나가 자동으로 생깁니다. 음성 기능이 꺼진 워크스페이스에서는 목록에 나오지 않습니다
api연동 관리 권한이 있는 사용자가 api 연동을 직접 등록할 때. 공개 API로 대화를 보내는 것만으로는 생기지 않고, 대시보드의 「서비스 연동」에도 없습니다
board게시판 문의 연동입니다. 운영자만 만들 수 있습니다
sms예약된 값입니다. 대시보드의 「서비스 연동」에는 이 값이 없습니다
external_api이전 방식의 연동입니다. 대시보드의 「서비스 연동」에서는 더 이상 추가할 수 없고, 이미 있는 연동은 목록에 그대로 나옵니다

모르는 provider 값 때문에 응답 처리가 실패할 때​

provider는 닫힌 목록이 아닙니다. 새 채널을 지원하면 위 표에 없는 값이 추가될 수 있고, 그 값은 이 문서에 반영되기 전에 응답에 먼저 나올 수 있습니다. 연동하는 쪽에서는 다음을 지켜 주세요.

  • provider를 위 값만 허용하는 고정 enum으로 파싱하지 마세요. 모르는 값이 와도 응답 전체를 실패로 처리하지 마세요.
  • 모르는 값의 연동은 건너뛰거나 일반 연동으로 표시하세요. 그 연동의 id·name·status는 다른 연동과 같은 뜻입니다.

노출되지 않는 값​

암호화된 자격 증명(credentials), webhook secret·token, 공급사별 config 같은 비밀 값은 조회 단계에서 제외되므로 응답에 포함되지 않습니다.