에이전트 생성

POST

agents

curl --request POST \
  --url https://client-api.tryvox.co/v3/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer support agent"
}
'

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "single_prompt",
  "created_at": 123,
  "updated_at": 123,
  "evaluate": false,
  "production_version": "<string>",
  "data": {
    "runtime": {
      "type": "pipeline"
    },
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1,
      "reasoningEffort": "none",
      "thinkingBudget": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "isAllowInterruption": true,
      "responsiveness": 1,
      "boostedKeywords": "<string>",
      "isAllowTurnDetection": true,
      "vadMinSilenceDuration": 0.5
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfInterruptible": false,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3,
      "callScreening": {
        "promptType": "static",
        "staticSentence": "<string>",
        "prompt": "<string>",
        "endCallAfterResponse": false
      }
    },
    "chatSettings": {
      "silenceChatTimeoutInSeconds": 3600
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "type": "string",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": [
          "recording"
        ]
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "webhookVersion": "v1",
      "enableAlimtalkOnCallEnd": false,
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "takeoverTranscription": true,
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "end_call",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": true,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ],
    "manuals": {}
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "data": {
          "name": "<string>",
          "globalNodeSettings": {
            "isGlobalNode": false,
            "transitionCondition": "<string>"
          },
          "transitions": [
            {
              "id": "<string>",
              "condition": "<string>",
              "isSkipUserResponse": true,
              "isFallback": true,
              "isGlobalTransition": true
            }
          ],
          "firstLineType": "aiFirst",
          "pauseBeforeSpeakingSeconds": 2.5
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "type": "custom",
        "sourceHandle": "<string>"
      }
    ]
  },
  "flow": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "position": {
          "x": 123,
          "y": 123
        },
        "data": {
          "first_line_type": "aiFirst",
          "name": "<string>",
          "pause_before_speaking_seconds": 2.5
        }
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "ai",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "v1",
    "is_production": true,
    "created_at": 123,
    "description": "<string>",
    "manuals_captured_at": 123,
    "manuals_capture_kind": "<string>"
  },
  "head_revision": 123,
  "flow_revision": 123,
  "restored_from_version": "<string>",
  "validation_message": "",
  "validation_issues": [
    {
      "message": "<string>",
      "field": "<string>",
      "code": "<string>",
      "rule": "<string>",
      "node_id": "<string>",
      "impact": "node",
      "suggestion": {},
      "doc": "<string>",
      "details": {}
    }
  ]
}

