KaiCalls는 대화하는 비서로 시작되었습니다. 이제는 여러분이 그 위에 구축할 수 있는 시스템이기도 합니다. 에이전시, 수직적 소프트웨어 벤더(Vertical software vendors), 그리고 파트너들은 KaiCalls를 폐쇄적인 대시보드로 취급하는 대신 자신들의 제품에 연결할 수 있습니다.

이 가이드는 개발자 플랫폼이 무엇을 노출하는지, 각 구성 요소가 어떻게 맞물리는지, 그리고 어디서부터 시작해야 하는지를 안내합니다. 여러분은 API 키, 커뮤니케이션 실행(Communication runs), 웹훅(Webhooks), 그리고 내구성이 있는 이벤트 표면(Durable event surface)을 얻게 되며, 이 모든 것은 OpenAPI 사양(OpenAPI spec)으로 문서화되어 있습니다.

개발자 플랫폼의 위치

개발자 플랫폼은 대시보드의 /dashboard/settings/api-keys에 위치합니다. 해당 페이지는 워크스페이스(Workspace)를 위한 API 키를 생성하고 관리하는 곳입니다. API 문서는 /docs/api에 있으며, 바로 실행 가능한 퀵스타트(Quickstart)는 /docs/api/quickstart에 있습니다.

KaiCalls 워크스페이스는 이미 통화를 캡처하고, 발신자의 자격을 검증하며, 예약을 잡고, 문자 및 이메일로 후속 조치를 취합니다. 개발자 플랫폼은 이러한 기능들을 엔드포인트(Endpoints)로 변환합니다. 여러분의 소프트웨어는 대시보드에 표시되는 것과 동일한 리드(Leads)와 통화를 읽을 수 있으며, 비서가 할 수 있는 것과 동일한 아웃바운드 커뮤니케이션(Outbound communication)을 트리거할 수 있습니다.

전체 인터페이스는 OpenAPI 사양(OpenAPI spec)으로 설명되어 있습니다. 클라이언트 생성기(Client generator)를 해당 사양으로 지정하면, 문서를 한 줄씩 읽을 필요 없이 모든 공개 경로(Public route)에 대한 타입 지정 메서드(Typed methods)를 얻을 수 있습니다.

범위가 제한된 API 키 (Scoped API keys)

플랫폼의 API 키는 모든 권한을 가진 것이 아니라 범위(Scope)가 지정되어 있습니다. 범위는 키가 읽고 쓸 수 있는 것을 제한하므로, 하나의 통합(Integration)에 전달된 키가 워크스페이스의 나머지 부분에 몰래 접근할 수 없습니다.

범위 지정(Scoping)은 파트너들에게 가장 중요합니다. 클라이언트를 위해 KaiCalls를 임베딩하는 에이전시는 해당 클라이언트의 데이터와 해당 통합의 작업으로 제한된 키를 발행할 수 있습니다. 이 키는 통합에 필요한 작업만 수행하며 그 외의 것은 수행하지 않습니다.

범위가 지정된 키는 플랫폼의 나머지 부분이 구축되는 토대입니다. /v1 API에 대한 모든 호출은 키를 포함하며, 해당 키의 범위가 호출이 허용되는 작업을 결정합니다.

커뮤니케이션 실행 (Communication runs)

커뮤니케이션 실행 (Communication run)은 API가 아웃바운드 연락 (outbound contact)을 시작하는 방식입니다. 실행 모델 (run model)은 전체 라이프사이클 (lifecycle)을 다루므로, 사용자의 소프트웨어는 실행을 검증 (validate)하고, 미리 보기 (preview)하고, 생성 (create)한 다음, 계획이 변경되면 일시 중지 (pause)하거나 취소 (cancel)할 수 있습니다.

라이프사이클 엔드포인트 (lifecycle endpoints)는 명확하게 구분되어 있습니다:

1. 검증 (Validate): 무언가를 확정하기 전에 POST /v1/communication-runs/validate를 통해 실행을 검증합니다. 검증 단계는 실행이 올바른 형식인지 확인하므로, 고객에게 도달하기 전에 문제를 포착할 수 있습니다.
2. 미리 보기 (Preview): 실행이 시작되면 어떤 동작을 수행할지 미리 확인합니다.
3. 생성 (Create): 실행을 실제로 시작하기 위해 실행을 생성합니다.
4. 일시 중지 또는 취소 (Pause or cancel): 실행 도중에 중단해야 하는 경우 실행을 일시 중지하거나 취소합니다.

