채널톡 Open API의 개념부터 실제 사용 방법까지, 빠르게 이해하고 적용할 수 있도록 돕는 입문 가이드입니다.
이 문서를 통해
API의 기본 개념과 필요성을 이해할 수 있어요.
채널톡 Open API로 할 수 있는 일들을 파악할 수 있어요.
API 요청 구성 요소(url, body 등)와 HTTP Method를 익힐 수 있어요.
실제 API 예시를 통해 구조와 사용법을 직관적으로 알 수 있어요.
API 요청 실패 사유를 파악할 수 있어요.
API는 프로그램과 프로그램 사이에서 데이터를 주고받을 수 있게 해주는 소통창구입니다.
채널톡에서는 외부 시스템이나 앱이 채널톡 서버와 통신하면서 다양한 자동화를 구현할 수 있도록 Open API를 제공하고 있어요.
예를 들어,
고객이 어떤 행동을 했을 때 자동으로 메시지를 보내거나
CRM 시스템에서 고객 정보를 가져와 채널톡에 업데이트하거나
특정 조건을 만족한 고객에게만 챗봇을 연결하는 자동 응대 흐름을 만드는 것도 가능합니다.
이처럼 Open API를 활용하면, 고객의 행동을 기반으로 한 맞춤형 자동화를 직접 구현할 수 있어요.
기존에 제공되는 기능보다 더 깊이 있는 연동을 가능하게 하며, 다양한 비즈니스 로직을 구현할 수 있어요.
특히 고객의 이벤트 발생 시, 데이터를 다른 시스템과 연동해 자동으로 처리하는 파이프라인을 구성할 수 있어요.
공식 문서: https://api-doc.channel.io/
✅ 어떤 정보가 필요할까요?
Open API를 호출하려면 최소한 아래 두 가지 정보를 준비해야 해요.
Authentication: Open API 사용을 위해 인증이 필요해요. API 키(Access Key, Secret Key)를 헤더에 담아야 요청이 정상 처리됩니다.
URL: 요청을 보낼 대상 주소입니다. 예: https://api.channel.io/open/v5/user-chats/...
Body: 실제로 전달할 데이터가 담긴 공간이에요. 예: 고객 정보, 메시지 내용 등
이 두 가지는 API 문서의 요청 사양(Request Spec)에 자세히 명시되어 있어요.
✅ 어떻게 요청할까요?
요청은 HTTP METHOD를 통해 구분돼요. 흔히 CRUD라고 부르는 작업 방식과 연결됩니다.
METHOD | 의미 | 역할 |
POST | Create | 새 리소스를 생성할 때 |
GET | Read | 기존 데이터를 조회할 때 |
PUT, PATCH | Update | 기존 데이터를 수정할 때 |
DELETE | Delete | 데이터를 삭제할 때 |
✅ 예시로 살펴보기
아래는 실제로 사용되는 채널톡 API 경로(Path)와 함께 어떤 방식으로 호출되는지를 보여주는 예예요.
PATCH /open/v5/user-chats/{userChatId}/invitePUT /open/v5/users/@{memberId}GET /open/v5/user-chats/{userChatId}/messagesGET /open/v5/user-chats/{userChatId}/messages/file
API는 일방적인 요청입니다.
만약 “특정 이벤트가 발생했을 때, 우리 서버로 먼저 알려줄 순 없을까?” 와 같이 특정 상황에서 채널톡으로부터 서버에 먼저 알림을 받고 싶다면 Webhook 기능을 활용해보세요!
채널톡 open API는 api key와 api secret을 발급하여 인증합니다.
Bearer 토큰 인증 방식은 지원되지 않습니다.
📌 API를 활용하기 위해 상담 ID 정보가 필요합니다. 어떻게 상담창의 ID를 확인할 수 있는지 먼저 참고해주세요!
1) 매니저 리스트를 통해 아이디 확인
2) 상담창에서 내부대화로 멘션하기
상담창 ID 확인하기 콘텐츠를 먼저 시청해주시는 걸 권장드려요!
1) 회원 정보 업데이트하기 by memberId
2) 리드(비회원) 정보 생성하기
고객 생성 시 입력하는 파라미터는 아래 문서의 항목을 참고하여 입력할 수 있습니다.
API를 연동하다 보면 다양한 이유로 요청이 실패할 수 있어요.
채널톡 서버는 다음과 같은 4가지 주요 에러 코드를 내려줍니다.
401 Unauthorized 인증 실패 에러
access_key 또는 access_secret이 잘못되었거나 누락된 경우
403 Forbidden 권한 없음 에러
요청한 리소스에 접근할 권한이 없는 경우
예: 비공개방의 메시지를 조회하거나, 오퍼레이터 시트가 없는데 채팅에 담당자로 초대하는 등
422 Unprocessable Entity 시스템 에러
잘못된 값으로 요청했을 경우 (가장 자주 발생)
요청 포맷을 어겼거나, 괄호를 닫지 않거나, 필수 필드를 빠트렸을 때
429 Too Many Requests 요청 한도 초과 에러 (Rate Limit)
API 요청 횟수가 일정 시간 내 할당량을 초과한 경우
API 응답 헤더에서 아래 정보를 통해 rate limit의 status를 확인해보실 수 있습니다.
502, 504 Server Error 채널톡 서버 에러
채널톡 자체 인프라 이슈일 가능성이 높아요
대부분 잠시 기다려주시면 해결됩니다
참고: 대부분의 오류는 API가 아니라 ‘입력값’ 문제인 경우가 많습니다.
입력값을 다시 확인하거나
관리자 페이지에서 직접 기능을 시도해보는 것도 좋은 점검 방법이에요.
지속적인 에러가 발생하거나 디버깅이 어려운 경우, 채널팀 문의하기를 통해 문의부탁드립니다.