{
  "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

에이전트 생성 요청 본문입니다. 설정은 data로 보냅니다. flow 에이전트는 권장 경로인 flow로 그래프를 작성하고, 기존 flow_data와 함께 보내면 flow가 우선합니다.

에이전트 생성 요청입니다.

single_prompt는 name만 필수입니다. data를 보내지 않거나 일부만 보내면 서버 기본값으로 채웁니다. flow 에이전트는 flow 필드의 {nodes, edges} 그래프로 작성합니다. deprecated flow_data는 호환용입니다. 그래프를 보내지 않으면 서버 기본 그래프로 채웁니다.

name

string

required

대시보드와 목록 응답에 표시되는 에이전트 이름입니다.

Required string length: 1 - 255

type

enum<string>

default:single_prompt

에이전트 유형입니다. single_prompt는 data를 사용하고, flow는 생성 시 flow_data 그래프가 필요합니다.

Available options:

single_prompt,

flow

data

AgentDataCreate · object | null

에이전트 설정 요청입니다. 구조는 agent-schema/agent-data-create에 공개되어 있으며, 누락되거나 일부만 전달된 값은 서버 기본값과 병합됩니다.

Show child attributes

flow_data

FlowData · object

deprecated

지원 종료 예정 필드입니다. 플로우 그래프를 예전 형식으로 담으며, 기존 호환을 위해 유지됩니다. 새 통합은 flow를 사용하세요. flow 에이전트에서는 선택 항목이며, flow와 flow_data를 함께 보내면 flow가 사용되고 flow_data는 무시됩니다.

Show child attributes

flow

Flow · object | null

flow 에이전트의 플로우 그래프입니다. nodes와 edges로 구성되고, 각 edge가 분기 조건(ai, logic, fallback)을 가집니다. 선택 항목이며, 생략하면 서버가 begin→conversation→endCall 기본 그래프를 만듭니다. flow와 flow_data를 함께 보내면 flow가 사용되고 flow_data는 무시됩니다. 정확한 형태는 flow-schema/flow-data 스키마 엔드포인트에 공개됩니다.

Show child attributes

folder_id

string | null

에이전트를 생성할 폴더입니다. 생략하거나 null이면 워크스페이스 루트에 생성됩니다.

Response

성공 응답

에이전트 생성·수정 응답입니다. AgentResponse에 저장 시 검증 결과인 validation_message와 validation_issues를 포함합니다.

agent_id

string<uuid>

required

에이전트 UUID입니다.

name

string

required

에이전트 이름입니다. 버전 스냅샷을 조회하더라도 현재 최상위 이름을 반환합니다.

type

enum<string>

required

선택한 구성의 타입입니다. single_prompt 또는 flow입니다.

Available options:

single_prompt,

flow

created_at

integer

required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

updated_at

integer

required

리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다.

evaluate

boolean

default:false

현재 평가 설정입니다. 버전 스냅샷에는 포함되지 않습니다.

production_version

string | null

현재 게시된 production 버전입니다. 없으면 null입니다.

data

AgentDataResponse · object

선택된 에이전트 설정 스냅샷입니다. 구조는 agent-schema/agent-data-response에 공개되어 있습니다.

Show child attributes

flow_data

FlowData · object | null

deprecated

지원 종료 예정 필드입니다. 에이전트의 플로우 그래프를 예전 형식으로 담고 있으며, 기존 호환을 위해 유지됩니다. 읽기 전용이고, flow 에이전트에서는 값이 있고 single_prompt 에이전트에서는 null입니다. 새 통합은 flow를 사용하세요. 이 필드는 지원 종료 기간 이후 제거됩니다.

Show child attributes

flow

Flow · object | null

에이전트의 플로우 그래프입니다. nodes를 edges로 연결하고, 각 edge가 분기 조건을 가집니다. flow 에이전트에서는 값이 있고 single_prompt 에이전트에서는 null입니다. 지원 종료 예정인 flow_data 대신 이 필드를 사용하세요. 정확한 형태는 flow-schema/flow-data 스키마 엔드포인트에 공개됩니다.

Show child attributes

version

AgentVersionMeta · object | null

스냅샷 조회 시에만 populated (version=v{n} 또는 production).

Show child attributes

head_revision

integer | null

현재 편집본의 리비전입니다. 고정 버전을 조회하면 null입니다.

flow_revision

integer | null

현재 Flow 리비전입니다. 프롬프트 에이전트이거나 고정 버전을 조회하면 null입니다.

restored_from_version

string | null

validation_message

string

default:""

저장 시 발생한 플로우 경고를 줄바꿈으로 구분한 요약입니다. 경고가 없으면 빈 문자열입니다. 생성·수정 응답에만 포함되며, GET 응답은 이 필드가 없는 AgentResponse를 사용합니다.

validation_issues

FlowValidationErrorItem · object[]

저장 시 검증 결과입니다. 규칙, 노드 ID, 영향 범위와 세부 정보를 포함합니다.

Show child attributes

curl --request POST \
  --url https://client-api.tryvox.co/v3/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer support agent"
}
'

{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "single_prompt",
  "created_at": 123,
  "updated_at": 123,
  "evaluate": false,
  "production_version": "<string>",
  "data": {
    "runtime": {
      "type": "pipeline"
    },
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1,
      "reasoningEffort": "none",
      "thinkingBudget": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "isAllowInterruption": true,
      "responsiveness": 1,
      "boostedKeywords": "<string>",
      "isAllowTurnDetection": true,
      "vadMinSilenceDuration": 0.5
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfInterruptible": false,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3,
      "callScreening": {
        "promptType": "static",
        "staticSentence": "<string>",
        "prompt": "<string>",
        "endCallAfterResponse": false
      }
    },
    "chatSettings": {
      "silenceChatTimeoutInSeconds": 3600
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "type": "string",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": [
          "recording"
        ]
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "webhookVersion": "v1",
      "enableAlimtalkOnCallEnd": false,
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "takeoverTranscription": true,
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "end_call",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": true,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ],
    "manuals": {}
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "data": {
          "name": "<string>",
          "globalNodeSettings": {
            "isGlobalNode": false,
            "transitionCondition": "<string>"
          },
          "transitions": [
            {
              "id": "<string>",
              "condition": "<string>",
              "isSkipUserResponse": true,
              "isFallback": true,
              "isGlobalTransition": true
            }
          ],
          "firstLineType": "aiFirst",
          "pauseBeforeSpeakingSeconds": 2.5
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "type": "custom",
        "sourceHandle": "<string>"
      }
    ]
  },
  "flow": {
    "nodes": [
      {
        "id": "<string>",
        "type": "begin",
        "position": {
          "x": 123,
          "y": 123
        },
        "data": {
          "first_line_type": "aiFirst",
          "name": "<string>",
          "pause_before_speaking_seconds": 2.5
        }
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "ai",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "v1",
    "is_production": true,
    "created_at": 123,
    "description": "<string>",
    "manuals_captured_at": 123,
    "manuals_capture_kind": "<string>"
  },
  "head_revision": 123,
  "flow_revision": 123,
  "restored_from_version": "<string>",
  "validation_message": "",
  "validation_issues": [
    {
      "message": "<string>",
      "field": "<string>",
      "code": "<string>",
      "rule": "<string>",
      "node_id": "<string>",
      "impact": "node",
      "suggestion": {},
      "doc": "<string>",
      "details": {}
    }
  ]
}

{
  "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