채팅 생성
프롬프트 또는 플로우 에이전트로 API 채팅을 생성합니다. 저장된 첫 대화 내역을 함께 반환합니다.
curl --request POST \
--url https://client-api.tryvox.co/v3/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"agent": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
"agent_version": "current"
},
"dynamic_variables": {
"customer_name": "홍길동"
},
"metadata": {
"crm_session_id": "session_a1b2c3"
},
"external_id": "customer_123"
}
'import requests
url = "https://client-api.tryvox.co/v3/chats"
payload = {
"agent": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
"agent_version": "current"
},
"dynamic_variables": { "customer_name": "홍길동" },
"metadata": { "crm_session_id": "session_a1b2c3" },
"external_id": "customer_123"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
agent: {agent_id: '7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a', agent_version: 'current'},
dynamic_variables: {customer_name: '홍길동'},
metadata: {crm_session_id: 'session_a1b2c3'},
external_id: 'customer_123'
})
};
fetch('https://client-api.tryvox.co/v3/chats', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-api.tryvox.co/v3/chats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent' => [
'agent_id' => '7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a',
'agent_version' => 'current'
],
'dynamic_variables' => [
'customer_name' => '홍길동'
],
'metadata' => [
'crm_session_id' => 'session_a1b2c3'
],
'external_id' => 'customer_123'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-api.tryvox.co/v3/chats"
payload := strings.NewReader("{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-api.tryvox.co/v3/chats")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-api.tryvox.co/v3/chats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent": {
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_version": "current"
},
"channel": "<string>",
"status": "active",
"responder": {
"type": "ai",
"operator": {
"member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"since": 123
},
"metadata": {},
"dynamic_variables": {},
"start_at": 123,
"end_at": 123,
"chat_analysis": {
"summary": "<string>",
"user_sentiment": "positive",
"custom_analysis_data": [
{}
]
},
"chat_cost": {
"total_cost": "<string>"
},
"transcript": [
{
"id": 123,
"role": "user",
"author": "customer",
"content": "<string>",
"created_at": 123,
"attachments": [
{
"file_key": "<string>",
"mime_type": "<string>"
}
],
"client_idempotency_key": "<string>"
}
],
"provider_responder": "ai"
}{
"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": "AGENT_NOT_FOUND",
"message": "에이전트를 찾을 수 없습니다.",
"details": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a"
}
}
}{
"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
워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.
Headers
상태를 변경하는 POST 요청에 필요한 멱등성 키입니다. 24시간 동안 안전하게 재시도할 때 사용합니다. 값은 비어 있으면 안 됩니다. 최대 255자까지 허용합니다.
1 - 255Body
채팅을 처리할 에이전트와 초기 설정입니다.
agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.
Show child attributes
Show child attributes
저장용 메타데이터입니다. 에이전트 처리에는 사용하지 않습니다.
에이전트 프롬프트에 주입할 동적 변수입니다.
고객사 서비스에서 사용하는 고객 식별자입니다. 지정하면 해당 식별자의 고객을 찾거나 생성해 채팅에 연결합니다.
1 - 255이 채팅의 첫 안내 메시지입니다. 지정하면 에이전트의 첫 메시지 설정보다 우선합니다. 에이전트는 첫 사용자 입력부터 실행합니다.
1Response
성공 응답
채팅 ID입니다.
연결된 고객의 UUID입니다. 고객 식별자를 생략해도 익명 고객을 생성합니다. 고객 연결이 없으면 null일 수 있습니다.
agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.
Show child attributes
Show child attributes
채팅 채널입니다. 현재 api, widget, sms, kakao를 지원하며 등록된 채널 이름을 그대로 반환합니다.
^[a-z][a-z0-9_]{0,31}$채팅 상태입니다.
active, ended 현재 응답 주체입니다. AI, 상담사, 외부 채널 가운데 어느 쪽이 응답 중인지 확인합니다.
Show child attributes
Show child attributes
생성 시 전달한 저장용 메타데이터입니다.
생성 시 전달한 동적 변수입니다.
채팅 시작 시각입니다. 밀리초 단위 Unix 타임스탬프입니다.
채팅 종료 시각입니다. 밀리초 단위 Unix 타임스탬프이며 진행 중에는 null입니다.
대화 종료 후 분석 결과입니다. 분석 완료 전에는 null 입니다.
Show child attributes
Show child attributes
확정된 Chat AI 사용료입니다. active 상태이거나 전체 비용을 확정할 수 없으면 null입니다.
Show child attributes
Show child attributes
채팅 대화록입니다. user/agent 메시지와 tool_call_invocation/tool_call_result 항목을 순서대로 포함합니다.
- ChatTranscriptMessageResponse
- ChatToolCallInvocationResponse
- ChatToolCallResultResponse
Show child attributes
Show child attributes
외부 채널 응대권의 조회 시점 상태입니다. 채널 원장에서 계산하며 별도로 저장하지 않습니다.
ai, external, unknown Was this page helpful?
curl --request POST \
--url https://client-api.tryvox.co/v3/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"agent": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
"agent_version": "current"
},
"dynamic_variables": {
"customer_name": "홍길동"
},
"metadata": {
"crm_session_id": "session_a1b2c3"
},
"external_id": "customer_123"
}
'import requests
url = "https://client-api.tryvox.co/v3/chats"
payload = {
"agent": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a",
"agent_version": "current"
},
"dynamic_variables": { "customer_name": "홍길동" },
"metadata": { "crm_session_id": "session_a1b2c3" },
"external_id": "customer_123"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
agent: {agent_id: '7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a', agent_version: 'current'},
dynamic_variables: {customer_name: '홍길동'},
metadata: {crm_session_id: 'session_a1b2c3'},
external_id: 'customer_123'
})
};
fetch('https://client-api.tryvox.co/v3/chats', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://client-api.tryvox.co/v3/chats",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent' => [
'agent_id' => '7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a',
'agent_version' => 'current'
],
'dynamic_variables' => [
'customer_name' => '홍길동'
],
'metadata' => [
'crm_session_id' => 'session_a1b2c3'
],
'external_id' => 'customer_123'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://client-api.tryvox.co/v3/chats"
payload := strings.NewReader("{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://client-api.tryvox.co/v3/chats")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-api.tryvox.co/v3/chats")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent\": {\n \"agent_id\": \"7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a\",\n \"agent_version\": \"current\"\n },\n \"dynamic_variables\": {\n \"customer_name\": \"홍길동\"\n },\n \"metadata\": {\n \"crm_session_id\": \"session_a1b2c3\"\n },\n \"external_id\": \"customer_123\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent": {
"agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent_version": "current"
},
"channel": "<string>",
"status": "active",
"responder": {
"type": "ai",
"operator": {
"member_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"since": 123
},
"metadata": {},
"dynamic_variables": {},
"start_at": 123,
"end_at": 123,
"chat_analysis": {
"summary": "<string>",
"user_sentiment": "positive",
"custom_analysis_data": [
{}
]
},
"chat_cost": {
"total_cost": "<string>"
},
"transcript": [
{
"id": 123,
"role": "user",
"author": "customer",
"content": "<string>",
"created_at": 123,
"attachments": [
{
"file_key": "<string>",
"mime_type": "<string>"
}
],
"client_idempotency_key": "<string>"
}
],
"provider_responder": "ai"
}{
"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": "AGENT_NOT_FOUND",
"message": "에이전트를 찾을 수 없습니다.",
"details": {
"agent_id": "7f3e9c12-4a8b-4d5e-9f1a-2b3c4d5e6f7a"
}
}
}{
"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": {}
}
}