카카오 플러스친구 API 연동 with Node.js

(안내) 이 글은 카카오 오픈빌더에 맞추어 새로 작성되었습니다. 카카오 오픈빌더와 외부 API 연동(feat.Nodejs)

(안내) 2019년 초부터 카카오 플러스 친구 정책 변경으로 신규 가입자는 본 글에 작성된 방식으로 외부 API를 사용할 수 없고 카카오 i 오픈빌더를 통해서만 스마트 채팅 제작이 가능합니다. 

본론에 들어가기 앞서, 카카오 플러스친구는 스마트 채팅이라는 자동 응답기능을 제공하는데요.

관리자 페이지의 스마트 채팅 메뉴에 들어가면 FAQ형과 API형을 선택할 수 있습니다.

FAQ는 10개 정도되는 질문과 그에 해당하는 답변을 관리자가 미리 입력하여 사용하는 간단한 형태입니다.

이에 반해 API형은 챗봇 등에 연결하거나 cs분석을 위해 별도의 DB에 기록하는 등 고객의 대화내용에 따라 여러가지 기능을 수행할 수 있도록 관리자가 개발한 API을 플러스 친구에 연결할 수 있는 기능입니다.

FAQ 형태는 어렵지 않으므로 따로 설명하지 않고 플러스친구와 API를 연동하는 방법을 알아보겠습니다.

카카오 플러스 친구 계정과 플러스 친구는 생성한 것으로 간주하고 설명을 진행하겠습니다.

기본 예제 코드는 https://github.com/LeckererDarr/kakaoApiWithNode/blob/master/app.js를 참고했으니 필요하시다면 참고하세요.

1.API 문서 확인

스마트채팅 메뉴에서 API형을 선택하면 위와 같은 화면을 볼 수 있습니다.

여기서 우측 상단에 API Document 버튼을 누르면 API와 관련된 문서를 볼 수 있습니다.

관심있으시다면 한 번 정독하는 것을 권장드리며, 그중에 핵심이 되는 내용을 간단하게 알아보겠습니다.

1.플러스친구 api는 user_key라는 해시 된 유저 식별값을 취급하며, 이 값은 외부에 노출되지 않는 것을 권장합니다. 즉 보관해야 하는 경우라면 암호화 하라 이런 내용입니다.

2.HTTPS (SSL) 프로토콜을 권장합니다. 필수 사항은 아닙니다.

3.API 응답이 5초 이상 지연되면 응답없음 메세지가 사용자에게 보여집니다. 서버 네트워크 상태나 로직을 5초 이내 응답이 가능하도록 최적화 해야한다는 내용입니다.

2.API 개설(라우트 개설)

실제 API와 관련된 내용은 API Document의 API SPEC 메뉴에 작성 되어있습니다.

우리가 이 문서에서 필수적으로 개설해야 할 부분은 /keyboard (Get방식) /message (Post방식) API 입니다.

- keyboard

/keyboard는 사용자가 처음 플러스친구와 대화창을 개설 했을 때 호출됩니다.

keyboard의 응답 케이스는 type에 따라 2가지로 나눌 수 있으며, 가능한 type은 buttons와 text(text는 문서에 나와있지 않습니다)가 있습니다.

buttons는 대화창 개설 시 버튼 목록을 보여주고, text는 직접 사용자 입력을 받게됩니다.

아래 keyboard 라우트의 예제와 화면을 보시겠습니다.

var express = require('express');
var app = express();
var bodyParser = require('body-parser');

app.get('/keyboard',function(req,res){
  let answer = {
    "type" : "buttons",
    "buttons" : ["회원가입", "예약하기", "회원탈퇴"]
  };
  res.send(answer);
});

app.listen(3000,function(){
  console.log(`Connect 3000 port!`)
});

var express = require('express');
var app = express();
var bodyParser = require('body-parser');

app.get('/keyboard',function(req,res){
  let answer = {
    "type" : "text"
  };
  res.send(answer);
});

app.listen(3000,function(){
  console.log(`Connect 3000 port!`)
});

위에 설명한대로 플러스친구 추가 후 채팅창을 열게되면 Get방식으로 /keyboard 라우트를 호출하고 그에 대한 응답이 대화창에 표시되게 됩니다.

룰 베이스라면 buttons, 일상 대화가 학습된 NLU 모델이라면 text를 사용할 수 있겠습니다.

- Message

/Message는 사용자가 채팅 입력 시 호출됩니다. 이는 Post로 호출되니 이 부분을 유의하시기 바랍니다.

우선 Message 사용자 입력이 어떻게 들어오는지 확인하기 위해 간단한 예제를 만들어봤습니다.

var express = require('express');
var app = express();
var bodyParser = require('body-parser');

app.get('/keyboard',function(req,res){
  let answer = {
    "type" : "buttons",
    "buttons" : ["회원가입", "예약하기", "회원탈퇴"]
  };
  res.send(answer);
});

app.post('/message', function(req,res){
  let user_key = decodeURIComponent(req.body.user_key); // user's key
  let type = decodeURIComponent(req.body.type); // message type
  let content = decodeURIComponent(req.body.content); // user's message
  console.log(user_key);
  console.log(type);
  console.log(content);

  let answer = {
    "message":{
      "text":"your message is arrieved server : "+content // in case 'text'
    }
  }
  res.send(answer);
});

app.listen(3000,function(){
  console.log(`Connect 3000 port!`)
});

