문의하기 (구버전) 로그인 로그인

[API 연동] 외부 시스템 연결 가이드 (v4.5)

최종 수정: 2026. 6. 12.

챗봇이 단순히 정해진 지식만 대답하는 것을 넘어, 사내 시스템이나 외부 서비스의 데이터를 실시간으로 조회하고 제어할 수 있도록 도와주는 강력한 기능입니다.

🎉 v4.5 업데이트 안내
기존에는 플러그인으로 제공되던 API 연동 기능이 v4.5부터 챗봇의 기본 기능으로 통합되었습니다. 이제 외부 데이터(날씨, 배송 조회, 학사 일정 등)를 챗봇에 자유롭게 연결할 수 있습니다.

1. 개요

API 연동을 활용하면 챗봇 대화 도중 다음과 같은 작업을 수행할 수 있습니다.

  • 조회형 : "오늘 우리 학교 급식 메뉴 뭐야?" → 나이스(NEIS) 교육 정보 API 호출 후 답변
  • 접수/제어형 : "A/S 접수하고 싶어요" → 사내 접수 시스템에 데이터 전송 후 접수번호 안내

2. 사전 준비: 방화벽 허용 IP 주소 (Outbound)

🚨 매우 중요: 챗봇이 고객사의 API 서버나 외부망에 접근하려면 방화벽 설정이 필요합니다.

[콘텐츠 관리] → [API 연동] 페이지 상단을 보면 쉴드(방패) 아이콘과 함께 고정 IP 주소(예: 34.47.77.33) 가 표시되어 있습니다.
이 IP는 Cloudturing 챗봇이 외부 API를 호출할 때 사용하는 고정 아웃바운드(Outbound) 주소입니다. 사내 API를 연동하시려면, 표시된 IP 주소를 내부 개발팀이나 보안팀에 전달하여 방화벽 허용(Whitelist) 처리를 요청해 주세요.

3. API 연동 등록 과정

API 명세서를 업로드하면 AI가 분석하여 연동 기능을 자동으로 생성합니다.

1단계 : 명세서 업로드 및 후보 추출

API를 연동하려면, 먼저 [파일 관리] 메뉴에서 명세서를 업로드하고 AI 분석 및 분류 확정 단계를 거쳐야 합니다.

💡 참고: 파일 업로드 및 AI 분석에 대한 전체 과정이 낯설다면 [학습 문서 업로드 및 데이터 관리 가이드]를 먼저 확인해 주시면 큰 도움이 됩니다.

  1. [파일 관리] 메뉴로 이동하여 연동하고자 하는 API의 명세서(TXT, JSON, PDF 등)를 업로드하고 [▶ 분석] 버튼을 누릅니다. (Swagger나 OpenAPI 규격 문서도 좋습니다.)
  2. 분석이 완료되어 상태가 '초안 생성됨'으로 바뀌면, 우측 분류 지침에서 해당 내용이 'API 연동' 으로 잘 지정되었는지 확인합니다.
  3. 이상이 없다면 [✔ 분류 확정 저장] 을 누른 뒤, 화면 상단의 [유형별 등록] 을 클릭합니다.
  4. 이제 확정된 내용이 2단계에서 진행할 [API 연동] 메뉴의 후보 목록으로 자동 이관됩니다.

2단계 : API 연동 생성하기

  1. [콘텐츠 관리] → [API 연동] 메뉴로 이동합니다.
  2. 좌측 목록의 [API 연동 후보] 에 파일 관리에서 확정했던 항목들이 나타납니다. 연동할 후보를 클릭합니다.
  3. 화면 중앙에서 다음 두 가지를 설정합니다.
    • API 타입 선택: 외부 시스템의 데이터를 가져오거나 보내는 일반적인 목적이라면 [외부 데이터 호출] 을 선택합니다.
    • 사용 용도 설명: AI가 언제 이 API를 써야 할지 알 수 있도록 자연어로 적어줍니다.
      (예: "지역명을 입력받아 실시간 날씨 데이터를 반환하는 기능")
  4. 우측 하단의 주황색 [API 연동 생성하기] 버튼을 클릭합니다.

4. 생성된 API 확인 및 테스트 (샌드박스)

생성이 완료되면 좌측 목록이 [생성된 API] 로 이동하며, 클릭 시 상세 정보를 확인하고 관리할 수 있습니다.

① 상태 및 활성화 관리

  • 우측 상단의 토글 스위치(활성/비활성) 를 통해 챗봇이 해당 API를 실제 대화에서 사용할지 말지 결정할 수 있습니다.
  • 연동 정보가 더 이상 필요 없다면 [🗑 삭제] 버튼으로 지울 수 있습니다.
  • 작업 유형(조회/수정 등), 상태(PASSED), 호출 파라미터(GET/POST 요청 정보) 등 AI가 분석한 함수 명세가 화면에 나열됩니다.

② 샌드박스 내부 자체 연동 테스트 (매우 중요 ⭐)

챗봇 화면에서 직접 대화해 보기 전에, API가 정상적으로 호출되는지 화면 하단의 '샌드박스 내부 자체 연동 테스트' 영역에서 테스트할 수 있습니다.

  1. 테스트 파라미터 입력: API 호출에 필요한 필수 값(예: 시도교육청코드, 학교코드, 날짜 등)을 입력란에 적어줍니다.
  2. [▶ 테스트 스크립트 런타임 실행] 버튼을 클릭합니다.
  3. 응답 결과가 성공(200 OK 등)으로 떨어지고 데이터가 잘 들어오는지 확인합니다. 성공했다면 챗봇이 실제 대화에서도 이 데이터를 바탕으로 답변할 수 있습니다.

💡 작동 원리 (LLM Function Calling)

  1. 사용자가 인천뷰티예술고등학교의 챗봇에 "내일 급식 뭐야?" 라고 질문합니다.
  2. AI가 질문을 분석하여 일반 지식(대화의도)으로 답할지, 실시간 데이터(API)가 필요한지 스스로 판단합니다.
  3. API가 필요하다고 판단되면, 사용자의 질문에서 필요한 파라미터(학교명, 날짜 등)를 뽑아내어 연결된 API를 호출합니다.
  4. 외부 시스템에서 받은 결과값(급식 메뉴 데이터)을 사람의 말로 자연스럽게 문장화하여 사용자에게 답변합니다.