통화 생성

POST

calls

curl --request POST \
  --url https://client-api.tryvox.co/v3/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_number": "07011112222",
  "to_number": "01012345678",
  "agent": {
    "agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
    "agent_version": "current"
  },
  "dynamic_variables": {
    "customer_name": "홍길동",
    "appointment_at": "2026-05-10 14:00"
  },
  "metadata": {
    "crm_lead_id": "lead_a1b2c3"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_version": "current"
  },
  "call_type": "web",
  "status": "queued",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaign_id": "<string>",
  "from_number": "<string>",
  "to_number": "<string>",
  "presentation_number": "<string>",
  "disconnection_reason": "user_hangup",
  "start_at": 123,
  "end_at": 123,
  "recording_url": "<string>",
  "metadata": {},
  "dynamic_variables": {},
  "call_analysis": {
    "summary": "<string>",
    "user_sentiment": "positive",
    "custom_analysis_data": [
      {}
    ]
  },
  "call_cost": {
    "total_cost": "<string>"
  },
  "variant_label": "<string>",
  "opt_out_sensitive_data_storage": false,
  "transcript": [
    {}
  ],
  "takeover": {
    "takeover_id": "<string>",
    "status": "<string>",
    "source": "<string>",
    "mode": "<string>",
    "operator": {
      "member_id": "<string>",
      "name": "<string>",
      "external_id": "<string>"
    },
    "requested_at": 123,
    "connected_at": 123,
    "ended_at": 123,
    "operator_call_id": "<string>"
  },
  "segments": [
    {
      "mode": "<string>",
      "started_at": 123,
      "ended_at": 123
    }
  ],
  "handled_by": "<string>"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

조직 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Body

application/json

아웃바운드 통화 생성 요청입니다. 에이전트를 직접 지정하려면 agent를 보냅니다. 발신 번호에 활성 traffic split 정책이 있으면 agent를 생략합니다.

v3 아웃바운드 통화 생성 요청.

from_number

string

required

발신 번호. 하이픈 없는 국내 번호 (예: '01012345678'). libphonenumber 검증.

to_number

string

required

수신 번호. 하이픈 없는 국내 번호 (예: '01098765432').

agent

AgentMapping · object | null

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

Show child attributes

metadata

Metadata · object

자유 형식 메타데이터입니다. 응답에서 그대로 반환합니다.

dynamic_variables

Dynamic Variables · object

에이전트 프롬프트에 주입할 동적 변수. {{변수명}} 치환.

presentation_number

string | null

수신자에게 표시할 번호. 조직 승인 번호만 허용. 미지정은 null.

Response

성공 응답

v3 단건 통화 응답. transcript 포함.

AI 원장 순수성 (Operator-Call Split §7.1): 이 응답은 AI 구간만 담는다 — transcript/analysis에 operator 발화는 구조적으로 없다. 사람 상담 구간은 operator-control이 소유한다. takeover.operator_call_id는 그 구간의 opaque join key이며, 이 API의 조회 path가 아니다.

string<uuid>

required

통화의 고유 식별자입니다.

agent

AgentMapping · object

required

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

Show child attributes

call_type

enum<string>

required

통화 유형. 'web'/'phone'/'inbound'/'outbound'/'api' 중 하나.

Available options:

web,

phone,

inbound,

outbound,

api

status

enum<string>

required

통화 상태입니다. 값 의미와 전이 규칙은 CallStatusV3Enum 정의를 참고합니다.

Available options:

queued,

ongoing,

ended,

error,

canceled,

not_connected

customer_id

string<uuid> | null

서버가 귀속한 고객 UUID입니다. 아직 고객 귀속이 완료되지 않았거나 귀속 대상이 없으면 null입니다.

campaign_id

string | null

통화가 속한 캠페인의 정수 문자열 id. 캠페인 미소속이면 null입니다.

from_number

string | null

발신 번호. 하이픈 없는 국내 번호 (예: '01012345678'). 웹 통화 등은 null.

to_number

string | null

수신 번호. 하이픈 없는 국내 번호.

presentation_number

string | null

수신자에게 표시할 발신 번호. 조직이 사전 등록·승인한 번호 (telephone_presentation_numbers). 미지정 시 null.

disconnection_reason

enum<string> | null

통화 종료 사유. 진행 중이면 null.

Available options:

user_hangup,

agent_hangup,

dial_no_answer,

dial_failed,

dial_busy,

voicemail_reached,

concurrency_limit_reached,

insufficient_balance,

error_voxai,

max_duration_reached,

inactivity,

