Skip to main content
채팅 인바운드 웹훅은 카카오톡, 문자 같은 연결된 채널로 고객이 보낸 메시지가 새 채팅을 열면, 채널과 고객을 구분하는 값을 내 서버로 보내고 서버가 돌려준 값을 그 채팅의 동적 변수와 메타데이터로 넣어요. 채널로 먼저 연락한 고객의 회원 정보를 첫 답변부터 쓰게 할 수 있어요. 전화는 인바운드 웹훅이 같은 일을 해요. API(POST /v3/chats), 문자 발신 시작(POST /v3/chats/sms), 위젯으로 만드는 채팅에는 요청을 보내지 않아요. 이 채팅에는 만들 때 넣은 dynamic_variables, metadata를 써요.

채팅 인바운드 웹훅 연결하기

1

수신 서버 만들기

아래 요청과 응답 형식대로 답하는 HTTPS 엔드포인트를 준비하세요. 예시는 서버 구현 예시에 있어요.
2

채팅 인바운드 웹훅 URL 넣기

에이전트 설정의 웹훅 설정을 열고 채팅 인바운드 웹훅 URL에 엔드포인트를 넣은 뒤 저장하세요. API로는 에이전트의 data.webhookSettings.inboundChatWebhookUrl에 넣어요. URL은 https://만 저장되고, URL 자체에는 동적 변수를 쓸 수 없어요.
3

프롬프트에 변수 넣기

응답의 dynamic_variables 키와 같은 이름으로 프롬프트에 {{변수명}}을 넣으세요. 첫 답변을 만들 때 값으로 바뀌어요.
4

실제 채팅으로 확인하기

curl로 먼저 시험한 뒤 연결한 채널로 메시지를 보내 새 채팅을 열고 변수가 제대로 들어갔는지 보세요.
URL을 저장한 에이전트 버전으로 새로 시작하는 채팅부터 요청을 보내요. 이미 진행 중인 채팅에는 보내지 않아요.

요청과 응답

채널로 받은 메시지가 새 채팅을 열면 vox.ai가 채팅 하나에 한 번, 아래 JSON 본문으로 POST 요청을 보내요. 필드는 항상 이 다섯 개이고, 해당하지 않는 값은 null이에요.
  • channel: 채팅이 들어온 채널이에요. sms, kakao, navertalk, instagram, line, wechat, channeltalk 가운데 하나예요.
  • chat_channel_id: 채팅 조회 API에 나오는 채팅 채널 ID와 같은 값이에요. 등록하지 않은 문자 채널은 null이에요.
  • widget_id: 위젯 채팅에는 요청을 보내지 않으므로 지금은 항상 null이에요.
  • agent: 응대할 에이전트예요. agent_version은 채팅 웹훅과 같은 형식으로 v{n}이나 current예요.
  • channel_user_id: 그 채널에서 고객을 구분하는 값이에요. 문자는 고객 전화번호, 채널톡은 user_chat_id, 다른 메신저는 그 채널의 이용자 키예요.
응답 JSON은 아래 구조를 따라야 해요.
  • dynamic_variables: 프롬프트의 {{변수명}}에 들어갈 키와 값이에요.
  • metadata: 프롬프트에는 들어가지 않고 채팅의 메타데이터로 저장돼요. 채팅 조회 API와 chat_started, chat_ended, chat_analyzed 채팅 웹훅에서 그대로 읽을 수 있어요. 메시지 이벤트 웹훅에는 실리지 않아요.
  • 값이 없을 때: 해당 고객이 없으면 chat_inbound를 빼거나 {"chat_inbound": {"dynamic_variables": {}}}처럼 빈 객체로 답하세요. 두 필드는 따로 읽고, 객체가 아닌 필드는 쓰지 않아요.

응답 제한

  • 시간: vox.ai가 이 채팅의 웹훅 처리를 시작한 때부터 응답 본문을 다 받을 때까지 5초 안에 끝나야 해요. 요청 준비, 주소 조회, 연결 시간도 이 5초에 들어가므로 서버가 쓸 수 있는 시간은 5초보다 짧아요. 연결 단계에서 시간이 초과되면 한 번만 다시 시도하고, 그 밖에는 다시 보내지 않아요.
  • 크기: 응답 본문은 64KB까지만 읽어요.
  • 상태 코드: 2xx 응답만 값으로 써요. 리다이렉트(3xx)는 따라가지 않아요.

서버 구현 예시

채팅에서 일어나는 일

  • 첫 답변은 응답을 받은 뒤에 나가요. 에이전트의 첫 답변은 웹훅 응답이 오거나 5초가 지난 뒤에 만들어요. 그래서 첫 답변이 최대 5초 늦어질 수 있어요.
  • 채팅 웹훅도 그 뒤에 보내요. 그 채팅의 채팅 웹훅은 웹훅이 끝난 뒤 chat_started부터 보낼 순서를 잡고, chat_started에 합친 값이 실려요. 서로 다른 요청이 내 서버에 도착하는 순서는 네트워크에 따라 달라질 수 있어요. 첫 채팅 웹훅은 이전보다 최대 약 11초 늦게 도착할 수 있어요.
  • 채팅은 바로 저장돼요. 채팅과 첫 메시지는 웹훅을 기다리지 않고 저장돼요. 그래서 웹훅이 끝나기 전에는 대시보드와 채팅 조회 API에서 동적 변수와 메타데이터가 비어 보일 수 있어요.
  • 실패하면 값 없이 이어가요. 시간 초과, 2xx가 아닌 응답, 64KB를 넘는 본문, 형식 오류는 웹훅 값 없이 채팅을 이어가요. 5초가 지나 늦게 온 응답의 값은 쓰지 않아요.
  • 상담사가 맡은 채팅도 보내요. 상담사가 응대하거나 AI 응답을 끈 채로 시작한 채팅에도 요청을 보내요. 나중에 AI가 맡으면 그때 저장된 값을 써요.

보안

HMAC 서명 검증

에이전트 설정의 인바운드 웹훅 서명이 켜져 있고 워크스페이스에 웹훅 서명 키가 있으면 채팅 인바운드 웹훅 요청에 HMAC-SHA256 서명 헤더가 붙어요. 이 스위치는 인바운드 웹훅과 같이 쓰고, 기본값은 꺼짐이에요. 서명 키와 검증 방식은 워크스페이스 단위 웹훅의 HMAC-SHA256 서명과 같아요. 서명 키는 대시보드 설정 > 웹훅에서 발급해요.

엔드포인트 쪽 추가 방어

  • 자체 토큰: URL 경로나 쿼리에 비밀 토큰을 넣고 서버에서 검증하세요. 예: https://api.example.com/webhook/chat-inbound?token=YOUR_SECRET_TOKEN
  • 요청 검증: agent.agent_id가 내 에이전트인지, chat_channel_id가 내가 연결한 채널인지 확인하세요.

연결 확인

본문 형식이 고정이라 엔드포인트는 curl로 직접 시험할 수 있어요.
요청과 응답 형식대로 5초 안에 200 응답이 오는지 먼저 확인한 뒤, 연결한 채널로 메시지를 보내 첫 답변에 변수가 들어갔는지 보세요.

예외 상황

관련 문서