AI SNS CHAT의 REST API를 언제 쓰고 언제 쓰지 않을지, 스트리밍과 웹훅, 속도 제한, 보안 점검, 단계별 출시 방법을 정리했습니다.
자사 앱, 사내 시스템, 독자적인 채팅 화면에 AI 상담원을 붙이고 싶은데 기본 채널 연결만으로는 부족한 경우가 있습니다. 이럴 때 쓰는 것이 AI SNS CHAT의 REST API입니다. 이 글에서는 API가 필요한 상황과 필요 없는 상황을 구분하고, 구성 요소와 속도 제한, 설계 패턴, 보안 체크리스트, 출시 순서를 차례로 설명합니다.
API가 맞는 도구일 때, 아닐 때
API를 먼저 열기 전에 "정말 코드를 짜야 하는가"부터 따져 보시기 바랍니다. AI SNS CHAT에는 이미 웹사이트 채팅 위젯, Instagram, Messenger, WhatsApp, LINE, KakaoTalk 등 많은 채널 연결이 준비되어 있습니다. 이 채널에 상담원을 올리는 일은 설정 화면에서 끝나며 API가 필요하지 않습니다.
API가 어울리는 경우는 대략 다음과 같습니다.
- 자사 모바일 앱이나 웹 앱 안에 직접 디자인한 채팅 화면을 넣고 싶을 때
- 회원 등급, 주문 상태 같은 사내 데이터를 대화 흐름과 엮고 싶을 때
- 대화 결과를 자사 CRM이나 알림 시스템으로 보내고 싶을 때
- 기본 위젯으로는 표현하기 어려운 화면 구성이 필요할 때
반대로 "카카오톡 채널에 답변 봇을 올리고 싶다", "홈페이지에 상담 창을 달고 싶다" 정도라면 기본 연결이 더 빠르고 유지보수도 쉽습니다.
구성 요소 이해하기
AI SNS CHAT의 공개 API는 JSON 기반 REST 방식이며, 크게 네 가지로 나누어 이해하면 편합니다.
API 키
API 키는 워크스페이스 설정의 API keys 메뉴에서 발급합니다. 키는 발급 시점에 한 번만 표시되므로 그 자리에서 안전한 보관 장소에 옮겨 두어야 합니다. 노출이 의심되면 폐기(revoke)하고 새로 발급하면 됩니다. API 키는 Hobby 이상 플랜에서 사용할 수 있습니다.
요청과 응답
대화는 JSON으로 주고받습니다. 사용자의 메시지를 보내면 에이전트의 답변을 받는 것이 기본 흐름입니다. 에이전트의 페르소나, 학습 데이터, 가드레일은 대시보드에서 설정한 그대로 적용되므로, 코드에서 따로 다시 정의하지 않아도 됩니다.
SSE 스트리밍
요청에 stream=1을 지정하면 Server-Sent Events 방식으로 답변이 조금씩 도착합니다. 답이 완성될 때까지 빈 화면을 보여 주는 대신 글자가 이어서 나타나게 만들 수 있어 체감 속도가 좋아집니다. 자체 채팅 화면을 만든다면 사실상 이 방식을 기본으로 삼는 편이 좋습니다.
HMAC 서명 웹훅
AI SNS CHAT에서 발생한 이벤트를 우리 서버로 받아 볼 수 있고, 웹훅에는 HMAC 서명이 붙습니다. 전송 이력은 전달 로그(delivery log)에서 확인할 수 있어서 "보냈는데 안 왔다"는 상황을 추적할 때 도움이 됩니다. 서명 형식과 헤더의 정확한 이름은 API 레퍼런스 문서를 기준으로 구현하시기 바랍니다.
공개된 속도 제한을 지키세요
공개된 속도 제한은 다음과 같습니다.
| 대상 | 제한 |
|---|---|
| 인증(auth) | IP당 5분에 20회 |
| 공개 채팅(public chat) | IP당 분당 30회 |
| 폴링(poll) | 분당 120회 |
여기서 놓치기 쉬운 점은 "IP당"이라는 기준입니다. 예를 들어 (가정입니다) 여러 사용자의 요청을 하나의 백엔드 서버가 대신 전달한다면, 외부에서 보기에는 모두 같은 IP에서 온 요청입니다. 이 경우 공개 채팅 제한인 분당 30회를 서버 전체가 나눠 쓰게 될 수 있습니다. 이벤트 공지로 문의가 한꺼번에 몰리는 날에는 이 부분이 병목이 됩니다.
대응 방법은 다음과 같습니다.
- 제한에 걸리면 즉시 재시도하지 말고 간격을 점점 늘려 가며 다시 시도합니다.
- 폴링은 꼭 필요한 곳에서만 쓰고, 가능하면 SSE 스트리밍이나 웹훅으로 대체합니다.
- 같은 질문이 반복되는 화면(자주 묻는 질문 버튼 등)은 우리 쪽에서 정적으로 처리해 호출 수를 줄입니다.
- 로그인 같은 인증 호출은 토큰을 재사용하고 매번 새로 호출하지 않습니다.
잘 작동하는 설계 패턴
서버를 중간에 두기
브라우저나 앱에서 API 키를 직접 쓰면 안 됩니다. 키가 앱 코드나 네트워크 요청에 노출되기 때문입니다. 우리 백엔드가 키를 보관하고, 클라이언트는 우리 백엔드만 호출하는 구조가 기본입니다.
- 01사용자 앱 또는 웹
- 02우리 백엔드(키 보관)
- 03AI SNS CHAT API
- 04웹훅으로 결과 수신
대화 맥락은 식별자로 이어 붙이기
한국 쇼핑몰의 상담 화면이라면 로그인한 회원의 ID를 대화와 함께 관리해 두는 방식이 편합니다. 같은 고객이 앱과 웹을 오가도 문의가 이어지도록 우리 쪽 식별자와 대화를 매핑해 저장해 두세요.
실패를 전제로 만들기
네트워크 오류나 일시적 지연은 반드시 생깁니다. 스트리밍이 중간에 끊겼을 때 "다시 시도" 버튼을 보여 주고, 웹훅 수신은 같은 이벤트가 두 번 와도 문제가 없도록 중복 처리를 막아 두면 안정적입니다.
사람에게 넘기는 시점 정하기
API로 만든 화면에서도 사람 상담원 연결 경로는 반드시 필요합니다. 답변이 해결되지 않았을 때 문의 접수 화면이나 전화 번호로 안내하는 흐름을 설계에 포함하세요.
서비스 오픈 전 보안 체크리스트
- API 키는 서버 환경 변수나 비밀 관리 도구에만 두고, 소스 저장소에 올리지 않습니다.
- 키는 용도별로 나누어 발급하고, 퇴사자가 생기거나 노출이 의심되면 바로 폐기합니다.
- 웹훅은 서명을 검증한 뒤에만 처리합니다. 서명이 맞지 않는 요청은 버립니다.
- 웹훅 수신 주소는 HTTPS를 사용합니다.
- 로그에 고객 이름, 연락처 같은 개인정보와 키가 그대로 남지 않도록 합니다.
- 에이전트 설정에서 프롬프트 인젝션과 악용 방지 필터를 점검합니다.
- 대화 보관 기간 등 개인정보 관련 사내 기준을 먼저 정리해 둡니다.
AI SNS CHAT은 개인정보 보호 관행을 GDPR과 일본 APPI를 참고하여 설계했지만, SOC 2, ISO 27001, HIPAA 인증을 받은 서비스는 아닙니다. 사내 보안 심사가 필요한 조직이라면 이 점을 전제로 검토하시기 바랍니다. 자세한 내용은 보안 페이지에서 확인할 수 있습니다.
테스트와 단계적 출시
- Playground에서 먼저 답변 품질을 확인합니다. API로 호출하기 전에 에이전트 자체가 의도대로 답하는지 점검하는 것이 순서입니다.
- 테스트용 에이전트로 연동을 개발합니다. 운영 에이전트를 건드리지 않도록 Duplicate로 복제본을 만들어 쓰면 됩니다. 복제는 페르소나, 모델, 학습 데이터를 가져오고 대화 기록은 가져오지 않습니다.
- 웹훅 전달 로그를 확인합니다. 이벤트가 정상 전달되는지, 실패한 건은 없는지 로그로 봅니다.
- 속도 제한 상황을 시험합니다. 일부러 요청을 몰아서 재시도 처리가 의도대로 동작하는지 확인합니다.
- 일부 사용자에게만 먼저 공개합니다. 예를 들어 (가정입니다) 사내 직원이나 베타 고객에게 한 주 정도 열어 보고, 대화 기록과 평가(좋아요/싫어요)를 본 뒤 전체로 넓힙니다.
운영 중 설정을 바꾸다 문제가 생겼을 때를 대비해, 에이전트의 복원 지점(restore point)을 만들어 두면 되돌리기가 쉽습니다.
AI SNS CHAT에서 실제로 해 보기
처음부터 순서대로 따라 하면 다음과 같습니다.
- 플랜 확인. API 키는 Hobby 이상 플랜에서 쓸 수 있습니다. 요금은 요금 페이지에서 확인하세요. Free 플랜에서는 키를 발급할 수 없습니다.
- API 키 발급. 워크스페이스 설정의 API keys에서 키를 만듭니다. 키는 한 번만 표시되니 바로 복사해 안전한 곳에 저장하세요. 잘못 노출했다면 같은 화면에서 폐기하고 다시 발급합니다.
- 에이전트 준비. 에이전트의 페르소나, 가드레일, 학습 데이터를 먼저 갖춥니다. 데이터 소스는 사이드바의 Data sources에서 파일, 텍스트, 웹사이트, Q&A 등을 추가할 수 있습니다.
- Playground로 점검. 대화 품질을 충분히 확인한 뒤에 코드를 붙입니다.
- 연동 구현. 백엔드에서 API를 호출하고, 화면에는
stream=1스트리밍을 연결합니다. 이벤트를 받아야 한다면 웹훅을 등록하고 서명을 검증합니다. 구체적인 요청 형식은 API 레퍼런스를 기준으로 합니다. - 운영 확인. 대화는 Activity의 Chat logs에서 보고, 사용량은 Usage 페이지에서 에이전트별 크레딧으로 확인합니다. 답변 1건이 크레딧 1개로 계산됩니다.
API와 기본 채널을 함께 쓰는 구성도 흔합니다. 예를 들어 (가정입니다) 자사 앱에는 API로 만든 채팅 화면을 두고, 웹사이트에는 채팅 위젯을, 고객이 많이 쓰는 KakaoTalk 채널과 Instagram은 연결 페이지에 안내된 기본 연결로 붙이는 식입니다. 이렇게 하면 모든 접점이 하나의 에이전트와 하나의 학습 데이터를 공유합니다. 사람 상담원에게 넘기는 경우에는 Helpdesk의 Scheduling으로 근무 시간표를 정해 두면 근무 중인 담당자에게 자동 배정되고, 알림은 Slack, Teams, 이메일, 웹훅 등으로 받을 수 있습니다. Helpdesk는 Standard 이상 플랜이 필요합니다. 기능 전체는 기능 페이지에서 확인할 수 있습니다.
마무리
REST API는 기본 채널 연결로 해결되지 않는 부분을 메우는 도구입니다. 지원 채널에 올리는 것만이 목적이라면 API 없이도 충분하고, 자체 앱이나 독자 화면, 사내 시스템과의 결합이 필요할 때 API의 가치가 커집니다. 키는 서버에만 두고, 속도 제한을 기준으로 호출 수를 설계하고, 웹훅 서명을 검증하고, 작은 범위부터 열어 나가는 것. 이 네 가지만 지켜도 첫 연동에서 겪는 대부분의 문제를 피할 수 있습니다.
자주 묻는 질문
REST API를 쓰려면 어떤 플랜이 필요한가요?
API 키는 Hobby 이상 플랜에서 사용할 수 있습니다. Free 플랜에서는 사용할 수 없습니다. 플랜별 요금과 크레딧은 요금 페이지에서 확인하실 수 있으며, 금액은 운영 중 조정될 수 있습니다.
답변을 우리 화면에 스트리밍으로 보여 줄 수 있나요?
가능합니다. 요청에 stream=1을 지정하면 SSE 방식으로 답변이 순차적으로 전달됩니다. 이를 이용해 자체 채팅 화면에서 글자가 이어서 나타나는 효과를 구현할 수 있습니다.
웹훅이 정말 AI SNS CHAT에서 온 것인지 어떻게 확인하나요?
웹훅에는 HMAC 서명이 붙으므로, 우리 서버에서 서명을 검증한 뒤에만 처리하시면 됩니다. 서명이 일치하지 않는 요청은 버리세요. 정확한 검증 방법은 API 레퍼런스를 따르시고, 전달 이력은 전달 로그에서 확인할 수 있습니다.
속도 제한은 어떻게 되나요?
공개된 기준은 인증이 IP당 5분에 20회, 공개 채팅이 IP당 분당 30회, 폴링이 분당 120회입니다. 백엔드 한 대가 여러 사용자의 요청을 대신 보내면 같은 IP로 집계될 수 있으니 재시도 간격과 호출 수를 함께 설계하시기 바랍니다.
WhatsApp이나 Messenger에 에이전트를 올리려면 API가 필요한가요?
필요하지 않습니다. WhatsApp, Messenger, Instagram, KakaoTalk 등은 Channels 메뉴에서 기본 연결로 설정할 수 있습니다. API는 자체 앱이나 독자 화면처럼 기본 연결로 부족한 경우에 선택하시면 됩니다.


