실시간 정보 API · 최신 정보 조회

환경설정 > 상담톡 설정 > 지식베이스 > 실시간 정보 API는 배송·예약 등 답변 시점에 확인해야 하는 정보를 외부 시스템에서 읽어 오는 기능입니다. API는 시스템끼리 정보를 주고받는 연결 방식이며, 연동 담당자가 제공한 정보를 바탕으로 설정해 주세요.

실시간 조회 결과는 학습 데이터로 저장되지 않습니다. 읽기 전용 GET 방식으로 조회하며, 비밀값은 연결에 저장합니다. API 키·토큰·실제 고객 식별값을 안내 문구나 공개 매뉴얼에 입력하지 마세요.

실시간 API 등록 화면에서 기본 정보, 연결, 요청 경로와 파라미터를 설정합니다.

① 이름·용도 연동의 이름과 AI가 언제 조회해야 하는지 작성합니다.

② 사용 상태 조회에 사용할 때 활성화합니다.

③ HTTP API 연결 등록된 연결을 선택하거나 [연결 만들기]로 준비합니다.

④ 경로·쿼리 연결의 Base URL을 기준으로 상대경로와 쿼리 파라미터를 정합니다.

⑤ 파라미터 필요한 입력 항목과 값을 채울 주체를 정합니다.

⑥ 응답 매핑 레코드 경로와 최대 건수 등 답변에 사용할 응답 범위를 정합니다.

⑦ 등록 설정을 확인하고 등록한 뒤 실제 질문으로 조회 결과를 점검합니다.

처음 접하는 분을 위한 API 이해하기

API는 상담톡이 다른 시스템에 필요한 정보를 요청하는 연결 방법입니다. FAQ가 미리 작성한 안내문이라면, 실시간 조회는 질문을 받은 시점에 원본 시스템에서 정보를 확인하는 방식입니다. 예를 들어 배송 방법은 FAQ로 안내하고, 특정 주문의 현재 배송 상태는 조회 API로 확인합니다.

연동 담당자에게 먼저 받을 정보

조회할 업무와 원본 시스템, 연결에 사용할 기본 주소(Base URL)
읽기용 GET 요청 경로와 인증 방법
필요한 입력값 이름, 필수 여부, 안전한 테스트 값
정상 결과·결과 없음·오류일 때의 응답 예시
고객에게 보여도 되는 응답 필드와 보여 주면 안 되는 필드

이 정보가 준비되지 않았다면 임의의 주소나 키를 넣기보다 담당자에게 먼저 확인해 주세요. 비밀키는 안내된 연결 설정에서 관리하며 AI 지침이나 공개 매뉴얼에 넣지 않습니다.

입력 항목을 예로 이해하기

아래는 구조를 설명하는 가상 예시로, 그대로 등록해 동작하는 실제 API가 아닙니다.

항목	형식 예시	의미
이름	배송 상태 조회	운영자가 구분할 이름
용도	고객이 배송 진행 상태를 물을 때 조회합니다.	언제 사용할 조회인지 설명
경로	/v1/orders	연결된 기본 주소 뒤에 붙는 상대경로
레코드 경로	data.items	응답 데이터 안에서 목록이 있는 위치
표시 필드	배송 상태·기준 시각	응답 중 고객에게 필요한 정보만 선택

등록과 사용 설정은 별도입니다

지식베이스에서 API를 등록하고 [호출해 보기]로 정상 결과를 확인합니다.
실패하거나 빈 결과가 나오면 요청값과 응답 구조를 담당자와 확인합니다.
[운영 설정 > 동작 설정 > 실시간 정보 조회]에서 사용 여부와 조회할 API를 설정하고 저장합니다.
고객 화면에서 정상 조회 질문과 결과가 없는 질문을 각각 확인합니다.

완료 기준: 호출 테스트 성공뿐 아니라 고객 화면에 필요한 정보만 정확하게 안내되어야 합니다. 설정 화면의 테스트 입력란 유무는 연결과 API 구성에 따라 다를 수 있습니다. 조회 실패를 ‘해당 주문이 없다’는 결과로 단정하지 마세요.

