관리번호로 070 대량 발급·관리하기 — 파트너 가입중개(External Assignment)

ClawOps Business 요금제 + 관리번호 Add-on (₩990,000/월) 으로, B2B 파트너가 관리계정 하나로 다수의 최종이용자에게 070 번호를 일괄 발급·관리할 수 있다.

핵심은 발급 링크(issuance link) 다. 파트너가 발급 링크를 만들어 최종이용자에게 전달하면, 최종이용자가 링크에서 본인인증을 거쳐 070을 받는다. 발급된 070은 파트너가 아니라 최종이용자 본인 명의로 계약되는 실제 통신 회선이다. 파트너는 별도 통신 사업 허가 없이 가입 중개만 한다.

어디에 쓰나

B2B 가입중개 — 파트너가 소속/입점 멤버에게 070을 일괄로 깔아주는 시나리오:

• 프랜차이즈 본사 → 가맹점주 각자에게 070 (점주 본인 명의)
• 플랫폼 → 입점 기사·사장님에게 070 (입점자 본인 명의)
• 부동산 법인 → 소속 중개인에게 070 (중개인 본인 명의)
• 방문·출장 서비스 업체 → 소속 기사·상담사에게 070

이건 멀티테넌시도, 즉석 마스킹도 아니다

먼저 무엇이 아닌지부터 명확히 한다.

• 소프트웨어 멀티테넌시 아님. 파트너 계정 아래 가상의 sub-account 를 파서 번호를 나눠주는 구조가 아니다. 발급되는 070 하나하나가 최종이용자 본인 명의의 실제 통신 계약이다.
• 거래별 즉석 폐기번호(mask) 아님. 거래 1건마다 30초 TTL로 번호를 자동 생성·폐기하는 모델은 불가능하다. 모든 070은 발급 시점에 최종이용자의 본인인증을 거쳐야 하므로, 자동 발급·자동 폐기되는 임시 번호는 존재하지 않는다.

발급 링크는 단발성(single-use)이라 TTL이 있지만, 이는 "링크의 만료 시간"이지 "번호의 수명"이 아니다. 링크가 만료돼도 이미 발급된 070은 최종이용자 명의로 그대로 유지된다.

0. 사전 준비

• ClawOps Business 가입 (₩99,000/월)
• 관리번호(external_assignment) Add-on 활성화 (Console → Add-ons → ₩990,000/월)
• 관리계정 API key

Add-on 이 비활성 상태에서 발급 API를 호출하면 403 FEATURE_DISABLED 가 떨어진다.

1. 발급 흐름

파트너 (관리계정)
  │  ① assignment_links.create(note=..., webhook_url=...)
  ▼
발급 링크 {token, url, expires_at}   ← 단발성, TTL 60~86400초
  │  ② 최종이용자에게 url 전달 (문자·이메일·QR 등)
  ▼
최종이용자가 url 방문
  │  ③ 본인인증 (본인 명의 통신 계약)
  ▼
070 발급 (최종이용자 명의)  → 링크 상태: pending → consumed
  │
  ▼
인입 통화 → 링크의 webhookUrl 로 라우팅 → 파트너/최종이용자 핸들러에서 AI agent 응대

링크 상태는 pending(발급 대기) → consumed(발급 완료) 로 바뀌며, 그 외 expired(TTL 경과), revoked(파트너가 회수) 가 있다.

2. 발급 링크 생성

from clawops import ClawOps
client = ClawOps()

link = client.assignment_links.create(
    note="강남점 점주 김OO",                       # 파트너 식별용 메모
    webhook_url="https://your-app.com/clawops/incoming",
    ttl_seconds=86400,                            # 링크 유효기간 (60~86400초)
)

print(link.token)        # 단발성 토큰
print(link.url)          # 최종이용자에게 전달할 발급 URL
print(link.expires_at)   # 링크 만료 시각

REST 로는 동일하게:

POST /v1/accounts/{accountId}/assignment-links
{
  "note": "강남점 점주 김OO",
  "webhookUrl": "https://your-app.com/clawops/incoming",
  "ttlSeconds": 86400
}
→ { "token": "...", "url": "https://...", "expiresAt": "..." }

이 url 을 최종이용자에게 보내면, 최종이용자가 열어서 본인인증을 마치는 순간 070이 본인 명의로 발급된다. 링크는 한 번 쓰면 소진된다.

3. 발급 현황 조회

# 아직 본인인증 전 (발급 대기)
pending = client.assignment_links.list(status="pending")

# 발급 완료
consumed = client.assignment_links.list(status="consumed")

for link in consumed:
    detail = client.assignment_links.get(link.id)
    print(detail.note, detail.status)

각 최종이용자의 번호·사용량·상태는 Enrollment API 와 파트너 대시보드 에서 확인한다. 대시보드는 "누구에게 발급했고(note), 본인인증을 마쳤는지, 어떤 070을 받았는지, 통화량은 얼마인지" 를 파트너 시점에서 한눈에 보여준다.

