Overview

The Sukson Messaging API lets members put bots into Sukson chats. Your bot’s code runs on your own server, not on Sukson.

Words you’ll see a lot in these docs:

• An event is what Sukson sends to tell your bot something happened, such as someone calling it in a chat.
• A webhook is a URL on your server that Sukson sends events to.
• The API is the set of Sukson URLs your bot calls to send messages or read data, such as https://api.sukson.dev/v1/me.

1. Someone sends a message that calls the bot in a chat the bot is in.
2. Sukson sends that message as JSON in a POST to the bot’s webhook, with an HMAC signature (to prove it came from Sukson) and a reply_token (to answer it).
3. Your server answers in one of two ways:
   • respond HTTP 200 with {"reply": "..."} within 10 seconds (inline reply), or
   • respond 200 straight away and call POST /v1/chats/{chat_id}/messages later.
4. The bot’s message shows up in the chat right away, like any member’s message.

Which messages reach the bot

trigger	When
mention	The message contains the bot’s @handle
reply	The message replies to one of the bot’s messages
command	The message starts with a /command the bot declared (or /command@handle)
all	Every message, only when the chat owner turned on “see every message” and the bot’s plan allows it

Edited messages, forwarded messages, system messages and messages from bots (including other bots) never reach a bot, so bots can’t get stuck talking to each other.

API design

• One host, https://api.sukson.dev, and every path starts with the version, e.g. /v1/me (versioning).
• Paths that say what they are. me is the bot that owns the token, /v1/me/chats are its chats, /v1/chats/{chat_id}/messages are the messages of one chat.
• JSON everywhere. A successful answer is the data itself. An error is always {message, code, details} (errors).
• Server to server. The API has no CORS. Never call it from a browser, which would leak the token.

What a bot never receives

• Message history. A bot only sees the events sent to it. There’s no endpoint to read history.
• Who the sender really is. No email, IP, profile or real account id. The bot gets the display name and a stand-in id that only works for that bot.
• Files or image URLs. In v1 a bot only learns the message kind (message types).
• Other chats, or messages that don’t call the bot (unless the chat is set to “see every message”).

Personal data

What your bot receives is the personal data of Sukson members. Keep only what you need, delete it when you no longer need it, and never sell or share it, as agreed in the terms you accepted when you created the bot.