Connect and send through a backend¶
Install Chatom and the SDKs for the platforms you use:
pip install chatom
pip install slack-sdk discord.py matrix-nio symphony-bdk-python python-telegram-bot zulip
Create a backend¶
Each adapter accepts its own configuration model:
from chatom.discord import DiscordBackend, DiscordConfig
from chatom.irc import IRCBackend, IRCConfig
from chatom.matrix import MatrixBackend, MatrixConfig
from chatom.slack import SlackBackend, SlackConfig
from chatom.symphony import SymphonyBackend, SymphonyConfig
from chatom.telegram import TelegramBackend, TelegramConfig
from chatom.zulip import ZulipBackend, ZulipConfig
slack = SlackBackend(config=SlackConfig(bot_token="xoxb-..."))
discord = DiscordBackend(config=DiscordConfig(token="..."))
irc = IRCBackend(config=IRCConfig(server="irc.example.org", channels=["#operations"]))
matrix = MatrixBackend(
config=MatrixConfig(
homeserver="https://matrix.example.org",
user_id="@chatom:example.org",
access_token="...",
device_id="CHATOM",
)
)
symphony = SymphonyBackend(
config=SymphonyConfig(
host="company.symphony.com",
bot_username="chatom-bot",
bot_private_key_path="bot-private-key.pem",
)
)
telegram = TelegramBackend(config=TelegramConfig(bot_token="..."))
zulip = ZulipBackend(
config=ZulipConfig(site="https://example.zulipchat.com", email="chatom@example.com", api_key="...")
)
Pass secrets from environment variables or a secret manager in production.
Matrix encrypted rooms¶
MatrixBackend uses matrix-nio and cannot read or post in end-to-end encrypted rooms. MatrixE2EEBackend has the same interface and uses matrix-sdk-python, which wraps matrix-rust-sdk:
from chatom.matrix import MatrixConfig, MatrixE2EEBackend
matrix = MatrixE2EEBackend(
config=MatrixConfig(
homeserver="https://matrix.example.org",
user_id="@chatom:example.org",
password="...",
device_id="CHATOM",
store_path="/var/lib/chatom/matrix",
recovery_key="...",
)
)
store_path holds the device’s encryption keys and the login session, so keep it on persistent storage. The first connect logs in with the password and saves the session there; later connects restore it and keep the same device. Two processes must not share a store.
Clients that exclude insecure devices only share room keys with devices their owner has cross-signed. If the account already has a cross-signing identity, for example from signing in with Element, recovery_key lets a new device restore that identity and sign itself. Matrix presence is not available through this backend.
Symphony emoji reactions¶
Symphony users react to messages with emoji, but no public Agent or Pod REST
endpoint exposes reactions to a bot, so SYMPHONY_CAPABILITIES leaves
EMOJI_REACTIONS out and add_reaction refuses by default.
The web client reacts through an internal service, POST /maestro/reactions/v1/message, which accepts a bot’s session token.
use_internal_reactions opts in to it:
symphony = SymphonyBackend(
config=SymphonyConfig(
host="develop2.symphony.com",
bot_username="my-bot",
bot_private_key_path="/path/to/key.pem",
use_internal_reactions=True,
)
)
await symphony.add_reaction(message=sent, emoji="\N{THUMBS UP SIGN}")
await symphony.remove_reaction(message=sent, emoji="\N{THUMBS UP SIGN}")
That service is not part of Symphony’s published API specification and may
change without notice, which is why the flag defaults to off. An instance with
the flag set declares Capability.EMOJI_REACTIONS so capability-gated callers
see the truth, while the shared module constant stays unchanged.
Symphony itself answers REACTIONS_INVALID_EMOJI for a shortname, so common
shortnames are translated: ":thumbsup:", "thumbsup", and "+1" all become
👍, matching how reactions are named for the other backends. Install the
optional emoji package to cover every shortname; without it a small built-in
set is translated and anything else has to arrive as the character or as an
Emoji carrying unicode.
Use the common lifecycle¶
The rest of the workflow is backend-independent:
async def announce(backend, channel_name: str, content: str):
await backend.connect()
try:
channel = await backend.fetch_channel(name=channel_name)
return await backend.send_message(channel, content)
finally:
await backend.disconnect()
chatom.BackendBase.fetch_channel() accepts an identifier or named keyword. Methods that accept a channel generally accept either a channel ID or a chatom.Channel.
Use the synchronous facade¶
For a synchronous caller, use chatom.BackendBase.sync and close it when finished:
backend.sync.connect()
try:
channel = backend.sync.fetch_channel(name="operations")
backend.sync.send_message(channel, "Deployment complete")
finally:
backend.sync.disconnect()
backend.sync.close()
Check an optional operation¶
from chatom import Capability
if backend.capabilities.supports(Capability.EMOJI_REACTIONS):
await backend.add_reaction(channel, message, "thumbsup")
Consult the backend’s chatom.BackendCapabilities before relying on reactions, presence, editing, files, threads, or interactions.
Read and search messages¶
from datetime import datetime, timedelta, timezone
since = datetime.now(timezone.utc) - timedelta(hours=1)
messages = await backend.fetch_messages(channel, limit=100, after=since)
async for message in backend.read_messages(channel, limit=20):
print(message.author_name, message.content)
if backend.capabilities.supports(Capability.MESSAGE_SEARCH):
matches = await backend.search_messages("deployment", channel=channel)
History is returned newest-first. Bounds accept message IDs, chatom.Message objects, or timezone-aware datetimes.
Edit, delete, and react¶
if backend.capabilities.supports(Capability.EDITING):
message = await backend.edit_message(message, "Corrected content")
if backend.capabilities.supports(Capability.EMOJI_REACTIONS):
await backend.add_reaction(message, "thumbsup")
await backend.remove_reaction(message, "thumbsup")
if backend.capabilities.supports(Capability.DELETING):
await backend.delete_message(message)
Upload and download files¶
uploaded = await backend.upload_file(
channel,
report_bytes,
filename="report.csv",
content_type="text/csv",
content="Latest report",
)
for attachment in incoming_message.attachments:
data = await backend.download_attachment(attachment, message=incoming_message)
Send a direct message¶
user = await backend.fetch_user(email="alice@example.com")
message = await backend.send_dm(user, "The report is ready")
Listen for events¶
async for message in backend.listen(channel=channel):
if message.content == "ping":
await backend.reply_in_thread(message, "pong")
Use chatom.BackendBase.stream_interactions() for button, menu, and modal events. Streaming support depends on the selected backend and its connection mode.
Manage presence¶
if backend.capabilities.supports(Capability.PRESENCE):
await backend.set_presence("online", "Ready")
presence = await backend.get_presence(user)