4. 링크 회수

아직 본인인증 전(pending)인 링크를 더 이상 쓰지 않게 하려면 회수한다.

client.assignment_links.revoke(link.id)           # 상태: pending → revoked

이미 consumed 된 링크로 발급된 070은 최종이용자 본인 명의 계약이므로, 링크 회수로 회수되지 않는다. 회선 자체의 해지는 최종이용자/계약 절차를 따른다.

5. 인입 통화 라우팅

발급된 070으로 전화가 걸려오면, 그 번호 발급에 쓰인 링크의 webhookUrl 로 이벤트가 전달된다. 핸들러에서 최종이용자별 컨텍스트를 채워 AI agent 를 붙인다.

# webhook 핸들러 (예: FastAPI)
@app.post("/clawops/incoming")
def incoming(event: dict):
    if event["type"] != "call.initiated":
        return {"ok": True}

    to_number = event["data"]["to"]               # 인입된 070
    ctx = lookup_owner_context(to_number)         # 자사 DB에서 최종이용자 컨텍스트 조회

    ClawOpsAgent(
        from_=to_number,
        session=OpenAIRealtime(
            system_prompt=f"""
당신은 {ctx['name']} 의 전화 상담원입니다.
영업시간: {ctx['hours']}
안내 사항: {ctx['notes']}
""",
            language="ko-KR",
        ),
    ).serve(non_blocking=True)
    return {"ok": True}

발급 링크마다 webhookUrl 을 다르게 줄 수도 있고, 하나의 핸들러에서 인입 번호(to)로 분기해도 된다. 100개 가맹점이면 100개 발급 링크 → 100개 070, 한 핸들러에서 non_blocking=True 로 multiplex 한다.

6. 발급 슬롯 한도

발급할 수 있는 070 슬롯 수는 플랜의 maxAgents 로 제한된다. 이때 한도에는 이미 발급된 회선 + 아직 본인인증 전인 pending 링크 가 모두 합산된다.

발급된 070 회선 수  +  pending 발급 링크 수  ≤  플랜 maxAgents

한도를 넘겨 링크를 만들려 하면 QUOTA_EXCEEDED 가 떨어진다. 즉, 쓰지 않을 링크를 잔뜩 만들어두면 슬롯을 점유하므로, 안 쓰는 pending 링크는 revoke 로 정리하는 게 좋다.

7. 가격

항목	비용
ClawOps Business 월정액	₩99,000/월 (070 10개·동시 10)
관리번호(external_assignment) Add-on	₩990,000/월
통화/메시지	기본 Business 단가 적용
전사·요약	₩10/분 (애드온)

관리번호 Add-on 은 Business 요금제 전용이다. 발급 슬롯 한도는 위 6번대로 플랜 maxAgents 를 따른다.

FAQ

Q. 발급한 070은 우리(파트너) 명의인가요? 아니요. 최종이용자 본인 명의입니다. 파트너는 본인인증 기반의 가입 중개만 하며, 별도 통신 사업 허가 없이 운영합니다.

Q. 거래 1건마다 임시 070을 자동 생성·폐기할 수 있나요? 불가능합니다. 모든 070은 발급 시 최종이용자의 본인인증이 필요하므로, 자동 발급·자동 폐기되는 단발 마스킹 번호 모델은 제공하지 않습니다.

Q. 발급 링크를 잘못 보냈습니다. 아직 pending 상태라면 client.assignment_links.revoke(link_id) 로 회수하세요. 이미 consumed 됐다면 070이 발급된 것이므로 회선 해지 절차를 따릅니다.

Q. 링크가 만료되면 발급된 번호도 사라지나요? 아니요. TTL은 "링크"의 유효기간입니다. 링크가 expired 돼도 그 전에 발급된 070은 최종이용자 명의로 유지됩니다.

Q. 403 FEATURE_DISABLED 가 떠요. 관리번호(external_assignment) Add-on 이 비활성 상태입니다. Console → Add-ons 에서 활성화하세요.

Q. QUOTA_EXCEEDED 가 떠요. 발급된 회선 + pending 링크 합이 플랜 maxAgents 한도를 넘었습니다. 안 쓰는 pending 링크를 revoke 하거나 플랜을 상향하세요.

이 기능이 맞지 않는 경우

• 개인용 070 한 개만 필요하다 → 관리번호는 과합니다. 그냥 Trial 로 070 한 개를 발급받으세요 (3일 무료, 카드 불필요).
• 거래별 즉석 폐기번호를 원한다 → 제공하지 않습니다. 모든 070은 최종이용자 본인 명의의 실제 통신 계약입니다.

다음 단계

• 070 5분 발급 가이드 (Trial)
• 1588·1566 대표번호 무료 연동
• 070 webhook 라우팅 — 시간/번호/DTMF 분기
• Python AI 전화 SDK 5분 가이드