13.1개요

• 본 문서는 WeChat Biz 상담톡(이하, 상담톡) API를 이용하여, 상담을 요청한 사용자와의 채팅에서 메시지를 수신/발신하기 위한 API 문서이다.

• 본 문서는 https 프로토콜을 통해 데이터를 json 형식으로 가공하여 GET, POST method를 사용하여 전송하고, json형식의 결과 데이터를 parsing하여 처리할 수 있음을 전제로 작성되었다.

13.2용어 정의

13.2.1공중 계정(Sender Key)

• WeChat 의 비즈니스용 계정이다.

• 카카오톡 채널 홈페이지(https://mp.weixin.qq.com/)를 통해 개설 할수 있다.

13.2.2상담 세션(Session)

• 상담원이 고객에게 메시지를 전송하기 위한 필수 조건으로, 세션이 연결된 상태에서만 상담원은 고객에게 메시지를 전송할 수 있다.

• 고객의 상담 요청이 WeChat Biz 서버에 정상적으로 전송되면 세션이 생성과 동시에 시작된다.

• 고객은 상담 버튼을 클릭하여 상담을 요청하거나, 채팅방에서 메시지를 전송하여 상담 요청을 할 수 있다.

• 상담원이 상담 종료를 요청하면 상담 세션은 종료된다.

13.2.3사용자 키 (User Key)

• 특정 WeCHat 사용자를 구분하기 위한 key로, 고객이 상담을 요청한 시점에 제공된다.

• User Key는 공중계정별로 사용자에 대해 다르게 발급된다. 따라서 User Key는 해당 공중 계정에 대해서만 유효하다.

13.2.4상담원의 정의

• 상담원은 상담톡 API를 이용하는 주체를 의미하며 반드시 사람을 지칭하는 것은 아닙니다.

• 상담을 위하여 유저에게 상담원(사람)이 배정 되었는지 여부는 알 수 없습니다.

13.2.5상담 메시지

• 상담원 유저한테 보낸 대화 메시지, 유저가 상담원한테 보낸 메시지 모두 상담 메시지로 합니다.

13.3선결 조건

메시지 API를 사용하여 메시지 전송을 대행하기 위해 아래의 조건이 선결되어야 한다.

• WeChat 공중 계정에 가입되어 있어야 한다.

13.4API 스펙

13.4.1[서버] sip 서버

13.4.2메시지 발신

[Request]

POST /chat/write

[Parameter]

[Parameter > Message]

• 이미지 (message_type : "image")

예시

{
  "media_id": "MEDIA_ID"
}

• 음성 (message_type : "voice")

예시

{
  "media_id": "MEDIA_ID"
}

• 비디오 (message_type : "video")

예시

{
  "media_id": "MEDIA_ID",
  "thumb_media_id": "MEDIA_ID",
  "title": "TITLE",
  "description": "DESCRIPTION"
}

• 음악 (message_type : "music")

예시

{
  "title": "MUSIC_TITLE",
  "description": "MUSIC_DESCRIPTION",
  "musicurl": "MUSIC_URL",
  "hqmusicurl": "HQ_MUSIC_URL",
  "thumb_media_id": "THUMB_MEDIA_ID"
}

• NEWS (message_type : "news")

예시

{
  "articles": [
    {
      "title": "Happy Day",
      "description": "Is Really A Happy Day",
      "url": "URL",
      "picurl": "PIC_URL"
    }
  ]
}

• One Article (message_type : "mpnews")

예시

{
  "media_id": "MEDIA_ID"
}

• 메뉴 (message_type : "msgmenu")

예시

{
  "head_content": "Are you satisfied with the service? ",
  "list": [
    {
      "id": "101",
      "content": "Satisfied"
    },
    {
      "id": "102",
      "content": "Dissatisfied"
    }
  ],
  "tail_content": "Looking forward to your visit again"
}

[Response]

13.4.3상담톡 발신 메시지 타입

13.4.3.1텍스트 타입

• 텍스트 타입의 경우 텍스트 메시지 발송만 가능하다.

• 텍스트 글자수는 1000자 제한

13.4.3.2미디어 임시 업로드

• 3일 간 서버에 저장 됩니다.

• 3일 이후에는 만료 됩니다.

[Request]

POST /media/upload

[Header]

Content-type: multipart/form-data

[Parameter]

미디어 타입

• Image: 10 MB. PNG, JPEG, JPG, and GIF formats are supported.

• Voice: 2 MB. The maximum length is 60s. AMR and MP3 formats are supported.

• Video: 10 MB. The MP4 format supported.

• Thumbnail: 64 KB. The JPG format supported.

[Response]

13.4.3.3이미지 업로드(Article 용)

• Article 의 본문에 사용되는 이미지를 업로드 한다.

• 저장 개수 : 5,000 images (공중계정별 )

• JPG/PGN 만 지원

• 1 MB 미만

[Request]

POST /material/upload/img

[Header]

Content-type: multipart/form-data

[Parameter]

[Response]

13.4.3.4미디어 업로드

• 추가되면 URL과 함께 새로운 영구 이미지가 반환된다.

• 외부 도메인 이름에서 사용되는 경우 이미지가 숨겨짐

• 저장한도 : 기사 및 이미지는 5,000개, 기타 유형의 자산은 1,000개

지원 이미지 및 용량

• Image: 10 MB. BMP, PNG, JPEG, JPG, and GIF formats are supported.

• Voice: 2 MB. The maximum length is 60s. MP3, WMA, WAV, and AMR formats are supported.

• Video: 10 MB. The MP4 format supported.

• Thumbnail: 64 KB. The JPG format supported.

[Request]

POST /media/upload

[Header]

Content-type: multipart/form-data

[Parameter]

[Response]

13.4.4블랙리스트

• 블랙리스트를 관리 할수 있다.

• 블랙리스트를 조회, 등록 , 삭제 할수 있다.

13.4.4.1조회

[Request]

GET

• 한번에 최대 10,000 명을 조회할수 있다.

• 10,000명 이상일 경우 begin_openid 에 마지막 조회된 사용자를 넣어서 반복적으로 조회 할수 있다.

[Parameter]

예시

{
  "begin_openid": "OPENID1"
}

[Response]

예시

{
 "total":23000,
 "count":10000,
 "data":{"
    openid":[
       "OPENID1",
       "OPENID2",
       ...,
       "OPENID10000"
    ]
  },
  "next_openid":"OPENID10000"
}

