ClawOps API (v1.3.2)

ClawOps CPaaS API — Voice & Messaging. Authorization 헤더에 Bearer <api_key> 형식으로 인증합니다.

인증

Authorization: Bearer <api_key> 헤더로 인증합니다.

Endpoint 그룹

• Agents — 매니지드 AI 음성 에이전트와 지식 문서의 생성, 조회, 수정 및 삭제
• Calls — 아웃바운드 전화 발신, 통화 조회 및 제어
• Numbers — 전화번호 발급, 조회 및 반납
• Messages — SMS/LMS/MMS 문자와 카카오 알림톡·브랜드 메시지 발송 및 조회
• KakaoChannels — 카카오 비즈니스 채널 연결. 담당자 휴대전화로 받은 인증번호로 채널 소유를 증명해 계정에 연결하고, 연결 상태를 조회합니다. 인증번호는 담당자 휴대전화로만 전달되며 API 응답에 실리지 않습니다. 채널 목록이 반환하는 ClawOps 리소스 ID를 상세 조회·연결 해제·알림톡 발송에 사용합니다. 외부 메시지 공급자의 식별자는 공개 API에 노출하지 않습니다.
• KakaoTemplates — 연결된 채널에서 사용할 수 있는 알림톡 템플릿을 조회합니다. 응답의 id는 알림톡 발송 요청의 Kakao.TemplateId에 사용하는 ClawOps 리소스 ID입니다.
• KakaoBrandTemplates — 연결된 채널에서 사용할 수 있는 브랜드 메시지 템플릿을 조회합니다. 응답의 id는 브랜드 메시지 발송 요청의 Brand.TemplateId에 사용하는 ClawOps 리소스 ID입니다.
• Emails — 이메일 발송. 검증된 발신 도메인의 주소로 메일을 보냅니다. 첨부는 URL 로 전달하며 우리가 서버에서 내려받아 붙입니다. ⚠️ 과금 단위는 "통"이 아니라 수신자입니다 — 한 통을 3명에게 보내면 3건입니다.
• EmailDomains — 이메일 발신 도메인. 소유한 도메인을 등록하고, 받은 DNS 레코드(CNAME 3건)를 심어 소유를 증명하면 그 도메인으로 발신할 수 있게 됩니다. 등록만으로는 발신되지 않습니다 — DNS 설정 후 검증 API 를 호출해 verified 를 확인해야 합니다.

한 도메인은 ClawOps 전체에서 한 계정만 소유합니다. 루트 도메인과 하위 도메인은 별개 리소스이며, claw-ops.com 등 ClawOps 가 사용하는 도메인은 등록할 수 없습니다.

• Verifications — 본인인증(코드 방식). 인증 한 건을 만들고 코드를 대조합니다 — 생성 → 대조 → 결과 하나로 끝나며, 코드 생성·만료·시도 제한·한도는 우리가 관리합니다.

v2 경로입니다. 계정 ID 가 경로에 없고 API 키가 계정을 정하며, 요청·응답 필드는 모두 camelCase 입니다. 인증 방식(Authorization: Bearer)과 에러 모양 ({ error, code })은 v1 과 같습니다.

⚠️ 코드는 어떤 응답에도 실리지 않습니다. 사용자에게 가는 경로는 문자 본문 하나뿐이고 저장도 해시로만 합니다.

• Webhooks — 이벤트 기반 Webhook 관리
• AssignmentLinks — 관리번호(External Assignment) 발급 링크. external_assignment 애드온이 활성화된 계정만 POST/DELETE가 가능합니다.
• Dictionaries — 통화 받아쓰기(전사) hotwords 사전. 조직/번호별로 도메인 용어의 '들리는 발음형'(term)을 등록해 인식을 교정하고, canonical 을 지정하면 전사 후 표기 치환(예 "클로옵스"→"ClawOps")을 적용합니다. 번호에 사전을 부착하면 계정 기본 사전 대신 그 사전을 대체 적용(병합 아님)합니다.
• Certificates — 증명서 즉시 발급. 지금 종류는 통신서비스 이용증명원(telecom_subscription) 하나이며, 한국AI통신이 개통한 070·대표번호에 대해서만 발급합니다. 요청하면 그 자리에서 PDF 를 받고, 메일로도 보낼 수 있습니다.
• BlockedRecipients — 수신거부(DNC) 명단. 광고 문자 하단의 080 무료수신거부, ARS의 "수신거부 9번", 상담 중 구두 요청 등으로 접수된 번호를 계정 단위로 관리합니다. 전화와 문자는 각각 따로 차단하고, 해제해도 항목은 이력으로 남습니다. 대상은 이 계정의 발신(전화·문자)이며 착신은 대상이 아닙니다.

