KakaoTalk

All connectorsInboxKakaoTalk

Setup checklist#

The KakaoTalk card in Make Agent Fast shows this list with your own values already filled in, so most owners work through it there. Every step happens in Kakao's console except the two fields marked below.

1. Create a bot in Kakao i Open Builder. One bot holds every scenario block the channel answers with; skip this step when the channel already has a bot you can edit.
2. Add a skill and set its URL to the connector's Skill URL, then add a custom request header X-Kakao-Bot-Secret carrying your Bot secret. Kakao does not sign skill requests, so that header is the only proof a call came from your bot.
3. Point the fallback block at the skill so every question your scenarios do not handle reaches the agent. Wire a named scenario block to the same skill when it should be answered by the agent too.
4. Turn on the callback option for that block. Kakao drops a skill response that takes longer than five seconds; with the callback on, Make Agent Fast returns a waiting bubble immediately and posts the finished answer to userRequest.callbackUrl within the minute we treat that single-use URL as live.
5. Connect the KakaoTalk Channel to the bot, then paste the same channel ID into the connector's Channel ID field in Make Agent Fast.
6. Deploy the bot. Open Builder changes reach visitors only after a deploy, and every later skill or block change needs another one.

The rest of this page is the long form of the same six steps.

Prepare Kakao assets#

Create or select the Kakao Developers application, KakaoTalk Channel, and Kakao i Open Builder bot that will own the integration. Review Kakao's official Open Builder documentation for skills and blocks.

Collect or create these values:

The Bot secret is required on deployed Make Agent Fast environments because Kakao skill calls do not provide a platform signature. Generate a unique high-entropy value and do not reuse the REST API key as the secret.

Save the connector#

Open the site's Connectors page, choose KakaoTalk Channel, enter all three values, and select Connect. Make Agent Fast validates the REST API key where Kakao permissions allow it and displays the connector's unique Webhook URL after save.

Make Agent Fast cannot create the Open Builder skill or attach it to a block for you; the remaining work is in Kakao's console.

Configure the Open Builder skill#

1. In Kakao i Open Builder, create a skill for the intended bot.
2. Set the skill URL to the connector's copied Webhook URL.
3. Add a custom request header named X-Kakao-Bot-Secret whose value exactly matches Bot secret.
4. Connect the skill to the fallback or scenario block that should invoke the agent.
5. Turn on that block's callback option so slow answers survive Kakao's five-second skill deadline.
6. Save and deploy/publish the bot configuration according to Kakao's workflow.

The header is case-insensitive by HTTP rules, but the secret value is exact. Anyone who knows the webhook URL but not this secret should receive an unauthorized response.

Test capabilities#

Use the Open Builder test tool first, then the connected KakaoTalk Channel. Send a realistic Korean or supported-language text question and confirm the inline answer, Last message, and Conversations thread.

The connector card copies the request body below; the same body works with curl against the Skill URL. It carries no callbackUrl, so the answer comes back inline — the simpler thing to verify first.

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

A healthy skill answers within the five-second deadline with one simpleText output:

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

Once the block's callback option is on, Open Builder adds userRequest.callbackUrl to the request. Make Agent Fast then answers with a waiting bubble first and POSTs the finished reply to that single-use URL:

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

The current skill contract is text-only. The agent reply is one Kakao skillResponse version 2.0 with a simpleText output, capped below Kakao's text limit, returned inline or on the callback URL. Voice, files, images, and separate outbound audio are not supported.

Rotate or disconnect#

To rotate the Bot secret, update the connector and the Open Builder custom header as one coordinated change, then test immediately. A mismatch stops every inbound request. Rotate the REST API key in Kakao Developers and Make Agent Fast before revoking the old key.

Disabling or removing the connector does not delete the Open Builder skill or block. Remove or detach those provider-side objects when permanently decommissioning the integration.

Troubleshooting#

Do not expose the REST API key or Bot secret in client code or public documentation.