KakaoTalk

Todos los conectoresBandeja de entradaKakaoTalk

Lista de verificación de configuración#

La tarjeta de KakaoTalk en Make Agent Fast muestra esta lista con tus propios valores ya rellenados, así que la mayoría de los propietarios trabajan directamente desde ahí. Todos los pasos se realizan en la consola de Kakao, excepto los dos campos que se indican más abajo.

1. Crea un bot en Kakao i Open Builder. Un bot contiene todos los bloques de escenario con los que responde el canal; omite este paso si el canal ya tiene un bot que puedas editar.
2. Añade una skill y establece su URL con la Skill URL del conector; después añade un encabezado de solicitud personalizado X-Kakao-Bot-Secret con tu Bot secret. Kakao no firma las solicitudes de las skills, así que ese encabezado es la única prueba de que una llamada procede de tu bot.
3. Apunta el bloque de respaldo (fallback) a la skill para que todas las preguntas que tus escenarios no gestionen lleguen al agente. Conecta un bloque de escenario con nombre a la misma skill si también quieres que lo responda el agente.
4. Activa la opción de callback para ese bloque. Kakao descarta la respuesta de una skill que tarda más de cinco segundos; con el callback activado, Make Agent Fast devuelve de inmediato una burbuja de espera y publica la respuesta final en userRequest.callbackUrl dentro del minuto durante el cual consideramos válida esa URL de un solo uso.
5. Conecta el canal de KakaoTalk al bot y pega después ese mismo ID de canal en el campo Channel ID del conector en Make Agent Fast.
6. Despliega el bot. Los cambios en Open Builder solo llegan a los visitantes tras un despliegue, y cada cambio posterior en una skill o un bloque requiere otro.

El resto de esta página es la versión detallada de estos mismos seis pasos.

Prepara los recursos de Kakao#

Crea o selecciona la aplicación de Kakao Developers, el canal de KakaoTalk y el bot de Kakao i Open Builder que serán los propietarios de la integración. Consulta la documentación oficial de Open Builder de Kakao sobre skills y bloques.

Reúne o crea estos valores:

El Bot secret es obligatorio en los entornos desplegados de Make Agent Fast porque las llamadas de las skills de Kakao no incluyen una firma de la plataforma. Genera un valor único y de alta entropía, y no reutilices la REST API key como secreto.

Guarda el conector#

Abre la página Canales del agente, elige KakaoTalk Channel, introduce los tres valores y selecciona Conectar. Make Agent Fast valida la REST API key siempre que los permisos de Kakao lo permitan y, tras guardar, muestra la Webhook URL única del conector.

Make Agent Fast no puede crear la skill de Open Builder ni asociarla a un bloque por ti; el resto del trabajo se hace en la consola de Kakao.

Configura la skill de Open Builder#

1. En Kakao i Open Builder, crea una skill para el bot correspondiente.
2. Establece la URL de la skill con la Webhook URL copiada del conector.
3. Añade un encabezado de solicitud personalizado llamado X-Kakao-Bot-Secret cuyo valor coincida exactamente con el Bot secret.
4. Conecta la skill al bloque de respaldo o de escenario que deba invocar al agente.
5. Activa la opción de callback de ese bloque para que las respuestas lentas superen el límite de cinco segundos de las skills de Kakao.
6. Guarda y despliega/publica la configuración del bot según el flujo de trabajo de Kakao.

El encabezado no distingue mayúsculas de minúsculas según las reglas de HTTP, pero el valor del secreto debe ser exacto. Cualquiera que conozca la URL del webhook pero no este secreto recibirá una respuesta de no autorizado.

Prueba las capacidades#

Usa primero la herramienta de prueba de Open Builder y después el canal de KakaoTalk conectado. Envía una pregunta de texto realista en coreano o en otro idioma compatible y confirma la respuesta en línea, el Último mensaje y el hilo en Conversaciones.

La tarjeta del conector copia el cuerpo de solicitud que aparece a continuación; ese mismo cuerpo funciona con curl contra la Skill URL. No incluye callbackUrl, por lo que la respuesta llega en línea, que es lo más sencillo de verificar primero.

{
  "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": {}
  }
}

Una skill en buen estado responde dentro del límite de cinco segundos con una única salida simpleText:

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

Cuando la opción de callback del bloque está activada, Open Builder añade userRequest.callbackUrl a la solicitud. Make Agent Fast responde entonces primero con una burbuja de espera y envía por POST la respuesta final a esa URL de un solo uso:

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

El contrato actual de la skill es solo de texto. La respuesta del agente es un único skillResponse de Kakao versión 2.0 con una salida simpleText, limitada por debajo del máximo de texto de Kakao, que se devuelve en línea o a través de la URL de callback. No se admiten voz, archivos, imágenes ni audio saliente por separado.

Rotar o desconectar#

Para rotar el Bot secret, actualiza el conector y el encabezado personalizado de Open Builder como un único cambio coordinado y prueba de inmediato. Si no coinciden, se detienen todas las solicitudes entrantes. Rota la REST API key en Kakao Developers y en Make Agent Fast antes de revocar la clave anterior.

Desactivar o eliminar el conector no borra la skill ni el bloque de Open Builder. Elimina o desvincula esos objetos del lado del proveedor cuando des de baja definitivamente la integración.

Solución de problemas#

No expongas la REST API key ni el Bot secret en código de cliente ni en documentación pública.