12.1개요
본 문서는 WeChat 상담톡(이하, 상담톡) API를 이용하여, WeChat 상담을 요청한 사용자와의 채팅에서 메시지를 수신하기 위한 API 문서이다.
본 문서는 https 프로토콜을 통해 데이터를 json 형식으로 가공하여 GET, POST method를 사용하여 전송하고, json형식의 결과 데이터를 parsing하여 처리할 수 있음을 전제로 작성되었다
12.1.1선결조건
WeChat 공중 계정에 가입되어 있어야 한다.
수신도메인이 설정 되어 있어야 한다. ( 수신도메인 설정은 아래 참조)
12.1.2수신도메인 설정
수신 도메인은 상용기준으로 HTTPS만 등록할 수 있고 기본 포트인 443을 제외하고는 커스텀 포트는 허용하지 않는다.
수신 도메인은 상용기준으로 CA가 발급한 인증서만 사용 가능하며 사설 인증서는 허용하지 않는다.
수신 도메인에 prefix (wechat) 추가 및 마지막에 앱ID 를 추가 해야한다.
(ex : https://biz.uconnect.co.kr/wechat/message/wx57a91116a1 )
자세한 사항은 아래 링크 참조하세요.
https://developers.weixin.qq.com/doc/offiaccount/en/Basic_Information/Access_Overview.html
12.1.3시퀀스 다이어그램 (Sequence Diagram)
12.2수신
12.2.1용어설명
SENDER_KEY : Wechat APP ID(앱 ID)
USER_KEY : Wechat 사용자 KEY 값
12.2.2사용자 메시지 수신
path : /wechat/message
method : POST
header
Content-type: application/json
request body에 Json 형태의 데이터 전달
수신 URL Sample : https://biz.uconnect.co.kr/wechat/message( 수신도메인 + 메시지 수신 path )
키 | 타입 | 설명 |
|---|---|---|
chat_type | text | 값(고정) : WECHAT |
user_key | text | 메시지를 발송한 사용자 키 |
sender_key | text | 메시지를 APP ID |
touser | text | 메시지를 전송한 사용자 키 |
time | number | 메시지 전달 상담톡 서버 시각 (실제 유저가 입력한 시각은 아님) |
serial_number | number | 메시지 고유 id |
type | text | 사용자가 전송한 메시지 종류 (text,image,voice,video,shortvideo,location,link,file) |
content | text | 사용자가 전송한 메시지 |
attachment | boolean | 사용자가 전송한 메시지가 1000자를 초과하는 경우 - 3000byte 까지 자른 메시지를 content 필드로 전달 - 전체 메시지는 장문 메시지 API 를 이용해서 사용 |
url | text | type 이 image or link 일경우 사용 |
media_id | text | type 이 image, voice, video, shortvideo, file 일 경우 사용 |
thumb_media_id | text | type 이 video, shortvideo 일 경우 사용 |
format | text | type 이 voice 일 경우 사용 Voice format(amr) |
recognition | text | 음성을 text 로 변환한 결과 type 이 voice 일 경우 사용 (Official Account 에 voice recognition 이 활성화 되어있어야 한다) |
location_x | text | type 이 location 일 경우 위도 |
location_y | text | type 이 location 일 경우 경도 |
scale | text | type 이 location 일 경우 Map scale |
location_lable | text | type 이 location 일 경우 정보 |
title | text | type 이 link or file 일 경우 Title |
description | text | type 이 link or file 일 경우 Description |
e164 | text | user_key 로 찾은 전화번호 |
user_id | text | user_key 로 찾은 사용자 id |
user_name | text | user_key 로 찾은 사용자 이름 |
agree_type | int | 동의유형(0:기본, 1:1회성동의) |
12.2.3Following/Unfollowing Event
path : /wechat/event
method : POST
header
Content-type: application/json
키 | 타입 | 설명 | 예제 |
|---|---|---|---|
chat_type | text | ||
user_key | text | 메시지를 발송한 사용자 키 | |
app_user_id | number | 메시지를 발신한 사용자의 앱 유저 아이디 (없을 경우 null로 표시) | |
sender_key | text | 메시지를 수신한 발신프로필 키 | |
reference | json | 고객사에서 설정한 메타정보 extra : 버튼을 통해 전달된 메타 정보 | "reference":{ "extra":"고객사에서 관리되는 커스텀한 메타 정보가 전달" } |
last_reference | json | 고객사에서 설정한 메타 정보가 없을 경우 가장 마지막 정보 extra : 버튼을 통해 전달된 메타 정보 bot: 상담을 어떻게 시작했는지 값 bot_event : 봇으로 상담 시작 시, 봇블럭 이벤트 값 created_at : 마지막 메타 정보 생성 | "last_reference":{ "extra":"객사에서 관리되는 커스텀한 메타 정보가 전달", "created_at":"2019-07-21T19:34:29.5", "bot":"true", "bot_event":"TEST_EVENT" } |
session_id | text | 세션 아이디 | "session_id":"123 |