KakaoTalk

Все коннекторыВходящиеKakaoTalk

Чек-лист настройки#

Карточка KakaoTalk в Make Agent Fast показывает этот список с уже заполненными вашими значениями, поэтому большинство владельцев проходят его там. Каждый шаг происходит в консоли Kakao, кроме двух полей, отмеченных ниже.

1. Создайте бота в Kakao i Open Builder. Один бот содержит каждый блок сценария, которым отвечает канал; пропустите этот шаг, если у канала уже есть бот, которого вы можете редактировать.
2. Добавьте скилл и установите его URL в URL скилла коннектора, затем добавьте пользовательский заголовок запроса X-Kakao-Bot-Secret, несущий ваш Секрет бота. Kakao не подписывает запросы скилла, поэтому этот заголовок — единственное доказательство, что вызов пришёл от вашего бота.
3. Направьте резервный блок на скилл, чтобы каждый вопрос, который ваши сценарии не обрабатывают, достигал агента. Подключите именованный блок сценария к тому же скиллу, когда он тоже должен отвечаться агентом.
4. Включите опцию обратного вызова для этого блока. Kakao отбрасывает ответ скилла, занимающий больше пяти секунд; с включённым обратным вызовом Make Agent Fast сразу возвращает пузырь ожидания и отправляет готовый ответ на userRequest.callbackUrl в течение минуты, в которую мы считаем этот одноразовый URL живым.
5. Подключите KakaoTalk-канал к боту, затем вставьте тот же ID канала в поле Channel ID коннектора в Make Agent Fast.
6. Разверните бота. Изменения Open Builder достигают посетителей только после развёртывания, и каждое последующее изменение скилла или блока требует ещё одного.

Остальная часть этой страницы — развёрнутая форма тех же шести шагов.

Подготовьте ресурсы Kakao#

Создайте или выберите приложение Kakao Developers, KakaoTalk-канал и бота Kakao i Open Builder, которые будут владеть интеграцией. Изучите официальную документацию Open Builder Kakao о скиллах и блоках.

Соберите или создайте эти значения:

Секрет бота обязателен на развёрнутых окружениях Make Agent Fast, потому что вызовы скилла Kakao не предоставляют платформенную подпись. Сгенерируйте уникальное значение с высокой энтропией и не используйте REST API ключ как секрет.

Сохраните коннектор#

Откройте страницу Коннекторы сайта, выберите KakaoTalk-канал, введите все три значения и нажмите Подключить. Make Agent Fast проверяет REST API ключ, где позволяют разрешения Kakao, и показывает уникальный URL вебхука коннектора после сохранения.

Make Agent Fast не может создать скилл Open Builder или привязать его к блоку за вас; оставшаяся работа — в консоли Kakao.

Настройте скилл Open Builder#

1. В Kakao i Open Builder создайте скилл для нужного бота.
2. Установите URL скилла в скопированный URL вебхука коннектора.
3. Добавьте пользовательский заголовок запроса X-Kakao-Bot-Secret, значение которого точно совпадает с Секретом бота.
4. Подключите скилл к резервному блоку или блоку сценария, который должен вызывать агента.
5. Включите опцию обратного вызова этого блока, чтобы медленные ответы переживали пятисекундный дедлайн скилла Kakao.
6. Сохраните и разверните/опубликуйте конфигурацию бота по процессу Kakao.

Заголовок нечувствителен к регистру по правилам HTTP, но значение секрета точное. Любой, кто знает URL вебхука, но не этот секрет, должен получить неавторизованный ответ.

Протестируйте возможности#

Сначала используйте тестовый инструмент Open Builder, затем подключённый KakaoTalk-канал. Отправьте реалистичный корейский или поддерживаемый языковой текстовый вопрос и подтвердите встроенный ответ, Последнее сообщение и ветку в Диалогах.

Карточка коннектора копирует тело запроса ниже; то же тело работает с curl против URL скилла. Оно не несёт 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": {}
  }
}

Здоровый скилл отвечает в пределах пятисекундного дедлайна одним выводом simpleText:

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

Когда опция обратного вызова блока включена, Open Builder добавляет userRequest.callbackUrl в запрос. Make Agent Fast тогда сначала отвечает пузырём ожидания и отправляет POST готового ответа на этот одноразовый URL:

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

Текущий контракт скилла только текстовый. Ответ агента — один Kakao skillResponse версии 2.0 с выводом simpleText, ограниченный ниже текстового лимита Kakao, возвращаемый встроенным или на URL обратного вызова. Голос, файлы, изображения и отдельное исходящее аудио не поддерживаются.

Ротация или отключение#

Чтобы ротировать Секрет бота, обновите коннектор и пользовательский заголовок Open Builder как одно скоординированное изменение, затем немедленно протестируйте. Несовпадение останавливает каждый входящий запрос. Ротируйте REST API ключ в Kakao Developers и Make Agent Fast перед отзывом старого ключа.

Отключение или удаление коннектора не удаляет скилл или блок Open Builder. Удалите или отсоедините эти объекты на стороне провайдера при окончательном выводе интеграции из эксплуатации.

Решение проблем#

Не раскрывайте REST API ключ или Секрет бота в клиентском коде или публичной документации.