Messaging & Social

This page covers the built-in tools that read and send email, post into team chats, send SMS and WhatsApp messages, work with X and Reddit, and manage Zoom meetings. Use it to pick a tool, configure its credentials, and understand why a tool is unavailable or a send failed.

Choosing a Tool

For Amazon SES email, see aws_ses in Automation & Platforms.

Credentials

Set fields of type password through the dashboard or credential store; see Security Restrictions. Many credential fields below are optional in the dashboard but required in practice, and the tool fails to load or errors on its first call without them. Instead of stored fields, these tools also read the environment variables SLACK_TOKEN, SLACK_USER_TOKEN, DISCORD_BOT_TOKEN, TELEGRAM_TOKEN, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_API_KEY, TWILIO_API_SECRET, WEBEX_ACCESS_TOKEN, RESEND_API_KEY, X_BEARER_TOKEN, X_CONSUMER_KEY, X_CONSUMER_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_USERNAME, REDDIT_PASSWORD, ZOOM_ACCOUNT_ID, ZOOM_CLIENT_ID, and ZOOM_CLIENT_SECRET. gmail instead connects through Google OAuth; see Google Services OAuth For Local Installs or Google Services OAuth for custom and hosted setups. Most tools enable or disable individual functions with enable_<function> flags, and all: true enables every function; include_tools and exclude_tools filter further, as described in Filtering Toolkit Functions.

[gmail]

gmail reads, searches, drafts, sends, replies to, stars, and labels mail in the connected Gmail account. Connect the account through the google_gmail OAuth provider; when no usable connection exists, the tool replies with a link to connect. To use a Google Workspace service account instead, set GOOGLE_SERVICE_ACCOUNT_FILE to the key file path and GOOGLE_DELEGATED_USER to the mailbox to impersonate through domain-wide delegation. gmail always runs in the primary MindRoom runtime, even for agents whose other tools run in a worker, so workers never receive Google credentials.

Its functions are apply_label(), create_draft_email(), delete_custom_label(), get_draft(), get_emails_by_context(), get_emails_by_date(), get_emails_by_thread(), get_emails_from_user(), get_latest_emails(), get_message(), get_starred_emails(), get_thread(), get_unread_emails(), list_custom_labels(), list_drafts(), mark_email_as_read(), mark_email_as_unread(), remove_label(), search_emails(), search_threads(), send_email(), send_email_reply(), send_email_to_self(), star_email(), unstar_email(), and update_draft(). Archiving, trashing, attachment downloads, and sending existing drafts are not available. send_email_to_self(subject, body) always sends to the connected account's own address, so an approval rule can allow it while still requiring approval for send_email; see Tool Approval.

Draft and send functions accept attachment file paths, not Matrix attachment IDs. Allowed paths follow the agent's file_access setting: with the default workspace, attachments must be files inside the agent workspace, and an agent without a workspace cannot attach files. With unrestricted, any file MindRoom can read is allowed. Relative paths resolve from the workspace root, or from the MindRoom working directory when an unrestricted agent has no workspace. Attachments may total at most 25 MiB per message; larger sets fail with Gmail attachments exceed the 25 MiB limit.

Each option below defaults to true, and setting it to false removes the matching function.

Use exclude_tools to remove other functions, such as delete_custom_label.

[slack]

slack sends messages and threaded replies, lists channels and users, reads channel history and threads, searches messages, and uploads or downloads files. Use channel IDs rather than names, especially for threaded replies and history reads. get_channel_history() returns only top-level messages; to read a thread's replies, enable get_thread() and pass the parent message's timestamp. slack always runs in the primary runtime, and its file uploads and downloads are not confined by the agent's file_access, so enable it only for agents trusted with what the MindRoom process can reach; see File access.

To search messages, set enable_search_messages: true and store a user token with the search:read scope in user_token; a bot token alone cannot search. A user token stored as the primary token also works for search. search_workspace() works only when Slack itself invokes the agent and supplies an action token, so it fails in ordinary Matrix conversations; use search_messages() there.