생성 (Create) 호출에는 Idempotency-Key (멱등성 키)가 필요합니다. 멱등성 (idempotency) 요구 사항은 재시도된 요청이 동일한 실행을 두 번 시작하지 않음을 의미하며, 따라서 불안정한 네트워크나 앱 내에서의 더블 클릭으로 인해 고객에게 중복 연락이 가는 것을 방지합니다. 이는 현대적인 결제 및 메시징 API에서 사용하는 표준 패턴이며, KaiCalls API는 실행 생성 시 이를 강제합니다.

필터링된 웹훅 (Filtered webhooks)

웹훅 (Webhooks)은 사용자가 폴링 (poll)을 하는 대신 이벤트를 엔드포인트 (endpoint)로 푸시 (push)합니다. KaiCalls 플랫폼은 프로덕션 환경에서 안전하게 실행할 수 있게 해주는 세 가지 기능을 갖춘 구독형 웹훅 (subscription webhooks)을 지원합니다.

두 번째는 테스트 전달 (test delivery)입니다. 개발 중에 엔드포인트로 테스트 이벤트를 발송하여, 실제 이벤트에 의존하기 전에 핸들러 (handler)가 제대로 작동하는지 확인할 수 있습니다.

세 번째는 비밀 키 순환 (secret rotation)입니다. 구독을 해지하지 않고도 구독의 서명 비밀 키 (signing secret)를 순환시킬 수 있으므로, 라이브 전달 (live deliveries)을 중단하지 않고도 검증 (verification) 상태를 최신으로 유지할 수 있습니다.

재생 및 백필을 지원하는 내구성 있는 이벤트 (Durable events with replay and backfill)

웹훅은 실패할 수 있습니다. 엔드포인트가 다운되거나, 배포 (deploy) 과정에서 진행 중인 요청이 유실되거나, 네트워크 타임아웃 (time out)이 발생할 수 있습니다. 푸시 전용 (push-only) 시스템은 이러한 이벤트를 영구적으로 잃게 됩니다. 대신 KaiCalls 플랫폼은 이벤트를 내구성 있게 (durably) 저장합니다.

모든 이벤트는 전달 시도 (delivery attempts)와 함께 기록되므로, 무엇이 전송되었고 성공적으로 도착했는지 확인할 수 있습니다. 세 가지 엔드포인트가 해당 저장소를 복구 도구로 전환합니다:

• /v1/events를 통해 **이벤트 목록을 조회 (List events)**하여 워크스페이스에서 발생한 일에 대한 영구적인 기록을 읽을 수 있습니다.
• event-deliveries 인터페이스를 통해 **전송 상태를 조사 (Inspect deliveries)**하여 귀하의 엔드포인트에 대한 각 시도(attempt)를 확인할 수 있습니다.
• 엔드포인트가 이벤트를 놓쳤을 때 **이벤트를 재생(Replay)하거나 백필(Backfill)**할 수 있으므로, 다운타임(downtime) 구간이 영구적인 공백이 아닌 추적 가능한 작업(catch-up job)이 됩니다.

영구적인 이벤트(Durable events)는 구축 방식을 변화시킵니다. 이벤트가 여전히 저장소에 남아 있고 엔드포인트가 복구되었을 때 재생할 수 있기 때문에, 놓친 웹훅(webhook)을 유실된 데이터로 취급하지 않게 됩니다.

증거 조회 API (Evidence read APIs)

플랫폼은 또한 통화 이면에 있는 기록을 위한 조회 API(read APIs)를 제공합니다. 이것들은 증거 엔드포인트(evidence endpoints)이며, 귀하의 소프트웨어가 통화로 인해 생성된 산출물(artifacts)을 가져올 수 있게 해줍니다.

증거 인터페이스는 SMS 메시지 및 대화, 작업(jobs), 시도(attempts), 그리고 녹음(recordings)을 다룹니다. 클라이언트에게 통화 시 발생한 일을 보여줘야 하는 통합(integration) 서비스는 대시보드를 스크래핑하는 대신 이러한 엔드포인트를 읽습니다. 에이전트 설정 버전(agent config versions) 읽기 엔드포인트를 사용하면 에이전트가 실행 중이던 설정을 확인할 수 있으므로, 동작과 해당 동작을 생성한 정확한 버전을 상관관계(correlate) 지을 수 있습니다.

