This page contains documentation for the ChatUser class and its subclasses:
ChatUser
Overview
Synology Chat API via DSM session (username + password).
Wraps the SYNO.Chat.* APIs discovered on DSM 7.3.2+. 25 of 39 registered APIs confirmed working; see module docstring for details.
For token-based access (no DSM login), use :class:ChatBot.
Methods
channel_list
List all chat channels.
Internal API
SYNO.Chat.Channel
Parameters
simple bool
If True, return {channel_id: channel_name}
instead of the full JSON response.
Returns
dict[str, object] or str or dict[int, str]
Full API response, or {channel_id: name} dict
when simple=True.
channel_create
Create a new named chat channel and auto-join it.
Internal API
SYNO.Chat.Channel.Named
Parameters
name str
Channel name.
members list[str]
User IDs to invite after creation.
Returns
dict[str, object] or str
Created channel with channel_id and auto_join flag.
channel_close
Close (delete) a chat channel.
Internal API
SYNO.Chat.Channel
Parameters
channel_id int
Numeric channel ID to close.
Returns
dict[str, object] or str
API response.
channel_archive
Archive a chat channel.
Internal API
SYNO.Chat.Channel
Parameters
channel_id int
Numeric channel ID to archive.
Returns
dict[str, object] or str
API response.
channel_invite
Invite users to a named channel.
Internal API
SYNO.Chat.Channel.Named
Parameters
channel_id int
Numeric channel ID.
user_ids list[int]
List of user IDs to invite.
Returns
dict[str, object] or str
API response.
channel_join
Join a channel (must be public or the user must be invited).
Internal API
SYNO.Chat.Channel.Named
Parameters
channel_id int
Numeric channel ID to join.
Returns
dict[str, object] or str
API response.
channel_leave
Leave a channel.
.. warning::
If you are the only member, the channel becomes orphaned
(no one can rejoin or close it via API). Only leave channels
that have other members.
Internal API
SYNO.Chat.Channel.Named
Parameters
channel_id int
Numeric channel ID to leave.
Returns
dict[str, object] or str
API response.
channel_view
Mark a channel as read up to a given timestamp.
Internal API
SYNO.Chat.Channel
Parameters
channel_id int
Channel ID.
last_view_at int
Unix timestamp in milliseconds marking the last read
point. Defaults to current time.
Returns
dict[str, object] or str
API response.
channel_preference_get
Get channel preferences (notifications, etc.).
Internal API
SYNO.Chat.Channel.Preference
Parameters
channel_id int
Channel ID.
Returns
dict[str, object] or str
API response.
user_list
List all chat users.
Internal API
SYNO.Chat.User
Returns
dict[str, object] or str
API response.
user_get
Get user details.
Internal API
SYNO.Chat.User
Parameters
user_id str
User ID.
Returns
dict[str, object] or str
API response.
user_status_get
Get user online status.
Internal API
SYNO.Chat.User.Status
Parameters
user_id str
User ID.
Returns
dict[str, object] or str
API response.
user_avatar_get
Get user avatar.
Internal API
SYNO.Chat.User.Avatar
Parameters
user_id str
User ID.
Returns
dict[str, object] or str
API response.
user_preference_get
Get current user's Chat preferences.
Internal API
SYNO.Chat.User.Preference
Returns
dict[str, object] or str
API response.
incoming_webhook_list
List all incoming webhooks.
Internal API
SYNO.Chat.Webhook.Incoming
Returns
dict[str, object] or str
API response.
incoming_webhook_create
Create an incoming webhook to post messages into a channel.
Provides a token and webhook user_id. The webhook URL to POST
messages to must be constructed as::
https://{host}:{port}/webapi/entry.cgi?api=SYNO.Chat.Webhook.Incoming&version=1&method=incoming&token=***
with payload={"text": "..."} as form-encoded POST body.
For direct posting without webhooks, prefer :meth:post_create.
Internal API
SYNO.Chat.Webhook.Incoming
Parameters
name str
Webhook name.
channel_id str
Target channel ID.
icon_url str
URL for the webhook icon.
Returns
dict[str, object] or str
Created webhook with token and user_id.
incoming_webhook_delete
Delete an incoming webhook.
Internal API
SYNO.Chat.Webhook.Incoming
Parameters
webhook_id str
Webhook ID to delete.
Returns
dict[str, object] or str
API response.
outgoing_webhook_list
List all outgoing webhooks.
Internal API
SYNO.Chat.Webhook.Outgoing
Returns
dict[str, object] or str
API response.
outgoing_webhook_create
Create an outgoing webhook (Chat POSTs events to your URL).
Internal API
SYNO.Chat.Webhook.Outgoing
Parameters
name str
Webhook name.
channel_id str
Channel ID.
url str
Target URL for events.
events list[str]
Event types (default ["message"]).
Returns
dict[str, object] or str
API response.
outgoing_webhook_delete
Delete an outgoing webhook.
Internal API
SYNO.Chat.Webhook.Outgoing
Parameters
webhook_id str
Webhook ID to delete.
Returns
dict[str, object] or str
API response.
slash_command_list
List all slash commands.
Internal API
SYNO.Chat.Webhook.Slash
Returns
dict[str, object] or str
API response.
slash_command_create
Create a slash command (/deploy, /alert, etc.).
Internal API
SYNO.Chat.Webhook.Slash
Parameters
name str
Command display name.
command str
Command text (e.g. "deploy").
url str
Webhook URL to POST to.
channel_id str
Channel ID to restrict command to.
Returns
dict[str, object] or str
API response.
slash_command_delete
Delete a slash command.
Internal API
SYNO.Chat.Webhook.Slash
Parameters
command_id str
Command ID to delete.
Returns
dict[str, object] or str
API response.
builtin_webhook_list
List built-in webhook integrations (e.g., GitHub, Jira).
Internal API
SYNO.Chat.Webhook.BuiltIn
Returns
dict[str, object] or str
API response.
broadcast_webhook_list
List broadcast webhooks.
Internal API
SYNO.Chat.Webhook.Broadcast
Returns
dict[str, object] or str
API response.
bot_set
Add/update a bot in the chat user list.
The user_id comes from a webhook or chatbot integration.
Call this after creating an incoming webhook or chatbot to
make the bot visible to users.
Internal API
SYNO.Chat.Bot
Parameters
user_id int
Bot user ID (from webhook/chatbot create response).
nickname str
Display name for the bot in chat.
Returns
dict[str, object] or str
API response.
bot_delete
Remove a bot from the chat user list.
Internal API
SYNO.Chat.Bot
Parameters
user_id int
Bot user ID to remove.
Returns
dict[str, object] or str
API response.
external_list
List all external integrations (combined view).
Internal API
SYNO.Chat.External
Returns
dict[str, object] or str
API response.
post_list
List posts in a channel.
Internal API
SYNO.Chat.Post
Parameters
channel_id int
Channel ID.
limit int
Max posts per page (default 50).
offset int
Pagination offset (default 0).
Returns
dict[str, object] or str
API response.
post_search
Search posts across one or more channels.
Powerful search with filters for post type, attachments (pin/url/star),
author, time range, and sorting.
Internal API
SYNO.Chat.Post
Parameters
channel_ids list[int]
Channel IDs to search in (e.g. [72] or [72, 73]).
keyword str
Free-text search in message body.
post_type list[str]
Filter by post type: ["file"], ["normal"], or both
["file", "normal"].
has list[str]
Filter by attachment type. Valid values:
"pin" (pinned), "url" (contains link), "star"
(starred). :::note
"file"/"mention" are silently ignored
:::
by the API.
creator_ids list[int]
Filter by message author user IDs.
after int
Only posts created after this Unix timestamp (ms).
before int
Only posts created before this Unix timestamp (ms).
sort_by str
Sort field: "create_at", "update_at",
"last_pin_at", or "last_comment_at".
Default: "create_at".
sort_by_array list[str]
Multi-field sort (e.g. ["is_sticky", "last_pin_at"]).
Overrides sort_by when provided.
thread_id int
Filter by thread ID. 0 = root posts only (no replies).
offset int
Pagination offset. Default: 0.
limit int
Max results per page. Default: 50.
Returns
dict[str, object] or str
{"data": {"search_results": [...], "total": N, "offset": 0, "limit": 50}, "success": True}.
post_create
Post a message to a channel (direct API, no webhook needed).
Internal API
SYNO.Chat.Post
Parameters
channel_id str
Target channel ID.
message str
Message text. Supports newlines.
file_id str
File ID from :meth:post_file_upload.
Returns
dict[str, object] or str
Created post with 'post_id' key.
post_attachment_list
List post attachments.
Internal API
SYNO.Chat.Post.Attachment
Parameters
channel_id int
Channel ID.
limit int
Max results (default 50).
Returns
dict[str, object] or str
API response.
post_file_upload
Upload a file to a chat channel.
Sends a multipart/form-data POST to SYNO.Chat.Post
(method=create, version=5).
Internal API
SYNO.Chat.Post
Parameters
channel_id str
Target channel ID.
file_path str
Local path to the file to upload.
Returns
dict[str, object] or str
Success response with file_props including file name and size.
post_reaction_add
Add a reaction (sticker) to a post.
Internal API
SYNO.Chat.Post.Reaction
Parameters
post_id str
Target post ID.
sticker_name str
Sticker name, e.g. "grinning", "heart", "thumbsup".
See Synology Chat sticker picker for available names.
Returns
dict[str, object] or str
API response.
post_pin
Pin a post to the top of the channel.
Pinned posts are visible via :meth:post_search with
has=["pin"].
Internal API
SYNO.Chat.Post
Parameters
post_id str
Target post ID.
Returns
dict[str, object] or str
API response.
post_unpin
Unpin a previously pinned post.
Internal API
SYNO.Chat.Post
Parameters
post_id str
Target post ID.
Returns
dict[str, object] or str
API response.
post_thread_list
List threads (posts with replies) in a channel.
Returns root posts that have replies, along with the reply
posts themselves.
Internal API
SYNO.Chat.Post
Parameters
channel_id int
Channel ID to list threads from.
offset int
Pagination offset. Default: 0.
limit int
Max threads per page. Default: 25.
related_comment_count int
Number of reply posts to include per thread. Default: 3.
Returns
dict[str, object] or str
{"data": {"search_results": [...], "related_posts": [...], "total": N}, "success": True}.
search_results contains root posts (thread_id == own
post_id). related_posts contains replies.
post_reminder_list
List post reminders in a channel.
Internal API
SYNO.Chat.Post.Reminder
Parameters
channel_id int
Channel ID.
Returns
dict[str, object] or str
{"data": {"posts": [...]}, "success": True}.
post_reminder_delete
Delete a post reminder.
Internal API
SYNO.Chat.Post.Reminder
Parameters
channel_id int
Channel ID.
post_id str
Post ID whose reminder should be deleted.
Returns
dict[str, object] or str
API response.
post_reminder_get
Get the reminder set on a post.
Internal API
SYNO.Chat.Post.Reminder
Parameters
post_id str
Post ID.
Returns
dict[str, object] or str
{"data": {"remind_at": 0}, "success": True} —
remind_at is 0 if no reminder is set, otherwise a Unix
timestamp in milliseconds.
post_reminder_set
Set or update a reminder on a post.
Internal API
SYNO.Chat.Post.Reminder
Parameters
post_id str
Post ID.
remind_at int
Unix timestamp in milliseconds when to trigger the
reminder.
Returns
dict[str, object] or str
API response.
post_schedule_list
List scheduled (delayed) posts in a channel.
Internal API
SYNO.Chat.Post.Schedule
Parameters
channel_id int
Channel ID.
Returns
dict[str, object] or str
{"data": {"schedule_posts": [{"cronjob_id": N, "message": "...", "send_at": ms_ts}]}, "success": True}.
post_schedule_create
Schedule a post to be sent at a future time.
Internal API
SYNO.Chat.Post.Schedule
Parameters
channel_id int
Target channel ID.
message str
Message text.
send_at int
Unix timestamp in milliseconds when the message
should be sent.
Returns
dict[str, object] or str
Response with cronjob_id.
post_schedule_delete
Delete a scheduled post before it's sent.
Internal API
SYNO.Chat.Post.Schedule
Parameters
cronjob_id int
Cron job ID (from :meth:post_schedule_list).
Returns
dict[str, object] or str
API response.
chatbot_list
List chatbots.
Internal API
SYNO.Chat.Chatbot
Returns
dict[str, object] or str
API response.
chatbot_set
Create/update a chatbot integration.
Requires a user_id from an incoming webhook.
The chatbot will receive messages and can respond via the URL.
.. note::
This API requires admin privileges. Error 117 (permission
denied) or 105 (missing parameter) may occur if the user
lacks permission or the user_id is not a valid chatbot.
Internal API
SYNO.Chat.Chatbot
Parameters
user_id int
Bot user ID (from incoming webhook create).
url str
Webhook URL the chatbot posts events to.
purpose str
Short description shown in the integration page.
welcome_note str
Welcome message shown when a user opens the bot chat.
hide_from_user bool
If True, bot is hidden from the "Add" list (default True).
Returns
dict[str, object] or str
API response.
sticker_list
List available stickers.
Internal API
SYNO.Chat.Sticker
Returns
dict[str, object] or str
API response.
admin_setting_get
Get Chat Server admin settings.
Internal API
SYNO.Chat.Admin.Setting
Returns
dict[str, object] or str
API response.
app_info
Get Chat app information.
Internal API
SYNO.Chat.App
Returns
dict[str, object] or str
API response.
misc_info
Get miscellaneous Chat info.
Internal API
SYNO.Chat.Misc
Returns
dict[str, object] or str
API response.
build_webhook_url
Build the incoming webhook URL from a UI-created token.
Use a token from the Chat UI Integration → Incoming Webhook page
(64 characters). API-created webhook tokens will NOT work —
only UI-created ones are valid for SYNO.Chat.External.
Parameters
token str
The 64-char webhook token from Chat UI.
Returns
str
https://{ip}:{port}/webapi/entry.cgi?api=SYNO.Chat.External&version=2&method=incoming&token=***.
send_webhook
Send a message via incoming webhook token (UI-created).
No DSM session required — just the webhook token and NAS URL.
Parameters
token str
64-char webhook token from Chat UI Integration page.
text str
Message text. Supports \n and <url|link> syntax.
nas_url str
Base NAS URL, e.g. https://your-nas.local:5001.
verify bool
Verify SSL certificate.
Returns
dict
{"success": True} or {"success": False, "error": ...}.
ChatBot
Overview
Synology Chat bot/webhook API — no DSM session required.
Works with tokens created in the Chat UI Integration page. Supports two token types:
- Incoming Webhook token — send messages to a channel via
:meth:
send_incoming. - Bot token — list channels/users/messages, send DMs via
:meth:
send_message.
Parameters
nas_url str
Base URL of the NAS, e.g. https://your-nas.local:5001.
token str
64-character token from Chat UI Integration page.
cert_verify bool
Verify SSL certificate (default False).
Methods
channel_list
List channels visible to the bot.
Requires a bot token. Webhook tokens return code 404.
Returns
dict[str, Any]
API response.
user_list
List users visible to the bot.
Requires a bot token. Webhook tokens return code 404.
Returns
dict[str, Any]
API response.
post_list
List messages in a channel.
Requires a bot token and the bot must be a member of
the channel (otherwise error 401).
Parameters
channel_id str
Channel ID.
post_id str
Anchor post — omit for newest.
next_count int
Messages after anchor.
prev_count int
Messages before anchor.
Returns
dict[str, Any]
API response.
post_file_get
Download file attachment for a post (bot token).
Parameters
post_id str
Post ID with file attachment.
Returns
dict[str, Any]
API response.
send_incoming
Send a message to a channel via incoming webhook token.
Parameters
text str
Message text. Supports \n and <url|link> syntax.
file_url str
Publicly accessible file URL to attach (max 32 MB).
Returns
dict[str, Any]
API response.
send_message
Send a DM to specific users via bot token.
Parameters
text str
Message text.
user_ids list[int]
Target user IDs (e.g. [2] for user 2).
Returns
dict[str, Any]
API response.