Chats

The bot’s chats

GET /v1/me/chats

curl -s https://api.sukson.dev/v1/me/chats -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{
  "chats": [
    {
      "chat_id": "0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10",
      "kind": "group",
      "title": "Hiking club",
      "visibility": "mentions",
      "status": "active"
    },
    {
      "chat_id": "7d2e9f10-3c4b-4a5d-8e6f-1a2b3c4d5e6f",
      "kind": "room",
      "title": "Football talk",
      "visibility": "all",
      "status": "paused"
    }
  ]
}

Field	Description
chat_id	The chat’s id, same as chat.id in events; use it in POST /v1/chats/{chat_id}/messages
kind	room (public room), group or channel
title	The chat’s name; may be null
visibility	mentions (only messages that call the bot) or all (every message), set by the chat owner
status	active or paused (the owner paused the bot in this chat only)

A bot receives events and can post only where status is active. Pausing the bot in one chat doesn’t affect the others. A bot banned from a chat is out of it at once (it gets a leave event), and that chat isn’t listed any more.

A chat’s details

GET /v1/chats/{chat_id}

A chat the bot is in, with the bot’s settings and rights there. Chats where the bot is paused answer too. A chat the bot was banned from answers 404 NOT_FOUND, because the bot is out of it (it got a leave event).

curl -s https://api.sukson.dev/v1/chats/0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10 -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{
  "chat_id": "0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10",
  "kind": "group",
  "title": "Hiking club",
  "member_count": 42,
  "bot": {
    "visibility": "mentions",
    "allow_visitors": false,
    "status": "active",
    "rights": { "delete_messages": true, "kick": false, "ban": false }
  }
}

Field	Description
member_count	How many members the chat has
bot.visibility	mentions or all, as in GET /v1/me/chats
bot.allow_visitors	true when the chat owner lets the bot get messages from visitors who aren’t signed in (public rooms only)
bot.status	active or paused
bot.rights	The moderation rights the chat owner gave the bot (moderation)

A chat the bot isn’t in, a chat that doesn’t exist or a malformed chat_id gets 404 NOT_FOUND. If whoever added the bot lost that right (demoted or gone), you get 403 FORBIDDEN with reason attacher_lost_rights.

Members

GET /v1/chats/{chat_id}/members

Query	Rules
limit	Optional, 1–100, default 50
cursor	Optional, the next_cursor of the previous page

curl -s "https://api.sukson.dev/v1/chats/0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10/members?limit=50" \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{
  "members": [
    { "user_id": "4a7c1e9b2d3f40c58e6a7b8c9d0e1f2a", "name": "Somying", "avatar_url": "https://…/avatar.jpg", "role": "owner", "is_bot": false },
    { "user_id": "b1c2d3e4f5a60718293a4b5c6d7e8f90", "name": "WeatherBot", "avatar_url": null, "role": "member", "is_bot": true },
    { "user_id": "9f2c4e7a1b3d5f60718293a4b5c6d7e8", "name": "Somchai", "avatar_url": null, "role": "member", "is_bot": false }
  ],
  "next_cursor": "1834"
}

Field	Description
user_id	The person’s id for this bot, the same value as sender.id in events (member ids)
name	Display name. A closed account shows a label instead of a name.
avatar_url	Profile picture URL, or null
role	owner, admin or member. Bots are always member.
is_bot	true for bots
next_cursor	Send it as cursor for the next page; null when there are no more pages

• The first page starts with the owner and admins, then the bots in the chat, then everyone else in the order they joined. Later pages hold only everyone else.
• limit counts only everyone else. The owner, admins and every bot are always on the first page on top of it, so a chat with many admins or bots returns a first page longer than limit.
• Accounts only. Visitors who aren’t signed in are never listed.
• In a channel you see only the owner, admins and bots, not the subscribers, just as subscribers see each other.
• No email, IP, profile link or real account id. An account with no name at all shows as สมาชิก (member).

HTTP	code	When
404	NOT_FOUND	The bot isn’t in this chat, or there’s no such chat
403	FORBIDDEN	details.reason is attacher_lost_rights: whoever added the bot is no longer the owner or an admin who can edit the chat (demoted or gone)
403	CHAT_INACTIVE	The chat is closed
422	INVALID	Bad limit or cursor, or any query parameter sent twice
422	UNKNOWN_FIELD	A query parameter other than limit or cursor (for example ?page=2); its name is in details.fields

One member

GET /v1/chats/{chat_id}/members/{user_id}

One member, in the same shape as an entry of members. Use it to check whether whoever sent a message is the chat’s owner or an admin.

{ "user_id": "9f2c4e7a1b3d5f60718293a4b5c6d7e8", "name": "Somchai", "avatar_url": null, "role": "member", "is_bot": false }

You get 404 NOT_FOUND when the user_id is unknown, the person left the chat, is a visitor, or is a channel subscriber, and 403 FORBIDDEN reason attacher_lost_rights or 403 CHAT_INACTIVE as for the member list.

Leave a chat

DELETE /v1/me/chats/{chat_id}

The bot leaves the chat on its own, just as if its owner took it out. No body.

curl -s -X DELETE https://api.sukson.dev/v1/me/chats/0b6c3a52-5d0e-4c8e-9a51-6f1e7f6f2b10 \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN"

{ "left": true }

• The bot gets one leave event for that chat.
• To come back, the chat’s owner or an admin has to add the bot again in the app or website, and earlier moderation rights don’t carry over.
• A chat the bot isn’t in gets 404 NOT_FOUND.

Member ids

A bot never sees anyone’s real account id. Every person has an id (32 lowercase hex characters) that only your bot uses.

• The same person always has the same id, in every chat your bot is in, and it doesn’t change when you set a new webhook URL.
• Two bots see the same person under different ids, so ids can’t be matched across bots.
• One id everywhere: sender.id and user.id in events, user_id in member lists and in moderation.
• Use ids exactly as you got them, in lowercase. An upper-cased id won’t work.
• Visitors in public rooms have their own id too (in sender.id), but aren’t in member lists.

Adding the bot to a chat

In v1, bots are added to chats in the Sukson app or website only (on the chat’s info page, by its owner or an admin). How many chats a bot can be in at once is the entitlements.attachments_max of its plan. When the bot is added, it gets a join event.