시작하기

시작하기

한국 070 번호의 본인확인과 발급 조건을 확인하고, Python 또는 Node.js SDK로 AI 음성 에이전트의 발신·수신을 연결하는 가이드입니다.

Markdown으로 보기

시작하기

한국AI통신은 팀러너스 주식회사가 운영하는 한국 전화·문자 API 플랫폼입니다.

공식 API 주소는 https://api.koreaaitel.com입니다. Python SDK는 koreaaitel, Node.js SDK는 @koreaaitel/sdk로 설치합니다.

전화번호 발급, 통화 발신/수신, SMS/MMS 발송, AI 음성 에이전트까지 Python SDK로 제어할 수 있습니다.

이 가이드에서는 대시보드에서 번호를 발급받고, AI 에이전트로 전화를 받고 거는 것까지 진행합니다.

이 가이드는 SDK 기반의 Voice Agent 경로입니다. AI 봇이 아니라 통화 흐름 자체 를 IVR/분기/녹음 등으로 직접 제어해야 한다면 직접 만들기 (VoiceML) 의 비교를 먼저 확인하세요.

1단계: 번호 발급

계정 만들기와 본인확인

회원가입 후 필수 약관에 동의하고, 본인 명의의 지원되는 국내 휴대전화로 본인확인을 완료하면 대시보드에 접속할 수 있습니다. 개인 계정은 소유자의 본인확인이 필요하고, 사업자 계정은 번호를 발급하기 전에 별도 사업자 인증도 완료해야 합니다.

국내 휴대전화 번호 없이도 계정은 만들 수 있습니다. 본인확인이 어려우면 대시보드 이용, 체험 시작, 셀프서비스 070 발급이 제한됩니다. 요금제를 선택하기 전에 hello@koreaaitel.com으로 문의해 주세요. 영문 발급 안내도 참고할 수 있습니다.

요금제와 발급 가능 여부 확인

발급하려면 활성 구독이 있고, 발급 가능한 회선 한도와 070 번호 재고가 남아 있어야 합니다. 체험 대상 고객은 휴대전화 본인확인을 완료한 뒤 7일 동안 체험할 수 있으며, 체험에 070 번호 한 개가 포함됩니다. 유료 요금제에서도 본인확인이 필요합니다. 자세한 조건은 요금 안내와 전화번호 발급 문서를 참고하세요.

070 번호 발급

대시보드 > 전화번호 메뉴에서 새 070 번호를 요청합니다. 발급된 번호를 AI 에이전트의 발신과 수신에 사용할 수 있습니다.

API Key 확인

대시보드 > 개발자 > API 키에서 다음 두 값을 확인합니다.

항목설명
API KeySDK 인증에 사용되는 키
Account ID계정 고유 ID

2단계: 인바운드 에이전트

발급받은 번호로 걸려오는 전화를 AI가 받도록 설정합니다.

SDK 설치

Python 또는 Node.js / TypeScript 중 선택:

# Python (3.10+)
pip install "koreaaitel[agent,openai]"

# Node.js / TypeScript (18+)
npm install @koreaaitel/sdk ws openai

기존 pip install clawops와 npm install @teamlearners/clawops도 지원합니다. Python 코드는 import clawops를 사용합니다.

Python은 가상환경(venv) 사용을 권장합니다. Node.js는 ESM 환경("type": "module" 또는 .mjs)에서 실행하세요.

이 가이드는 현재 유일하게 검증 완료된 OpenAI Realtime을 사용합니다. 다른 제공자를 사용하려면 제공자 호환성에서 검증 상태를 확인하세요.

환경변수 설정

export CLAWOPS_API_KEY="your-api-key"
export CLAWOPS_ACCOUNT_ID="your-account-id"
export OPENAI_API_KEY="your-openai-key"

에이전트 실행

Python

from clawops.agent import ClawOpsAgent, OpenAIRealtime
import asyncio

agent = ClawOpsAgent(
    from_="07012341234",  # 발급받은 번호
    session=OpenAIRealtime(
        system_prompt="친절한 고객 상담원입니다. 한국어로 응대합니다.",
        voice="marin",
        language="ko",
    ),
)

asyncio.run(agent.serve())

Node.js / TypeScript

import { ClawOpsAgent, OpenAIRealtime } from '@koreaaitel/sdk/agent';

const agent = new ClawOpsAgent({
  from: '07012341234', // 발급받은 번호
  session: new OpenAIRealtime({
    systemPrompt: '친절한 고객 상담원입니다. 한국어로 응대합니다.',
    voice: 'marin',
    language: 'ko',
  }),
});

await agent.serve();

from (Python: from_) 에 1단계에서 발급받은 번호를 입력하세요. agent.serve()는 에이전트가 한국AI통신 서버에 직접 연결하므로 ngrok 같은 터널링 도구가 필요 없습니다.

실행 후 발급받은 번호로 전화를 걸어보세요. AI가 전화를 받습니다.

3단계: 아웃바운드 전화

에이전트에서 직접 전화를 걸 수도 있습니다.

Python

from clawops.agent import ClawOpsAgent, OpenAIRealtime
import asyncio

agent = ClawOpsAgent(
    from_="07012341234",
    session=OpenAIRealtime(
        system_prompt="예약 확인 전화를 하는 도우미입니다.",
        language="ko",
    ),
)

async def main():
    session = await agent.call("01012345678", timeout=30)
    print(f"발신 중... (call_id: {session.call_id})")
    await session.wait()       # 통화 종료까지 대기
    await agent.disconnect()

asyncio.run(main())

Node.js / TypeScript

import { ClawOpsAgent, OpenAIRealtime } from '@koreaaitel/sdk/agent';

const agent = new ClawOpsAgent({
  from: '07012341234',
  session: new OpenAIRealtime({
    systemPrompt: '예약 확인 전화를 하는 도우미입니다.',
    language: 'ko',
  }),
});

const session = await agent.call('01012345678', { timeout: 30 });
console.log(`발신 중... (callId: ${session.callId})`);
await session.wait();
await agent.disconnect();

인바운드와 아웃바운드를 동시에 처리할 수도 있습니다 (Python):

async def main():
    await agent.connect()                     # 인바운드 수신 시작
    session = await agent.call("01012345678") # 동시에 발신도 가능
    # Ctrl+C로 종료

다음 단계

  • 제공자 호환성 — 검증된 제공자 목록과 SDK별 지원 현황
  • Voice Agent — Tool 등록, Call Transfer, Pipeline 모드, MCP 연동 등 에이전트 심화 기능
  • Python SDK — REST API 전체 메서드 레퍼런스
  • Node.js SDK — REST API 전체 메서드 레퍼런스
  • VoiceML — Webhook 기반 통화 제어 (Say, Gather, Dial 등)
  • Webhook — Status Callback, Message Webhook, 서명 검증
  • Stream — 실시간 음성 스트리밍 연동 가이드

공식 문서와 요금