조회 API는 플랫폼을 완성합니다. 통신 실행(communication runs)을 통해 액션을 시작하고, 웹훅(webhooks)을 통해 결과를 전달받으며, 증거 엔드포인트(evidence endpoints)를 통해 기반 기록을 가져옵니다.

개발자 플랫폼의 대상

이 플랫폼은 세 가지 대상에게 적합합니다.

KaiCalls를 재판매하거나 내장하는 에이전시(Agencies)는 클라이언트별로 범위가 지정된 키(scoped keys)와 통합별 웹훅을 할당받아 하나의 API로 많은 비즈니스를 관리할 수 있습니다. 자체 제품 내에 통화 캡처 기능이 필요한 수직적 소프트웨어 벤더(Vertical software vendors)는 사용자에게 별도의 대시보드를 사용하도록 요청하는 대신, 이를 연결할 수 있는 API를 제공받습니다. KaiCalls 상단에 감사(audit) 또는 보고 레이어를 구축하는 파트너는 영구적인 이벤트와 증거 조회를 통해 다운타임 중에도 시스템의 동기화를 유지할 수 있습니다.

귀하의 소프트웨어에 캡처, 자격 검증 및 보고가 가능한 전화 시스템이 필요하다면, 개발자 플랫폼은 구축을 위한 접점(seam)이 될 것입니다.

시작하는 방법

첫 번째 인증된 통화(authenticated call)를 수행하려면 다음 단계를 따르세요.

1. /dashboard/settings/api-keys에서 개발자 플랫폼을 열고 범위가 지정된 키(scoped key)를 발행(mint)하세요.
2. /docs/api/quickstart의 퀵스타트(quickstart)를 읽고 첫 번째 인증된 요청을 수행하세요.
3. API 문서에 링크된 OpenAPI 명세(spec)로부터 클라이언트(client)를 생성하여 코드에 타입이 지정된 메서드(typed methods)를 적용하세요.
4. 실제 서비스를 시작하기 전, POST /v1/communication-runs/validate를 사용하여 통신 실행(communication run)을 검증하고 페이로드(payload)를 확인하세요.

이러한 일련의 과정은 모든 경로(route)가 OpenAPI 명세에 포함되어 있고 퀵스타트가 인증 흐름(auth flow)을 보여주기 때문에, 추측할 필요 없이 제로 상태에서 작동하는 통합(integration) 단계까지 도달하게 해줍니다.

FAQ

KaiCalls에 API가 있나요?
네. KaiCalls 개발자 플랫폼은 범위가 지정된 키(scoped keys), 통신 실행(communication runs), 필터링된 웹훅(webhooks), 내구성이 있는 이벤트(durable events), 그리고 증거 읽기 엔드포인트(evidence read endpoints)를 갖춘 공개 /v1 API를 제공합니다. 키는 /dashboard/settings/api-keys에서 관리하며, 문서는 /docs/api에서 확인할 수 있습니다.

API를 통해 아웃바운드 연락(outbound contact)을 시작하려면 어떻게 하나요?
통신 실행(communication runs)을 사용하세요. POST /v1/communication-runs/validate로 실행을 검증하고, 미리 보기(preview)를 수행한 뒤, Idempotency-Key와 함께 생성하고, 필요한 경우 일시 중지하거나 취소할 수 있습니다.

웹훅(webhook) 엔드포인트가 다운되면 어떻게 되나요?
이벤트는 전달 시도(delivery attempts) 정보와 함께 내구성 있게(durably) 저장됩니다. 엔드포인트가 복구되면 /v1/events 및 event-deliveries 인터페이스를 통해 놓친 이벤트를 다시 재생(replay)하거나 백필(backfill)할 수 있습니다.

API 키가 할 수 있는 작업을 제한할 수 있나요?
네. 키에는 범위(scope)가 지정되어 있으므로, 특정 통합(integration)에 발급된 키는 해당 통합에 필요한 작업만 읽고 쓸 수 있습니다.

OpenAPI 명세(spec)가 있나요?
네. 공개 v1 경로들은 API 문서에 링크된 OpenAPI 명세로 커버되어 있으므로, 타입이 지정된 클라이언트(typed client)를 생성할 수 있습니다.

직접 구축해 보세요. kaicalls.com에서 퀵스타트를 읽어보거나, (417) 386-2898로 KaiCalls 데모 라인에 전화하여 여러분의 통합 시스템이 연결될 비서의 목소리를 들어보세요.