번호 설정 수정
등록된 번호의 설정을 수정합니다. webhookUrl/webhookMethod 외에 routingType/sipEndpointId/sipCredentialId 도 수정 가능합니다. routingType=sip 으로 변경 시 sip_trunk 애드온이 활성화돼 있어야 하며, sipEndpointId 는 같은 계정 소유의 active 엔드포인트(활성 라우트 1개 이상)여야 합니다. routingType=softphone 으로 변경 시에도 sip_trunk 애드온이 필요하며, sipCredentialId 는 같은 계정 소유의 active·enabled SIP credential(등록 단말)이어야 합니다.
Authentication
API Key를 Bearer 토큰으로 전달
Path parameters
계정 ID
수정할 전화번호
Request
routingType=‘webhook’에서 수신 전화를 처리할 VoiceML Webhook URL
routingType=‘agent’에서 Managed Agent 시작 직전에 통화별 CallContext를 조회할 동기 endpoint. 응답은 {“CallContext”:{“Instruction”:”…”,“Variables”:{…}}} 형식이며, 조회 실패 시 저장된 Agent 설정만으로 통화를 계속합니다.
Webhook 호출 HTTP 메서드
Agent 미연결/거부 시 fallback 라우팅. ‘sip’ 로 변경 시 sip_trunk 애드온 + 유효한 sipEndpointId 필요. ‘softphone’ 으로 변경 시 sip_trunk 애드온 + 유효한 sipCredentialId(등록 단말) 필요. ‘forward’ 로 변경 시 forwardTo(같은 계정 보유 번호) 필요 — 내부 착신전환. ‘agent’ 로 변경 시 agentId 필요 — 매니지드 에이전트가 전화를 받습니다. ‘callflow’ 로 변경 시 callFlowId 필요 — 이 번호로 걸려온 전화를 콜 플로우(결정적 ARS)가 받습니다. ‘webhook’ 으로 되돌리면 다른 라우팅 ID가 자동으로 null 처리됩니다.
routingType=‘sip’ 일 때 라우팅할 SipEndpoint id. 같은 계정 소유 + status=active + 활성 라우트 1개 이상이어야 함.
routingType=‘softphone’ 일 때 착신할 등록 SIP credential(단말) id. 같은 계정 소유 + status=active + enabled 여야 하며, ephemeral(세션) credential 은 사용 불가.
routingType=‘forward’ 일 때 내부 착신전환할 대상 번호(같은 계정 보유 번호). 한국 번호 정규화 후 저장. 주면 전환 대상이 이 번호 하나가 됩니다.
routingType=‘forward’ 일 때 전환 대상 목록(최대 10개). 모두 동시에 울리고 먼저 받은 쪽으로 연결됩니다. 둘 이상이면 모든 대상이 SIP 단말(routingType=‘softphone’)로 받는 같은 계정 번호여야 합니다. forwardTo 와 함께 줄 수 없습니다.
routingType=‘callflow’ 일 때 인입을 처리할 콜 플로우 id. 같은 계정 소유여야 합니다. id 는 GET /v1/accounts/{accountId}/call-flows 로 조회합니다.
routingType=‘agent’ 일 때 인입을 처리할 매니지드 에이전트 id. 같은 계정 소유여야 합니다. id 는 GET /v1/accounts/{accountId}/agents 로 조회합니다.
Inbound webhook 호출 시 추가될 HTTP 헤더. 같은 통화의 후속 요청(action·<Redirect>·referUrl) 중 webhookUrl 과 origin(scheme·host·port)이 같은 요청에도 실립니다. 상태 콜백에는 실리지 않습니다. 키는 “X-” prefix 필수 (case-insensitive), reserved 헤더(X-Signature, X-Forwarded-*, X-Real-IP) 거절. 최대 10 entries, key ≤ 64 bytes, value ≤ 2048 bytes, ASCII printable. null 전송 시 헤더 제거, 미포함 시 변경 없음.
수신(inbound) 통화 상태 webhook URL. 빈 문자열/null 전송 시 해제.
구독할 상태 이벤트(공백 구분, 선택). 미지정 시 initiated ringing answered completed 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요. 전체 목록은 Webhooks.
받아쓰기 사전 부착. 같은 계정 소유 사전 id 를 지정하면 이 번호로 걸려온 통화 전사에 해당 사전을 대체 적용(병합 아님). null 전송 시 부착 해제(계정 기본 사전 폴백). 미포함 시 변경 없음.
번호 별칭(용도 메모). 앞뒤 공백은 지워 저장하며 최대 50자, 줄바꿈 등 제어문자는 쓸 수 없습니다. null 또는 빈 문자열을 보내면 별칭을 지웁니다. 미포함 시 변경 없음. 라우팅에는 영향이 없습니다.
발신 때 받는 화면에 표시할 승인된 표시 번호 id. null 이면 해제되어 이 번호가 그대로 표시되고, 미포함 시 변경 없음. 다음 통화부터 적용됩니다. 대표번호와 게이트웨이 번호에는 걸 수 없고, 발신번호 범위를 지정한 API 키로는 바꿀 수 없습니다.
true 면 이 번호로 걸려 오는 번호 표시제한 수신 통화를 받지 않고 거절합니다. 거절된 통화는 통화 기록에 status=rejected, hangupCause=caller_id_restricted_rejected 로 남습니다. routingType 과 무관하게 적용되며 미포함 시 변경 없음. 통신사가 표시제한 여부를 보내지 않는 경로에서는 거절되지 않을 수 있습니다. 특정 번호의 수신 통화를 막으려면 수신 통화 차단(POST /v1/accounts/{accountId}/blocked-callers)을 사용하세요.
Response
수정 성공
전화번호
번호 출처 (pool 등)
routingType=‘agent’에서 Managed Agent 시작 전에 통화별 CallContext를 조회하는 동기 endpoint.
Agent 미연결/거부 시 fallback 라우팅. ‘webhook’ = webhookUrl 호출, ‘sip’ = sipEndpointId 의 OriginationRoute 로 외부 PBX 다이얼, ‘softphone’ = sipCredentialId 의 등록 단말로 착신(Kamailio usrloc fork), ‘forward’ = forwardTo(보유 번호)로 내부 착신전환, ‘callflow’ = callFlowId 의 콜 플로우(결정적 ARS)가 인입을 받음, ‘agent’ = agentId 의 매니지드 에이전트가 받음.
routingType=‘sip’ 일 때 사용할 SipEndpoint id. 그 외 라우팅에서는 null.
routingType=‘softphone’ 일 때 착신할 등록 SIP credential(단말) id. 그 외 라우팅에서는 null.
routingType=‘forward’ 일 때 내부 착신전환 대상 번호(같은 계정 보유 번호). 대상이 여러 개면 첫 번째 대상. 그 외 라우팅에서는 null.
routingType=‘forward’ 일 때 전환 대상 전체(첫 번째가 forwardTo). 모두 동시에 울리고 먼저 받은 쪽으로 연결됩니다. 미설정이거나 그 외 라우팅이면 빈 배열.
routingType=‘callflow’ 일 때 인입을 처리할 콜 플로우 id. 그 외 라우팅에서는 null.
routingType=‘agent’ 일 때 인입을 처리할 매니지드 에이전트 id. 그 외 라우팅에서는 null.
Inbound webhook 호출 시 추가될 HTTP 헤더. 같은 통화의 후속 요청(action·<Redirect>·referUrl) 중 webhookUrl 과 origin(scheme·host·port)이 같은 요청에도 실립니다. 상태 콜백에는 실리지 않습니다. 키는 “X-” prefix 필수 (case-insensitive), reserved 헤더(X-Signature, X-Forwarded-*, X-Real-IP) 거절. 최대 10 entries, key ≤ 64 bytes, value ≤ 2048 bytes, ASCII printable. null 전송 시 헤더 제거, 미포함 시 변경 없음.
수신(inbound) 통화 상태 webhook URL. 발신은 통화 생성 시 statusCallback 으로 별도 관리.
구독할 상태 이벤트(공백 구분). 미지정 시 initiated ringing answered completed 가 적용됩니다. transfer(호전환 진행 상황)는 기본에 포함되지 않으므로 받으려면 직접 나열하세요.
번호 유형. did = 일반 번호, representative = 대표번호, safety050 = 050 안심번호(전화를 걸거나 문자를 보낼 수 없음).
부착된 받아쓰기 사전 id. null 이면 이 번호로 걸려온 통화 전사에 계정 기본 사전을 사용.
번호마다 적어 두는 용도 메모(별칭). null 이면 별칭 없음. 발신 표시·라우팅에는 쓰이지 않습니다.
번호 표시제한 수신 통화를 받지 않고 거절하는지 여부. 기본 false.
발신 때 받는 화면에 보일 표시 번호 id. null 이면 이 번호가 그대로 표시됩니다.