13.4.4.2등록

[Request]

POST

[Parameter]

예시

{
  "openid_list": [
    "OPENID1",
    "OPENID2"
  ]
}

[Response]

13.4.4.3삭제

[Request]

POST

[Parameter]

예시

{
  "openid_list": [
    "OPENID1",
    "OPENID2"
  ]
}

[Response]

13.4.5사용자 정보

• 버튼등을 통해 채팅방 입장시 사용자 정보가 있을경우 가져올수 있다.

• 시용자 정보 인증이 먼저 이루어져야 정상적으로 메시지는 상담원에게 보낼수 있다.

13.4.5.1사용자 정보 조회

[Request]

GET /user/info

[Parameter]

[Response]

[Example]

http://127.0.0.1:8080/user/info?sender_key=da2b0c0d28805157d5355b60beb9493a9b3e5b15&user_key=d14zPgU4yqoO&

{
  "code": "200",
  "message": "OK",
  "user_key": "d14zPgU4yqoO",
  "sender_key": "da2b0c0d28805157d5355b60beb9493a9b3e5b150",
  "user_id": "",
  "user_name": "",
  "tel_number": "1112323",
  "agree_type": 0, 
  "agree_date": "2022-05-11 15:40:04"
}

13.4.5.2사용자 정보 인증

[Request]

POST /user/auth

[Parameter]

[Response]

[Example]

curl -X POST -H "Content-type: application/json" \
  -d '{"user_key":"d74zPgU4yqoO","sender_key":"da2b0c0d28805157d5355b60beb9493a9b3e5b15","app_user_id":null,"user_name":"장형길","user_id":"kenneth","tel_number":"01029113333" }'  \
  http://127.0.0.1:8080/user/auth

{ 
    "code": "200", 
    "message": "OK" 
}

13.4.5.3사용자 정보 인증 철회

[Request]

post /user/auth/delete

[Parameter]

[Response]

[Example]

curl -X POST -H "Content-type: application/json" \
  -d '{"user_key":"d74zPgU4yqoO","sender_key":"da2b0c0d28805157d5355b60beb9493a9b3e5b15" }'  \
  http://127.0.0.1:8080/user/auth/delete

{ 
    "code": "200", 
    "message": "OK" 
}

13.4.6메지시 첨부파일 가져오기

• 메시지 수신시 1000자 이상의 경우 메시지가 첨부파일로 제공 된다.

• 메시지 첨부파일의 경우 일정시간이 이후 kakao 서버에서 파일이 삭제된다.

• 삭제전에 미리 저장된 첨부파일을 불러오는 API 다.

13.4.6.1첨부파일 가져오기

[Request]

GET /message/attachment

[Parameter]

13.4.7첨부파일 가져오기

• 일정시간이 지날경우 kakao 서버에 업로드한 파일이 삭제된다.

• 삭제전에 미리 저장된 첨부파일을 불러오는 API 다.

13.4.7.1첨부파일 가져오기

[Request]

GET /message/file

[Parameter]

13.5코드 정의

13.5.1오류 코드