Numbers API

번호에 걸린 agent 바인딩을 조회·수정하는 REST 엔드포인트 레퍼런스.

베이스 URL과 인증

베이스 URL

https://vox-gateway-prod.fly.dev

Calls API와 같은 번호 API 키를 씁니다 — 따로 발급받을 키도, 권한 설정도 없습니다. 키가 곧 번호라, 그 키로 고칠 수 있는 번호는 자기 번호 하나입니다.

Authorization: Bearer tg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

경로에 번호를 넣지 않습니다 — 발신에 발신 번호 입력란이 없는 것과 같은 이유입니다. 응답의 number_id · phone으로 어느 번호가 바뀌었는지 확인하세요.

오류는 {"error": "코드", ...} 봉투이고, 어떤 코드가 어느 상태로 오는지는 에러 코드에 모아 뒀습니다.

바인딩 객체

이 번호의 통화를 누가 대화하는가를 정하는 값입니다. 수신(inbound)과 발신(outbound)이 각각 따로 있고, 콘솔 번호 상세의 인바운드 · 아웃바운드 탭과 같은 값을 봅니다 — 어느 쪽에서 고쳐도 다른 쪽에 그대로 보입니다.

필드	타입	설명
`agent_type`	string	대화를 맡을 agent의 종류 (아래 표).
`chat_url`	string	자체 Agent의 엔드포인트. https만 받습니다. 내장 Agent면 null입니다.
`assistant_id`	string	LangGraph 그래프명 · Mastra agent id. 그 밖의 유형에서는 null로 정리됩니다.
`has_token`	boolean	아웃바운드 전용. 요청 인증 토큰이 저장돼 있는지 여부입니다 — 토큰 값 자체는 어떤 응답에도 실리지 않습니다.
`number_id` · `phone`	string	이 키가 가리키는 번호. 경로에 넣지 않으므로 응답이 알려줍니다.

바뀐 바인딩은 다음 통화부터 적용됩니다. 진행 중인 통화는 시작 시점의 설정을 그대로 끝까지 씁니다.

무엇	수신 agent_type	발신 agent_type
내장 Agent	`playground`	`platform`
일반 webhook	`webhook`	`webhook`
OpenAI 호환	`openai_compatible`	`openai_compatible`
n8n	`n8n`	`n8n`
LangGraph	`langgraph`	`langgraph`
Mastra	`mastra`	`mastra`

같은 내장 Agent인데 방향마다 코드값이 다릅니다 — 수신은 playground, 발신은 platform입니다. 각 유형의 연결 규격은 자체 Agent 연동 문서에 있습니다.

GET /api/v1/number/inbound

이 번호가 수신 통화를 누구에게 넘기는지 조회합니다.

요청

curl https://vox-gateway-prod.fly.dev/api/v1/number/inbound \
  -H "Authorization: Bearer $VOX_API_KEY"

성공 응답

200 OK
{
  "number_id": "8b2e…",
  "phone": "07079193558",
  "agent_type": "mastra",
  "chat_url": "https://agent.example.com/api/agents/support",
  "assistant_id": null
}

PATCH /api/v1/number/inbound

보낸 필드만 바꿉니다. 안 보낸 필드는 그대로 남습니다 — 엔드포인트만 옮길 때 유형을 다시 적을 필요가 없습니다.

필드	타입	필수	설명
`agent_type`	string	아니오	위 표의 수신 유형. 한 번도 설정한 적 없는 번호라면 이 필드를 함께 보내야 합니다 — 엔드포인트만으로는 어느 규격으로 부를지 정할 수 없습니다.
`chat_url`	string	아니오	자체 Agent 엔드포인트(https). null을 보내면 지웁니다.
`assistant_id`	string	아니오	LangGraph 그래프명. 그 밖의 유형이면 저장 시 null로 정리됩니다.

발신자 인증(화이트리스트 · 핸드셰이크)과 내장 Agent 수신 지침은 이 API로 바꿀 수 없습니다 — 콘솔 번호 상세에서 다룹니다.

요청

curl -X PATCH https://vox-gateway-prod.fly.dev/api/v1/number/inbound \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chat_url": "https://staging.example.com/api/agents/support"}'

응답은 GET과 같은 형태입니다. 모르는 필드를 보내면 400 invalid_request_body이고 아무것도 저장되지 않습니다 — 오타 난 필드를 조용히 무시하면 바인딩이 옛 agent를 가리킨 채 다음 통화가 그리로 가기 때문입니다.

GET /api/v1/number/outbound

이 번호로 거는 통화를 누가 대화하는지 조회합니다. 설정한 적이 없으면 platform(내장 Agent)입니다.

성공 응답

200 OK
{
  "number_id": "8b2e…",
  "phone": "07079193558",
  "agent_type": "platform",
  "chat_url": null,
  "assistant_id": null,
  "has_token": false
}

PATCH /api/v1/number/outbound

필드	타입	필수	설명
`agent_type`	string	아니오	위 표의 발신 유형. platform이 아니면 chat_url이 반드시 있어야 저장됩니다.
`chat_url`	string	아니오	자체 Agent 엔드포인트(https). agent_type을 platform으로 바꾸면 쓰이지 않으므로 함께 지워집니다.
`assistant_id`	string	아니오	LangGraph 그래프명 · Mastra agent id. 그 밖의 유형이면 null로 정리됩니다.
`agent_token`	string	아니오	우리가 그쪽 agent를 부를 때 실을 Bearer 토큰. 보내지 않으면 저장된 값을 유지하고, 빈 문자열을 보내면 지웁니다. 응답에는 has_token만 나옵니다.

요청

curl -X PATCH https://vox-gateway-prod.fly.dev/api/v1/number/outbound \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_type": "mastra", "chat_url": "https://agent.example.com/api/agents/sales", "assistant_id": "sales"}'

내장 Agent로 되돌리려면 {"agent_type": "platform"} 하나만 보내면 됩니다 — 남아 있던 chat_url은 함께 지워집니다.
자체 Agent 유형인데 chat_url이 없는 상태로는 저장되지 않습니다. 발신 시점에 거절되는 대신 저장 시점에 막습니다.

거절 사유는 에러 코드에 모아 두었습니다.