에이전트 생성

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>",
  "created_at": 123,
  "updated_at": 123,
  "production_version": "<string>",
  "data": {
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "responsiveness": 1,
      "boostedKeywords": "<string>"
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": []
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "<string>",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": false,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ]
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "<string>",
        "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": "<string>",
        "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": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "<string>",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "<string>",
    "is_production": true,
    "created_at": 123,
    "description": "<string>"
  },
  "validation_message": ""
}

{
  "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": 5,
      "window_seconds": 1
    }
  }
}

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

성공 응답

create/update 응답입니다. AgentResponse와 flow validator 메시지를 함께 반환합니다.

validation_message는 schema 검증을 통과해 200/201로 저장된 요청의 flow_data validator warning을 줄바꿈으로 합친 요약 문자열입니다. warning이 없거나 single_prompt 에이전트이면 빈 문자열입니다. Tier 3 reject 케이스는 400으로 처리하므로 이 필드에는 포함되지 않습니다.

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 형식입니다.

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

validation_message

string

default:""

flow_data validator 가 발견한 warning 들의 줄바꿈 구분 요약. warning 이 없거나 single_prompt 에이전트면 빈 문자열.

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>",
  "created_at": 123,
  "updated_at": 123,
  "production_version": "<string>",
  "data": {
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "responsiveness": 1,
      "boostedKeywords": "<string>"
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false,
      "dataRetention": {
        "durationSeconds": 157788000,
        "retainedDataTypes": []
      },
      "piiMasking": {
        "enabled": false,
        "name": false,
        "phone": false,
        "birthDate": false,
        "address": false,
        "email": false,
        "residentId": false
      }
    },
    "memory": {
      "enabled": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "<string>",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        },
        "allowInterruptionDuringExecution": false,
        "responseMode": "wait",
        "name": "end_call",
        "description": "<string>"
      }
    ]
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "<string>",
        "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": "<string>",
        "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": [
      {
        "source": "<string>",
        "target": "<string>",
        "condition": {
          "type": "<string>",
          "prompt": ""
        },
        "id": "<string>",
        "skip_user_response": false
      }
    ]
  },
  "version": {
    "version": "<string>",
    "is_production": true,
    "created_at": 123,
    "description": "<string>"
  },
  "validation_message": ""
}

{
  "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": 5,
      "window_seconds": 1
    }
  }
}

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

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

에이전트

에이전트 버전

통화

캠페인

보유 전화번호

발신표기번호

차단 번호

전화번호 자원

도구

스키마

지식 베이스

모델

고객

고객 속성 정의

메모리

알림

SMS

파일

조직

하위 조직 API 키

조직 인증

Authorizations

Body

Response