agents:
  support:
    tools:
      - slack:
          enable_get_thread: true
          enable_search_messages: true

[discord]

discord sends messages, reads channel messages and info, lists a server's channels, and deletes messages through the Discord REST API with a bot token. It does not run a live Discord bot, so it cannot receive messages, handle slash commands, or set presence. Functions take Discord IDs such as channel, server, and message IDs, not names. Deletion is enabled by default; set enable_delete_message: false for read and send access only.

[telegram]

telegram sends messages from a Telegram bot to the one chat or channel set in chat_id or TELEGRAM_CHAT_ID, so calls never choose a destination. For several Telegram destinations, configure the tool separately per agent or credential scope. Only send_message() is enabled by default. Optional functions send photos, documents, video, audio, animations, and stickers, edit, delete, and pin messages, react with emoji, read chat details with get_chat(), and download files with get_file(). get_file() returns file content unless save_downloads or output_directory is set, in which case it saves the file and returns its path.

agents:
  notifier:
    tools:
      - telegram:
          chat_id: "-1001234567890"
          enable_send_document: true

[whatsapp]

whatsapp sends messages through the WhatsApp Business (Meta Graph) API. Text and template messages are enabled by default; reply buttons, list messages, images, documents, locations, and reactions are opt-in. Template sends need a template name approved in WhatsApp Business. Set recipient_waid or WHATSAPP_RECIPIENT_WAID to give calls a default recipient; otherwise, every call must name one.

agents:
  pager:
    tools:
      - whatsapp:
          recipient_waid: "+15551234567"
          enable_send_reply_buttons: true

[twilio]

twilio sends SMS with send_sms(), looks up calls with get_call_details(), and lists recent messages with list_messages(). Authenticate with account_sid plus either auth_token or the api_key and api_secret pair. send_sms() rejects sender and recipient numbers that are not in E.164 format, such as +15551234567, and the sender must be a number on the Twilio account.

[webex]

webex sends messages to Webex rooms with send_message() and lists rooms with list_rooms(). It does not manage meetings. Send to room IDs, not room titles.

[resend]

resend sends transactional email through Resend with send_email(), using the message body as HTML. Every message comes from from_email, which usually must be a sender verified in Resend. Use gmail instead when the agent needs to read or reply within a mailbox.

[email]

email sends plain-text mail with email_user(subject, body) to the single address in receiver_email; calls cannot choose another recipient. It always signs in to Gmail SMTP (smtp.gmail.com:465), so the sender must be a Gmail or Google Workspace account, usually with an app password, and other SMTP servers cannot be configured. All four fields are required; a missing one makes the call return an error such as error: No receiver email provided. Use gmail for mailbox access or resend for HTML transactional mail.

agents:
  alerts:
    tools:
      - email:
          receiver_email: oncall@example.com
          sender_name: MindRoom Alerts
          sender_email: alerts@gmail.com

[x]

x creates posts, replies to posts, sends DMs, looks up users, reads the home timeline, and searches recent posts. A bearer token is enough for search and lookups, but posting, replying, DMs, and the home timeline generally need the four OAuth user credentials. search_posts() accepts a result limit of 10 to 100, and may return fewer matches.

[reddit]

reddit reads user profiles, top posts, subreddit info and stats, and trending subreddits, and can create posts and reply to posts and comments. client_id and client_secret are enough for reads; posting and replying also need username and password. A nonempty allowed_subreddits list limits posts and replies to those subreddits, named without r/ and matched case-insensitively; reads are unaffected.

agents:
  community:
    tools:
      - reddit:
          user_agent: MindRoomCommunityBot/1.0
          allowed_subreddits: [matrixdotorg]

[zoom]

zoom schedules, lists, inspects, and deletes Zoom meetings and reads meeting recordings. It uses the credentials of a Zoom Server-to-Server OAuth app, so there is no browser connect step. Meetings are scheduled for the app account's own user with fixed settings: automatic recording is off, and participants cannot join before the host.

Related Docs

• Tools Overview
• Automation & Platforms - aws_ses for Amazon SES email.