Getting started

Before you start you need two things: a Sukson member account and a server that accepts HTTPS from the internet (port 443 or 8443).

1. Create a bot

   Go to member.sukson.com/bots and create a bot. Choose a display name (A–Z, a–z, 0–9 only) and a handle, the name people type after @ to call the bot. The handle ends in _bot and can’t be changed later.

2. Keep the API token

   The API token is the key your bot sends with every API call. After you create the bot you see its token, starting with skbot_, once. Store it in a secret manager or an environment variable on your server. If you lose it, issue a new one on the bot’s page (authentication).

   Try it: if this call returns your bot, the token works.

   export SUKSON_BOT_TOKEN="skbot_..."
   curl -s https://api.sukson.dev/v1/me \
     -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

3. Set the webhook

   The webhook is the URL on your server that Sukson sends messages to. Make sure it checks signatures first (code samples), then set it on the bot’s page or through the API:

   curl -s -X PUT https://api.sukson.dev/v1/me/webhook \
     -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://bot.example.com/sukson"}'

   Before saving, Sukson sends a test ping event signed with a new secret. Your server must answer 2xx within 10 seconds for the URL to be saved. The API’s answer contains the secret (the webhook secret), shown once. Keep it to verify signatures.

4. Add the bot to a chat

   Open the chat’s info page and add the bot. You can do this in chats you own or administer (public rooms, groups and channels). One bot can be in several chats; how many depends on its plan. List them with GET /v1/me/chats.

5. Call your bot

   Type @handle hello in the chat. Your server receives a message event. Answer it with {"reply": "Hi there"} or call POST /v1/chats/{chat_id}/messages.

Test the webhook again

Call POST /v1/me/webhook/test to send a signed ping to the current URL. The answer gives a category (such as http_200 or timeout) and the time it took (webhook API).

Next steps

• Read Webhooks in full before going live, especially signature checks, de-duplication and the retry rules.
• Use the reply token when you need more time to answer (up to 60 seconds).
• Check the limits and your plan’s monthly quota.