flow_error,

call_transfer,

orphaned_no_agent_pickup,

dial_declined,

daily_call_limit_reached,

hourly_call_limit_reached,

blocked_number,

operator_hangup

start_at

integer | null

통화가 시작된 시각 (unix ms). 통화가 아직 시작되지 않았으면 null.

end_at

integer | null

통화가 종료된 시각 (unix ms). 통화가 아직 종료되지 않았으면 null.

recording_url

string | null

녹음 파일 URL. 녹음 없거나 옵트아웃이면 null.

metadata

Metadata · object

요청 시 전달된 정적 메타데이터를 그대로 반환합니다.

dynamic_variables

Dynamic Variables · object

요청 시 전달된 동적 변수를 그대로 반환합니다.

call_analysis

CallV3AnalysisDto · object | null

통화 분석 결과입니다(요약, 감정, 사용자 정의 분석). 분석 완료 전에는 null입니다.

Show child attributes

call_cost

CallV3CostDto · object | null

통화 비용입니다(KRW 원 단위, Decimal 문자열). 계산 완료 전에는 null입니다.

Show child attributes

variant_label

string | null

Traffic split variant label. Split 미사용/우회/폴백 통화는 null.

opt_out_sensitive_data_storage

boolean

default:false

민감정보 저장 거부 여부. true면 transcript/recording/analysis null.

transcript

Transcript · object[] | null

통화 대화록 (통합 리스트, AI 구간 전용). 항목 role 3종:

'agent'/'user': {role, content, start_at?, end_at?}
'tool_call_invocation': {role, tool_call_id, name, arguments}
'tool_call_result': {role, tool_call_id, content} 옵트아웃 시 null.

takeover

CallTakeoverBlockDto · object | null

이어받기 블록. call_transfer와 matching operator web relation으로 파생. 사람 구간 대화/지표는 이 응답에 없다. operator_call_id는 operator-control 원장의 opaque join key이며 api-server public path가 아니다.

Show child attributes

segments

CallSegmentDto · object[] | null

통화 구간 목록 (mode 'ai'|'human'). 이어받기 없는 콜은 ai 1구간. hold gap(dormancy→COMMIT)은 구간 사이 공백으로 표현.

Show child attributes

handled_by

string | null

'ai' | 'operator'. matching committed operator call 존재로 파생하며 bare call_transfer는 operator로 분류하지 않음. null이면 판정 불가(attribution 조회 일시 실패) — 정본은 operator call 리소스이므로 재조회로 복원 가능.

curl --request POST \
  --url https://client-api.tryvox.co/v3/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_number": "07011112222",
  "to_number": "01012345678",
  "agent": {
    "agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
    "agent_version": "current"
  },
  "dynamic_variables": {
    "customer_name": "홍길동",
    "appointment_at": "2026-05-10 14:00"
  },
  "metadata": {
    "crm_lead_id": "lead_a1b2c3"
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_version": "current"
  },
  "call_type": "web",
  "status": "queued",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "campaign_id": "<string>",
  "from_number": "<string>",
  "to_number": "<string>",
  "presentation_number": "<string>",
  "disconnection_reason": "user_hangup",
  "start_at": 123,
  "end_at": 123,
  "recording_url": "<string>",
  "metadata": {},
  "dynamic_variables": {},
  "call_analysis": {
    "summary": "<string>",
    "user_sentiment": "positive",
    "custom_analysis_data": [
      {}
    ]
  },
  "call_cost": {
    "total_cost": "<string>"
  },
  "variant_label": "<string>",
  "opt_out_sensitive_data_storage": false,
  "transcript": [
    {}
  ],
  "takeover": {
    "takeover_id": "<string>",
    "status": "<string>",
    "source": "<string>",
    "mode": "<string>",
    "operator": {
      "member_id": "<string>",
      "name": "<string>",
      "external_id": "<string>"
    },
    "requested_at": 123,
    "connected_at": 123,
    "ended_at": 123,
    "operator_call_id": "<string>"
  },
  "segments": [
    {
      "mode": "<string>",
      "started_at": 123,
      "ended_at": 123
    }
  ],
  "handled_by": "<string>"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

통화

상담사 통화

에이전트

에이전트 버전

도구

지식 베이스

메뉴얼

모델

스키마

보유 전화번호

전화번호 자원

발신표기번호

차단 번호

캠페인

시트

위젯

SMS

네이버톡톡

파일

고객

고객 속성 정의

메모리

알림

조직

하위 조직 API 키

조직 인증

Authorizations

Body

Response