등록하면 발신이 실제로 막힙니다. 통화 생성·메시지 발송이 발신 직전에 이 명단을 조회해 422 recipient_blocked 로 거절하며, 배치 발신(캠페인)도 같은 관문을 지나므로 해당 대상은 자동으로 건너뜁니다. 막힌 통화는 통화기록에 hangup_cause=recipient_blocked 로 남습니다.

수신 통화를 막으려면 BlockedCallers(수신 통화 차단)를 사용하세요.

• BlockedCallers — 수신 통화 차단. 등록한 번호에서 이 계정의 번호로 걸려 오는 수신 통화를 받지 않고 거절합니다. 계정 단위 목록이며 번호는 완전 일치로만 대조합니다. 해제해도 항목은 이력으로 남습니다. 발신은 막지 않습니다 — 발신을 막는 명단은 BlockedRecipients(수신거부)입니다.

거절된 통화는 통화 기록에 status=rejected, hangupCause=caller_blocked 로 남고, 수신 통화 statusCallback 이 설정돼 있으면 CallStatus=rejected 종료 통지가 한 번 갑니다. 번호 표시제한 통화는 이 목록이 아니라 번호 설정의 rejectCallerIdRestricted 로 거절합니다(hangupCause=caller_id_restricted_rejected).

• CallFlows — 콜 플로우(결정적 ARS) 조회·생성·수정·삭제. 블럭을 조립해 만든 ARS/IVR로, 발신은 createCall의 CallFlowId, 착신은 번호 라우팅(routingType=callflow)으로 연결합니다. 콘솔 빌더와 같은 그래프 포맷을 주고받으므로 API로 만든 플로우도 콘솔에서 그대로 열립니다. 통화가 수집한 값은 callflow.ended webhook으로 받습니다.
• CallBatches — 배치 발신(캠페인). 명단을 넣으면 동시통화 한도·분당 발신 속도·발신 가능 시간대를 지키며 순차적으로 발신합니다. 대상은 콜 플로우·매니지드 에이전트·VoiceML URL 중 하나입니다. 계정별 활성화가 필요하며, 활성화되지 않은 계정은 생성 시 403 입니다.
• SipTrunks — BYOC SIP 트렁크 관리. PSTN 인바운드를 외부 PBX로 전달(origination)하기 위한 엔드포인트와 라우트(다이얼 타겟). sip_trunk 애드온이 활성화된 계정만 변경(POST/PUT/DELETE)이 가능합니다.
• AssignmentSessions — 일회용 고엔트로피 토큰으로 진행하는 최종이용자 관리번호 발급 세션
• WebRTC — 브라우저(WebRTC) / SIP 단말이 ClawOps 게이트웨이에 등록·발신하기 위한 단기 토큰과 ICE/TURN 서버 정보. 영구 SipCredential 1개로부터 짧은 TTL(최대 24시간) JWT 토큰을 발급해서 클라이언트에 전달하는 패턴.
• Usage — 사용량 집계 조회. 통화 목록을 직접 합산하는 것과 달리 사후 정정과 청구 주기 경계가 반영된 확정값을 돌려줍니다. 관리번호 파트너는 groupBy=linkId 로 최종이용자별 사용량을 분리해 정산에 씁니다.
• MobileGateways — BT 휴대폰(chan_mobile) 게이트웨이 박스를 WireGuard 터널로 ClawOps SIP 에 붙이는 셀프 온보딩. 콘솔에서 1회용 enroll 토큰을 발급하고, 박스가 그 토큰으로 콜홈해 터널 IP 를 자동 할당받는다.

왼쪽 사이드바에서 그룹별 endpoint 를 펼쳐 확인하거나, 최초 호출 가이드 부터 시작하세요.