등록 순서

[API 등록]을 누릅니다.
이름과 용도를 입력합니다. 예: 이름 “배송 조회”, 용도 “고객이 주문번호로 배송 상태를 물을 때 조회합니다.”
연결(HTTP API)을 선택합니다. 사용할 연결이 없으면 [연결 만들기]를 통해 준비합니다. 선택 가능한 연결은 해당 지식베이스에 귀속된 연결입니다.
요청 경로와 쿼리 파라미터를 구성합니다. 경로는 연결 Base URL 기준 상대경로이며, 입력값은 쿼리 파라미터로 전달합니다.
필요한 파라미터와 응답 매핑을 지정합니다.
조회 실패·빈 결과 안내 문구와 AI 사용 지침, 호출 상한을 설정합니다.
[등록]한 뒤 목록의 [호출해 보기]로 실제 응답을 확인합니다.
운영 설정 > 동작 설정 > 실시간 정보 조회에서 사용 여부와 조회할 API를 설정하고 저장합니다. 등록만 하고 사용 설정을 빠뜨리지 않도록 확인해 주세요.

입력 항목 자세히 보기

항목	설명·사용 방법
이름 / 용도	운영자가 구분할 이름과 AI가 언제 사용해야 하는지 설명합니다. 용도는 최대 300자입니다.
상태	사용을 끄면 일시정지됩니다. 일시정지한 API는 AI가 조회하지 않습니다.
경로(GET·상대경로)	예: /v1/orders. 경로에는 슬롯을 사용할 수 없으며 값은 쿼리로 전달합니다.
쿼리 추가 / 파라미터 추가	요청에 필요한 항목을 추가합니다. 고객 입력은 AI가 대화에서 읽어 채우고, 서버가 채움은 상담방·고객·소셜 이벤트 값으로 서버가 채웁니다. 연락처·이메일·고객 ID는 서버가 채움으로만 구성합니다.
레코드 경로	응답 중 사용할 데이터 위치입니다. 예: data.items. 비우면 응답 전체를 기준으로 합니다.
최대 건수 / 표시 필드	AI에 전달할 결과 범위와 경로·라벨을 지정합니다. 표시 필드는 최대 12개이며, 각 값은 300자, 전달 묶음은 3,000B로 잘릴 수 있습니다. 꼭 필요한 정보만 선택해 주세요.
페이지 정보	총 건수·다음 페이지 여부·다음 offset·조회 시각 경로는 응답 최상위 기준으로 입력합니다. 사용하지 않으면 비워 둡니다.
실패·빈 결과 안내	조회할 수 없거나 결과가 없을 때 고객에게 안내할 문구입니다. 확인되지 않은 상태를 단정하지 않도록 작성해 주세요.
AI 사용 지침	언제 조회하고 어떻게 답할지 최대 1,500자로 정합니다. 시스템 규칙을 바꾸는 항목은 아닙니다.
호출 상한	제한 시간은 최대 5,000ms, 캐시는 최대 300초(0은 사용 안 함), 응답 1회당 호출은 최대 5회입니다. 일일 호출 상한도 확인합니다. 상한을 넘으면 조회 대신 안내 문구로 응답합니다.

테스트·운영

목록에서 이름·용도·연결·상태·마지막 테스트를 확인합니다. [호출해 보기]에 직접 입력할 필수값이 있으면 수정 화면이 열리며, 해당 영역에 테스트 값을 넣어 확인합니다. 그 외에는 바로 호출합니다. 성공 사례뿐 아니라 조회 결과 없음과 실패 상황도 확인해 주세요.

조회 결과가 불완전하면 레코드 경로와 표시 필드를 확인합니다. API를 등록해도 사용하지 않는다면 상태가 일시정지인지, 동작 설정의 실시간 조회와 API 선택이 켜져 있는지 확인해 주세요.