관리번호 발급 링크 생성

엔드유저가 방문하여 번호를 발급받을 수 있는 일회용 링크를 생성합니다.

전제조건: 계정에 external_assignment 애드온이 활성화되어 있어야 합니다. 비활성 시 403 FEATURE_DISABLED.

슬롯 한도: 발급된 회선 + 사용되지 않은 pending 링크 수의 합이 플랜 maxAgents를 초과하면 422 QUOTA_EXCEEDED.

한 링크는 1회만 소비되며, 소비되거나 만료/취소되면 재사용할 수 없습니다.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Request

This endpoint expects an object.

webhookUrlstringOptionalformat: "uri"

발급된 번호로 인입되는 통화/메시지를 받을 webhook URL

webhookMethodenumOptionalDefaults to POST

Allowed values:

notestringOptional<=200 characters

내부 메모

ttlSecondsintegerOptional60-604800

링크 만료까지의 시간(초). 미지정 시 기본 7일. ⚠️ 이 범위는 services/assignment-links.ts 의 TTL_SECONDS_MIN/MAX 와 같은 값이어야 한다 — 갈라지면 validator 가 먼저 400 을 내서 서비스 문구가 도달하지 않는다.

returnUrlstringOptionalformat: "uri"<=2048 characters

발급 완료 후 최종이용자를 되돌려 보낼 주소. host 가 계정에 등록된 허용 도메인과 정확히 일치해야 하며(대시보드 설정 → 조직 → 발급 페이지), 아니면 400. 미지정 시 완료 화면에 머문다.

webhookHeadersmap from strings to strings or nullOptional

발급 시 phone_number 로 prefill 될 헤더. 키는 “X-” prefix 필수 (case-insensitive), reserved 헤더(X-Signature, X-Forwarded-*, X-Real-IP) 거절. 최대 10 entries, key ≤ 64 bytes, value ≤ 2048 bytes, ASCII printable. null 전송 시 헤더 제거, 미포함 시 변경 없음.

Response

링크 생성 성공

tokenstringOptional

linkId와 동일한 값

urlstringOptional

엔드유저용 공개 URL

expiresAtdatetimeOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error