입력폼 제출 API

4 분 읽기가이드 기준일: 2026. 10. 14.노션 원문 보기 ↗

목적

이 API는 대화형 답변 생성 API 응답에 포함된 입력폼 데이터를 제출할 때 사용합니다.

입력폼 제출 시 사용자 입력값을 저장하고, 이후 후속 에이전트 작업이 있으면 자동으로 이어서 실행합니다.

따라서 이 API의 응답으로 일반 텍스트 답변, 추가 입력폼, 카드형 응답, 페이지 이동 데이터 등이 반환될 수 있습니다.

URL

HTTP 메서드

Plain Text

POST

헤더

헤더	값	설명
Content-Type	application/json	요청 본문이 JSON 형식임을 나타냅니다.
Authorization	Bearer <api_key>	Sidetalk 대시보드에서 설치하기 메뉴에 제공된 API 키를 사용하세요.

본문

파라미터	타입	필수	설명
sessionId	String	예	대화 세션을 구분하는 고유 키(Key)입니다. 입력폼 제출 내역을 같은 사용자 흐름과 연결하려면 동일한 값을 유지해야 합니다.
chat_log_uuid	String	아니요	해당 입력폼이 연결된 대화 로그 UUID입니다.
message	String	아니요	입력폼 제출 후 후속 답변 생성에 사용할 메시지입니다. 지정하지 않으면 기본 메시지로 처리될 수 있습니다.
stream	Boolean	아니요	응답을 스트림으로 받을지 여부를 지정합니다. `true` 또는 `false`. 지정하지 않으면 기본값 `false`가 사용됩니다.
inputForm	Object	예	입력폼 제출 데이터 객체입니다.

inputForm 객체

파라미터	타입	필수	설명
form_id	String 또는 Number	예	제출할 입력폼 ID입니다.
task_id	String	아니요	해당 입력폼이 연결된 작업 ID입니다.
order	Number	아니요	작업 내 액션 순서입니다.
original_chat_log_uuid	String	아니요	입력폼이 처음 표시된 대화 로그 UUID입니다.
executionHistory	Array	아니요	이전 에이전트 실행 이력입니다.
form_data	Object	예	사용자가 입력한 필드 값입니다. 각 key는 입력폼 정의의 `field_id` 와 동일해야 합니다.

form_data 예시

JSON

{
  "customer_name": "홍길동",
  "customer_phone": "01012345678",
  "customer_email": "test@example.com"
}

요청 예시

JSON

curl -X POST https://api.sidetalk.ai/v1/chat/input-forms/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "sessionId": "test-session-id",
    "chat_log_uuid": "2b9cc8fb-3cc6-4d40-aef6-d44af3d074f3",
    "message": "입력폼 제출",
    "stream": false,
    "inputForm": {
      "form_id": 101,
      "task_id": "task_101",
      "order": 1,
      "original_chat_log_uuid": "2b9cc8fb-3cc6-4d40-aef6-d44af3d074f3",
      "executionHistory": [],
      "form_data": {
        "customer_name": "홍길동",
        "customer_phone": "01012345678"
      }
    }
  }'

응답 형식

응답 형식은 대화형 답변 생성 API와 동일합니다.

stream: true 인 경우 SSE(Server-Sent Events) 형식으로 반환됩니다.
stream: false 인 경우 JSON 형식으로 반환됩니다.

후속 작업 결과에 따라 일반 텍스트 답변, 추가 입력폼, 카드형 응답, 페이지 이동 데이터 등이 반환될 수 있습니다.

입력값 저장 방식

입력폼 제출 시 입력값은 먼저 저장됩니다.

입력폼에 연결된 테이블이 있으면 해당 테이블에 저장됩니다.
입력폼에 연결된 테이블이 없으면 제출 내용이 내부 채팅 로그에 저장될 수 있습니다.

즉 이 API는 단순 저장 API가 아니라, 입력값 저장 후 후속 답변 생성까지 함께 처리하는 API입니다.