카카오톡

모든 커넥터받은 편지함카카오톡

설정 체크리스트#

Make Agent Fast의 카카오톡 카드에는 아래 목록이 내 값으로 채워진 채 표시되므로, 대부분은 그 화면에서 그대로 따라가면 됩니다. 아래 표시한 두 입력란을 빼면 모든 단계는 카카오 콘솔에서 진행합니다.

1. 카카오 i 오픈빌더에서 봇을 만듭니다. 채널이 답변하는 시나리오 블록은 모두 이 봇 안에 있습니다. 수정할 수 있는 봇이 이미 있다면 이 단계는 건너뛰세요.
2. 스킬을 추가하고 스킬 URL을 커넥터의 스킬 URL로 지정한 뒤, 봇 시크릿을 담은 커스텀 요청 헤더 X-Kakao-Bot-Secret을 추가합니다. 카카오는 스킬 요청에 서명하지 않으므로, 이 헤더가 내 봇에서 온 요청이라는 유일한 증거입니다.
3. 폴백 블록이 스킬을 사용하도록 연결해 시나리오가 처리하지 못한 모든 질문이 에이전트에 도달하게 합니다. 특정 시나리오 블록도 에이전트가 답하게 하려면 같은 스킬에 연결하세요.
4. 그 블록의 콜백 옵션을 켭니다. 카카오는 5초를 넘긴 스킬 응답을 버리지만, 콜백이 켜져 있으면 Make Agent Fast가 먼저 대기 말풍선을 보내고 완성된 답변을 userRequest.callbackUrl로 보냅니다. 이 일회용 URL은 1분 동안만 유효한 것으로 취급합니다.
5. 카카오톡 채널을 봇에 연결한 뒤, 같은 채널 ID를 Make Agent Fast 커넥터의 채널 ID 입력란에 넣습니다.
6. 봇을 배포합니다. 오픈빌더의 변경 사항은 배포해야 실제 이용자에게 적용되며, 이후 스킬이나 블록을 바꿀 때마다 다시 배포해야 합니다.

이 문서의 나머지 부분은 같은 여섯 단계를 자세히 풀어 쓴 것입니다.

Kakao 자산 준비하기#

통합을 소유할 Kakao Developers 애플리케이션, 카카오톡 채널, Kakao i Open Builder 봇을 만들거나 선택합니다. 스킬과 블록은 Kakao 공식 Open Builder 문서를 확인하세요.

다음 값을 수집하거나 생성합니다.

Kakao 스킬 호출에는 플랫폼 서명이 없기 때문에 배포된 Make Agent Fast 환경에서는 봇 시크릿이 필수입니다. 엔트로피가 높은 고유 값을 만들고 REST API 키를 시크릿으로 재사용하지 마세요.

커넥터 저장하기#

사이트의 커넥터 페이지에서 카카오톡 채널을 선택하고 세 값을 입력한 뒤 연결을 누릅니다. Make Agent Fast는 Kakao 권한이 허용하는 범위에서 REST API 키를 검증하고 저장 후 고유 웹훅 URL을 표시합니다.

Make Agent Fast는 Open Builder 스킬을 생성하거나 블록에 연결할 수 없습니다. 남은 작업은 Kakao 콘솔에서 수행합니다.

Open Builder 스킬 설정하기#

1. Kakao i Open Builder에서 대상 봇의 스킬을 만듭니다.
2. 스킬 URL을 복사한 커넥터 웹훅 URL로 설정합니다.
3. 이름이 X-Kakao-Bot-Secret이고 값이 봇 시크릿과 정확히 같은 커스텀 요청 헤더를 추가합니다.
4. 에이전트를 호출할 폴백 또는 시나리오 블록에 스킬을 연결합니다.
5. 느린 답변이 카카오의 5초 스킬 제한을 넘겨도 살아남도록 해당 블록의 콜백 옵션을 켭니다.
6. Kakao 흐름에 따라 봇 설정을 저장하고 배포/게시합니다.

HTTP 규칙상 헤더 이름은 대소문자를 구분하지 않지만 시크릿 값은 정확히 일치해야 합니다. 웹훅 URL만 알고 시크릿을 모르는 요청은 unauthorized 응답을 받아야 합니다.

기능 테스트#

먼저 Open Builder 테스트 도구를 사용하고 그다음 연결된 카카오톡 채널에서 테스트합니다. 실제 한국어 또는 지원 언어 텍스트 질문을 보내 인라인 답변, 마지막 메시지, 대화 스레드를 확인하세요.

커넥터 카드가 복사해 주는 요청 본문은 아래와 같으며, 같은 본문을 스킬 URL에 curl로 보내도 됩니다. callbackUrl이 없으므로 답변이 인라인으로 돌아오며, 먼저 확인하기에 가장 간단한 경로입니다.

{
  "intent": {
    "id": "5a56ec0cf65e53002d34e0f4",
    "name": "Fallback block"
  },
  "userRequest": {
    "timezone": "Asia/Seoul",
    "utterance": "What are your opening hours?",
    "lang": "kr",
    "user": {
      "id": "kakao-test-user",
      "type": "botUserKey",
      "properties": {
        "plusfriendUserKey": "kakao-test-user"
      }
    },
    "block": {
      "id": "5a56ec0cf65e53002d34e0f4",
      "name": "Fallback block"
    }
  },
  "bot": {
    "id": "5a56ec0cf65e53002d34e0f2",
    "name": "Your bot"
  },
  "action": {
    "id": "5a56ec0cf65e53002d34e0f6",
    "name": "Make Agent Fast skill",
    "params": {},
    "detailParams": {},
    "clientExtra": {}
  }
}

정상이라면 5초 제한 안에 simpleText 출력 하나로 응답합니다.

{
  "version": "2.0",
  "template": {
    "outputs": [
      {
        "simpleText": {
          "text": "We are open 9:00–18:00 on weekdays."
        }
      }
    ]
  }
}

블록의 콜백 옵션을 켜면 오픈빌더가 요청에 userRequest.callbackUrl을 함께 보냅니다. 그러면 Make Agent Fast는 먼저 대기 말풍선으로 응답하고, 완성된 답변을 그 일회용 URL로 POST합니다.

{
  "version": "2.0",
  "useCallback": true,
  "data": {
    "text": "One moment — I am looking that up."
  }
}

현재 스킬 계약은 텍스트 전용입니다. 에이전트 답변은 Kakao skillResponse 버전 2.0의 simpleText 출력 하나로, Kakao 텍스트 제한보다 작게 잘려 인라인 또는 콜백 URL로 전달됩니다. 음성, 파일, 이미지, 별도 발신 오디오는 지원하지 않습니다.

교체 또는 연결 해제#

봇 시크릿을 교체할 때는 커넥터와 Open Builder 커스텀 헤더를 한 번의 조정된 변경으로 업데이트하고 즉시 테스트합니다. 값이 다르면 모든 수신 요청이 중단됩니다. 이전 키를 폐기하기 전에 Kakao Developers와 Make Agent Fast의 REST API 키를 모두 교체하세요.

커넥터를 끄거나 삭제해도 Open Builder 스킬이나 블록은 삭제되지 않습니다. 영구 종료할 때 제공자 측 객체를 제거하거나 분리하세요.

문제 해결#

REST API 키와 봇 시크릿을 클라이언트 코드나 공개 문서에 노출하지 마세요.