/message를 위의 예제와 같이 작성하면 user_key, 사용자가 보낸 메세지의 type, 사용자가 보낸 메세지의 본문(content)를 로그로 확인할 수 있습니다.

이에 비추어 볼때, 사용자 입력의 type은 text와 photo 두 가지를 제공하는 것으로 보입니다.

(플러스 친구 대화창에 동영상은 전송되지 않았습니다.)

또한 이미지는 카카오 서버에 저장된 것으로 추정되는 url이 보여지고 있습니다.

사용자 key에 따라, 혹은 사용자 입력이 text일 때, photo일 때에 대한 처리를 다르게 해준다면 다양한 기능을 수행하도록 할 수 있겠습니다.

message의 response는 여러가지 형태로 가능하며 그 내용은 아래와 같습니다.

1.text 응답

2.이미지 응답

3.링크 버튼 응답

4.버튼 목록 응답

각 경우를 조합한 코드와 화면을 보겠습니다.

var express = require('express');
var app = express();
var bodyParser = require('body-parser');

app.use(bodyParser.json());

app.get('/keyboard',function(req,res){
  let answer = {
    "type" : "buttons",
    "buttons" : ["회원가입", "예약하기", "회원탈퇴"]
  };
  res.send(answer);
});

app.post('/message', function(req,res){
  let answer = {};

  if(content=="회원가입"){
    // text, 이미지 응답과 버튼목록 (1, 2, 4)
    answer = {
      "message": {
        "text": "회원가입이 완료되었습니다.",
        "photo": {
          "url": "https://github.com/LeckererDarr/Yuddomack/blob/master/KakaoTalk_Photo_2018-02-14-13-31-31.jpeg?raw=true",
          "width": 640,
          "height": 480
        },
      },
      "keyboard": {
        "type": "buttons",
        "buttons": ["회원가입", "예약하기", "회원탈퇴"]
      }
    };
  } else if(content=="예약하기"){
    // text, 이미지, 링크버튼 응답 (1, 2, 3, 4)
    answer = {
      "message": {
        "text": "예약이 완료되었습니다. 자세한 일정은 아래 링크에서 확인하세요",
        "photo": {
          "url": "https://github.com/LeckererDarr/Yuddomack/blob/master/KakaoTalk_2018-02-14-13-31-09_Photo_10.jpeg?raw=true",
          "width": 200,
          "height": 480
        },
        "message_button": {
          "label": "일정확인",
          "url": "http://yuddomack.tistory.com"
        }
      },
      "keyboard": {
        "type": "buttons",
        "buttons": ["회원가입", "예약하기", "회원탈퇴"]
      }
    };
  } else if(content=="회원탈퇴"){
    // text응답 (1)
    answer = {
      "message": {
        "text": "정말 회원탈퇴를 원하신다면 '정말탈퇴'라고 입력하세요",
      },
      "keyboard": {
        "type": "text"
      }
    };
  } else if(content=="정말탈퇴"){
    // text응답 (1)
    answer = {
      "message": {
        "text": "회원탈퇴가 완료되었습니다.",
      },
      "keyboard": {
        "type": "buttons",
        "buttons": ["회원가입", "예약하기", "회원탈퇴"]
      }
    };
  } else{
    answer = {
      "message": {
        "text": "잘못된 입력입니다.",
      },
      "keyboard": {
        "type": "buttons",
        "buttons": ["회원가입", "예약하기", "회원탈퇴"]
      }
    };
  }

  res.send(answer);
});

app.listen(3000,function(){
  console.log(`Connect 3000 port!`)
});

보여주기 식으로 작성된 코드라 너저분해 보이지만 각 버튼 입력에 따라 아래와 같은 화면이 나오게 됩니다.

시작은 /keyboard가 호출됩니다

회원가입을 누르면 텍스트, 이미지와 버튼목록이 보입니다.

예약하기를 누르면 텍스트, 이미지, url 링크 버튼이 보입니다.

회원탈퇴를 누르면 텍스트 응답이 보이고 직접 입력이 가능합니다.

정말탈퇴를 입력하면 텍스트 응답이 보이고 버튼 목록이 등장합니다.

각 케이스에 따라 챗봇 연동, 외부 DB작업 등 다양하게 응용하실 수 있습니다.

3.API 등록

이렇게 API가 준비됐다면 다시 관리화면으로 가서 아래와 같이 API의 URL을 입력하고 테스트 버튼을 누릅니다.

정상적으로 세팅이 되었다면 keyboard OK라는 상태를 볼 수 있습니다. 만약 이 부분에서 에러가 난다면 API 서버의 코드나 네트워크 상태를 확인해봐야합니다.

실질적으로 keyboard 라우트만 개설되어있다면 API형을 이용할 수 있지만 사용자가 입력했을때 

사용자 봇 서버에 에러가 감지되었습니다.

내용 : [잘못된 응답입니다. response is not OK(200) : 404 / Not Found]

이런 메세지를 출력하게 됩니다.

친구삭제, 방 나가기 등의 API가 존재하지만 서비스와 크게 상관있는 부분이 아니므로 생략하겠습니다.

4.요약

* Get방식의 /keyboard 라우트가 첫 화면 역할을 합니다.

* Post방식의 /message 라우트가 사용자와 대화를 처리합니다.

* 앱 URL을 입력할때 url주소/keyboard까지 입력하지말고 url주소만 정확히 입력해주세요. 실수할 수 있는 부분입니다.

이상으로 node와 express를 사용해서 카카오 플러스친구 API를 사용하는 법을 마치겠습니다.