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.

Reply and work with threads

parent = await backend.send_message(channel, "Deployment discussion")
reply = await backend.send_message(channel, "All checks passed", reply_to=parent)
thread_reply = await backend.reply_in_thread(parent, "Following up in the thread")

Use chatom.BackendBase.create_thread() for platforms where a thread is a named object and chatom.BackendBase.read_thread() to iterate its messages.

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)