메시지 Bot API 개요
메시지 Bot API를 사용하면 메시지 Bot 계정을 이용해 개별 사용자와 직접 상호 작용할 수 있다. 고객사의 메시지 수신 서버에서 메시지 Bot API 서버를 통해 언제든지 사용자에게 대화형 메시지를 보낼 수 있다. 또한 해당 대화방에서 사용자가 메시지를 보낼 때 자동으로 사용자에게 응답을 보낼 수 있다.
메시지 Bot API는 메시지 Bot 등록 및 조회와 메시지 전송, 메시지 수신 기능을 제공한다.
- 메시지 Bot 등록 및 조회는 고객사에서 사용할 메시지 Bot을 등록, 수정, 조회한다.
- 메시지 전송은 고객사의 메시지 Bot 서버를 통해 사용자 각각에게 메시지를 전달한다.
- 메시지 수신은 고객사의 메시지 Bot에 초대된 사용자의 대화방에서 사용자와 대화하는 기능을 수행한다.
메시지 Bot
메시지 Bot을 이용하면 개별 사용자에게 직접 메시지를 전달하거나 해당 사용자와 대화할 수 있다. 예를 들어, 고객사에서 사용자에게 전달할 공지사항이 있으면 직접 메시지를 전달하는 방식으로 공지 내용을 전달할 수 있다. 또, 사용자가 특정 문장을 입력하면 그에 맞는 대답을 자동으로 하는 시스템을 만들어 사용자와 상호 작용할 수 있다.
참고
- Bot은 최대 300개까지 등록할 수 있다.
메시지 Bot API
메시지 Bot API를 이용해 메시지 Bot을 등록, 수정, 조회할 수 있으며, 사용자에게 직접 메시지를 전달하거나 사용자와 상호 작용할 수 있다.
일반적인 메시지 Bot의 등록 및 메시지 발송은 다음 단계를 거친다.
- '메시지 Bot 등록' API로 메시지 Bot 정보 등록
- '메시지 Bot 도메인 등록' API로 도메인 등록
- '메시지 전송' API로 메시지 발송
- 필요한 경우 callback URL을 Bot에 등록하여 사용자와 상호 작용 가능
API의 흐름을 그림으로 표현하면 다음과 같다.
[그림 1 메시지 Bot API의 흐름]
메시지 Bot 등록 및 조회
메시지 Bot API를 이용하려면 테넌트와 도메인이라는 개념을 이해해야 한다. 테넌트는 그룹사의 개념이다. 도메인은 개별 기업의 개념이다. 여러 도메인이 하나의 테넌트에 속할 수 있다.
사용자가 직접 메시지 Bot을 등록하고 조회할 수 있도록 인터페이스를 제공한다. 메시지 Bot을 등록하면 해당 메시지 Bot은 사용자가 속한 테넌트에 등록된다. 등록된 메시지 Bot을 도메인에서 사용하고자 한다면 메시지 Bot 도메인을 별도로 등록해야 한다.
참고
- Bot이 등록되면 Bot Id 가 생성되며, Bot Id 는 이전 버전 API의 bot No. 와 동일하다.
메시지 Bot을 시스템에 등록하고, 메시지 Bot에 원하는 도메인까지 등록하는 과정은 API 외에도 Developers Console > Bot 메뉴 및 Admin > 서비스 > Bot 메뉴를 통해 동일한 기능을 수행할 수 있다.
도메인 등록이 완료된 bot은 메시지 전송/수신 기능을 사용할 수 있다.
메시지 전송
메시지 Bot이 특정 사용자에게 메시지를 전송할 수 있다.
참고
- 인원이 500명 이상 참여 중인 대화방에 메시지를 전송할 경우, 메시지 알림은 발생하지 않는다.
메시지 수신
사용자와 메시지 Bot의 상호 작용을 위한 인터페이스를 제공한다. 사용자가 메시지 Bot에게 보낸 메시지를 고객사의 메시지 수신 서버로 전달한다. 메시지 서버에서 보낸 메시지가 임의로 변조되었는지 확인하기 위해 X-WORKS-Signature 라는 응답헤더값으로 검증할 수 있다.
참고
- callback URL은 2개 이상 등록할 수 없다.
- callback 전달시 제공하는 인터페이스를 이전버전 API와 (Kaizen API)중 하나를 선택할 수 있다. 자세한 내용은 Developers Console > Bot 메뉴를 참고한다.
메시지 Bot 상태
메시지 Bot의 상태는 다음과 같이 나뉜다.
| 상태 | 설명 |
|---|---|
| 준비 중 | Bot을 등록한 상태로 각 도메인에서 사용하려면 '메시지 Bot 도메인 등록' API를 이용해 도메인을 등록해야 한다. |
| 서비스 중 | 각 도메인에 추가된 상태로 권한이 ON 상태라면 '메시지 전송' API를 이용해 각 도메인에 메시지를 발송할 수 있다. |
| > 권한 ON | Bot과의 대화 참여 가능 |
| >> 공개 | 대화상대 목록에 노출 |
| >> 비공개 | 대화상대 목록에 미노출 |
| > 권한 OFF | Bot과의 대화 참여 불가능 |
상태 변경에 따라 다음 종류의 서비스 알림이 발송된다.
| 서비스 알림 종류 | 상태 | 수신 |
|---|---|---|
| 대화상대 목록 추가 | ● 권한 ON & 공개 | 구성원 |
| 대화상대 목록 제거 | ● 권한 ON & 비공개 ● 권한 OFF ● 권한 ON인 Bot 도메인 제거 ● 권한 ON인 Bot 도메인에 대한 사용 범위 제한 ● 권한 ON인 Bot 삭제 |
구성원 |
| 서비스 중인 Bot 도메인 제거 | ● 서비스 중인 Bot 삭제 ● 서비스 중인 Bot 도메인에 대한 사용 범위 제한 |
관리자 |
| 서비스 중인 Bot '팀/그룹, 1:N 메시지방 초대 가능' 설정 | ● '팀/그룹, 1:N 메시지방 초대 가능' 설정 | 관리자 |
| 서비스 중인 Bot '팀/그룹, 1:N 메시지방 초대 가능' 해제 | ● '팀/그룹, 1:N 메시지방 초대 가능' 해제 | 관리자 |
관리자는 최고 관리자, 부관리자, IT 관리자를 뜻한다.
'팀/그룹 1:N 메시지방 초대 가능' 설정의 경우 사용 권한은 전체로 고정된다.
한번 삭제된 Bot은 다시 복구할 수 없다.
각 상태와 API 사용을 그림으로 표현하면 다음과 같다.
[그림 2 메시지 Bot 상태의 흐름]
사용 준비
메시지 Bot API를 사용하려면 bot 또는 bot.read scope를 포함하는 client를 생성해야 한다.