Quick start

The complete minimal path

Eight steps take you from creating a bot to its first interactive response.

1. Create a bot.
2. Get a token.
3. Configure a webhook.
4. Verify the signature.
5. Receive /start.
6. Send a response.
7. Add a button.
8. Test in Key Chat.

Create a bot

Open Bots in Key Chat, select Add bot, and set its name, username and description. The username must end in _bot.

Get a token

Issue a token after creating the bot. It is shown once; keep it secret and never ship it in client-side code.

Configure a webhook

Enter a public HTTPS URL in the existing bot’s editor and save it. Key Chat reveals the kcwhsec_… signing secret once; copy it to your server as KEYCHAT_WEBHOOK_SECRET.

Events are delivered at least once, so deduplicate them by id. Rotate secret invalidates the old value immediately; enabling or disabling the webhook does not rotate it.

Verify the signature

Verify X-KeyChat-Timestamp and the HMAC SHA-256 value in X-KeyChat-Signature before processing an event.

Receive /start

Installing a bot emits message.created with /start and a new session_id.

Send a response

Use the Runtime API with the event chat_id and your bot token.

curl -X POST https://chat.wokey.pro/_keychat/v1/bot/messages \
  -H "Authorization: Bearer $KEYCHAT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"<chat_id>","content":{"text":"Hello!"},"idempotency_key":"hello-001"}'

Add a button

Send keyboard or menu as a two-dimensional row array. A row may contain up to ten buttons.

Test in Key Chat

Add the bot to your chats. You can also use @echo_bot as a platform check: it returns every message it receives.

SDK practice

Start with a minimal message.created handler and add event types gradually. Keep the bot token and webhook secret in environment variables, then verify the public endpoint with a test event from the bot editor.

The first reply must use the chat_id from the incoming event. Do not key data by display_name or username; use UUIDs and session_id for durable relations.

await bot.sendMessage({
  chat_id: chatId,
  content: { text: '**Ready**', format: 'markdown' },
  idempotency_key: crypto.randomUUID()
});