Keyda Business
South KoreaEnglish 로그인 무료로 시작하기
Keyda Business 문서가이드

액션: 자체 시스템에서 가져오는 답변

액션을 사용하면 봇이 채팅 도중 자체 시스템에서 정보를 조회할 수 있습니다 — 주문이 어디쯤 왔는지, 언제 배송되는지, 예약이 확정되었는지 등. 고객이 물으면 봇이 필요한 정보를 수집하고 API를 호출한 뒤, 돌아온 결과를 바탕으로 고객의 언어로 답변합니다.

봇이 작동하는 모든 곳에서 사용할 수 있습니다: 웹사이트 위젯, 봇 링크와 QR 코드, 그리고 Android, iOS, React Native, Flutter, Ionic 앱. 설치하거나 업데이트할 것이 없습니다 — 호출은 당사 서버에서 이루어지므로 API 인증 정보가 브라우저나 휴대폰에 전달되지 않습니다.

시작하기 전에: 누구나 봇과 채팅할 수 있습니다

봇은 공개 채팅입니다. 주문 번호만으로 주문을 볼 수 있다면, 누구든 맞을 때까지 번호를 입력해 볼 수 있습니다.

실제 고객만 아는 두 가지 정보 — 주문 번호와 주문에 등록된 이메일 또는 전화번호 — 를 요청하고, 둘 다 일치할 때만 API가 주문을 반환하도록 하세요. 그렇지 않으면 "찾을 수 없음"으로 응답하세요.

봇은 세 가지 방식으로 돕지만, 어느 것도 그 확인을 대신하지는 않습니다. 고객이 실제로 입력한 값만 전송하고, 채팅 하나 또는 주소 하나가 할 수 있는 조회 횟수를 제한하며, 응답에서 봇이 볼 수 있는 필드를 직접 선택할 수 있습니다.

설정하기

대시보드에서 액션을 열고 새 액션을 선택하세요. 이 화면은 소유자와 관리자가 볼 수 있습니다.

  • 이름 — 본인이 알아보기 위한 이름. 예: "주문 상태".
  • 봇이 언제 사용해야 하나요? — 새 동료에게 설명하듯 한 문장으로: "고객이 주문이 어디쯤 왔는지 또는 언제 도착하는지 묻습니다."
  • API 주소 — GET 또는 POST, 그리고 https:// 주소. 값이 들어갈 자리에 {{order_id}}를 쓰세요.
  • 봇이 고객에게 요청하는 항목 — 최대 6개의 값. 각 값에는 직접 표현한 레이블("주문 번호"), API에서 사용하는 이름(order_id), 그리고 형식(모든 텍스트, 숫자, 이메일 주소, 전화번호)이 있습니다.
  • 헤더 — API 키 또는 토큰. 암호화되어 저장되며 다시 표시되지 않습니다.
  • 이 필드만 봇과 공유 — 선택 사항. status, eta, items[].name처럼 봇이 사용할 수 있는 응답 항목을 나열하세요. 나머지는 AI가 보기 전에 제거됩니다.

테스트를 누르고 샘플 값을 입력하면 전송된 요청과 봇에게 전달될 내용을 그대로 볼 수 있습니다. 그다음 테스트 화면에서 실제로 시도해 보세요: "내 주문 48213은 어디쯤 왔나요? 제 이메일은 asha@example.com입니다".

API가 받는 내용

GET의 경우 주소에 넣은 값은 채워지고 나머지는 쿼리 문자열에 추가됩니다:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

POST의 경우 값은 JSON 본문으로 전송됩니다:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

모든 요청에는 직접 설정한 헤더와 함께 다음 헤더가 포함됩니다:

헤더설명
webhook-id이 요청의 고유 id
webhook-timestamp전송 시각(초 단위)
webhook-signature서명 — 아래 참조
X-Keyda-Bot봇의 Client ID
X-Keyda-Action액션의 키. 예: order_status
X-Keyda-Conversation요청이 발생한 채팅

응답으로 보낼 내용

8초 안에 JSON 또는 짧은 한 줄의 일반 텍스트로 응답하세요.

  • 200과 데이터 — 봇이 이를 바탕으로 답변합니다. 작게 유지하고 명확한 필드 이름을 사용하세요. 내부 코드보다 {"status":"shipped","eta":"2 October"} 같은 형태가 더 잘 작동합니다.
  • 404는 일치하는 항목이 없을 때 — 봇이 고객에게 알리고 입력 내용을 확인해 달라고 요청합니다.
  • 그 외의 응답이거나 제시간에 응답이 없으면 — 봇이 사과하고 연락처를 안내하며, 해당 채팅에 확인 표시가 붙습니다. 이유는 액션 화면에 표시됩니다.

리디렉션은 따르지 않으며, 256 KB를 넘는 응답은 읽지 않습니다.

서명 확인

요청은 Standard Webhooks 방식으로 서명되므로 기존 라이브러리를 사용할 수 있습니다. 서명 시크릿은 액션 화면에 있습니다.

직접 확인하려면: id, 타임스탬프, 본문(body)을 그대로 마침표로 이어 붙이고, 시크릿(whsec_ 뒤의 부분을 base64 디코딩한 값)으로 HMAC-SHA256 서명을 만든 뒤 비교하세요.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

GET 요청은 본문이 비어 있으므로 서명 대상 텍스트는 마침표로 끝납니다. 값 자체도 서명에 포함하려면 POST를 사용하세요.

봇이 사용하는 방식

  • 부족한 정보는 짧은 질문을 하나씩 던져 요청하고, 고객이 채팅에서 앞서 말한 내용은 기억합니다.
  • 값을 추측하지 않습니다. 고객이 입력하지 않았다면 봇이 물어봅니다.
  • 메시지당 조회 1회. 저장된 답변이 여전히 우선하므로 직접 답변해 둔 질문은 API를 호출하지 않습니다.
  • 조회로 얻은 답변은 다른 고객에게 재사용되지 않습니다.
  • 조회 1회는 AI가 작성하는 다른 답변과 마찬가지로 답변 1개로 계산됩니다.

채팅에서는 조회로 얻은 답변 아래에 어떤 액션이 실행되었고 어떻게 끝났는지 표시됩니다. 고객이 입력한 값은 대화 기록에만 남고 다른 곳에는 저장되지 않습니다.

제한

봇당 액션 8개, 액션당 값 6개와 헤더 8개, 호출당 8초. 채팅 하나는 10분에 6회, 인터넷 주소 하나는 1시간에 20회 조회할 수 있으며, API는 봇으로부터 분당 최대 120회 호출을 받습니다.

액션은 정보를 읽기만 합니다. 주문 취소나 환불처럼 무언가를 변경하는 주소에 연결하지 마세요. 그런 작업에는 봇에 아직 없는 확인 단계가 필요합니다.

Next: Widget API →