Skip to content
SuksonSukson Developers
Preview: The API is still being rolled out and details may change before launch. Follow progress in the changelog.

Sukson Messaging APIv1 Preview

Build botsfor Sukson chats

Your bot runs on your own server. Sukson sends it the messages that call it, and your bot answers with plain HTTP and JSON.

Get startedAPI reference

Base URLhttps://api.sukson.dev/v1

POST/v1/chats/{chat_id}/messages
Send a message to a chat
curl -X POST \
  https://api.sukson.dev/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"type":"text","text":"Hello!"}]}'
Response 200 OK
{
  "messages": [
    {
      "message_id": 812346,
      "chat_id": "0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10",
      "created": true
    }
  ]
}

How it works

Your first bot in 3 steps

  1. Create a bot

    Create a bot at member.sukson.com/bots and keep its API token (it starts with skbot_). You see it only once.

    Create a bot

  2. Receive the webhook

    A webhook is a URL on your server. When someone calls your bot, Sukson sends that message to this URL as signed JSON.

    Event format

  3. Reply

    Answer with {"reply": "..."} within 10 seconds, or answer 200 first and send messages through the API later.

    Send messages

What you get

Simple to use, easy to verify

Signed webhooks

Every event carries an HMAC-SHA256 signature in X-Sukson-Signature, so you know it really came from Sukson.

Reply tokens

Answer the message that called your bot later, with a reply_token that works once, within 60 seconds.

Clear rate limits

120 requests per minute per bot. Every answer shows what is left in the X-RateLimit-* headers.

Version in the path

Every path starts with the version, such as /v1/me. Changes that would break existing code only come in a new version.

Docs

Make your first call

Call GET /v1/me with your bot token. If you get your bot back, you are ready.

Get started