Base Models¶

Chatom provides type-safe models for all chat concepts. These models are platform-agnostic and can be converted to/from backend-specific formats.

User¶

The User model represents a chat platform user.

from chatom import User

# Create a user with various identifiers
user = User(
    id="U123456",
    name="Alice Smith",
    handle="alice.smith",
    email="alice@example.com",
    avatar_url="https://example.com/avatar.png",
)

# Access computed properties
print(user.display_name)  # "Alice Smith"
print(user.mention_name)  # "alice.smith"

User Properties¶

Property	Type	Description
`id`	`str`	Unique identifier
`name`	`str`	Display name
`handle`	`str`	Username/handle
`email`	`str`	Email address
`avatar_url`	`str`	Profile picture URL
`is_bot`	`bool`	Whether user is a bot
`metadata`	`dict`	Platform-specific data

Incomplete Users¶

Users from message events may be incomplete (only have ID):

# User from a message event - only has ID
incomplete_user = User(id="U123456", is_incomplete=True)

# Resolve to get full details
full_user = await backend.resolve_user(incomplete_user)
print(full_user.name)  # Now populated

Channel¶

The Channel model represents a channel, room, or conversation.

from chatom import Channel, ChannelType

# Public channel
channel = Channel(
    id="C123456",
    name="general",
    topic="General discussion",
    channel_type=ChannelType.PUBLIC,
)

# Direct message
dm = Channel(
    id="D789",
    channel_type=ChannelType.DM,
    members=["U123", "U456"],
)

# Group DM
group_dm = Channel(
    id="G789",
    name="Project Team",
    channel_type=ChannelType.GROUP_DM,
    members=["U123", "U456", "U789"],
)

Channel Types¶

Type	Description
`ChannelType.PUBLIC`	Public channel visible to all
`ChannelType.PRIVATE`	Private channel (invite only)
`ChannelType.DM`	Direct message between two users
`ChannelType.GROUP_DM`	Group direct message

Channel Properties¶

Property	Type	Description
`id`	`str`	Unique identifier
`name`	`str`	Channel name
`topic`	`str`	Channel topic/description
`channel_type`	`ChannelType`	Type of channel
`members`	`List[str]`	Member user IDs
`organization_id`	`str`	Parent org/guild ID
`metadata`	`dict`	Platform-specific data

Message¶

The Message model represents a chat message.

from chatom import Message, MessageType, User, Channel
from datetime import datetime

# Create a message
message = Message(
    id="M123456",
    content="Hello, world!",
    author=User(id="U123", name="Alice"),
    channel=Channel(id="C456", name="general"),
    created_at=datetime.now(),
    message_type=MessageType.DEFAULT,
)

# Message with thread
reply = Message(
    id="M789",
    content="Great message!",
    author=User(id="U456", name="Bob"),
    channel_id="C456",
    thread_id="M123456",  # Parent message ID
    reply_to_id="M123456",
)

Message Properties¶

Property	Type	Description
`id`	`str`	Unique identifier
`content`	`str`	Message text content
`author`	`User`	Message author
`author_id`	`str`	Author user ID
`channel`	`Channel`	Channel/room
`channel_id`	`str`	Channel ID
`created_at`	`datetime`	When created
`edited_at`	`datetime`	When last edited
`thread_id`	`str`	Parent thread ID
`reply_to_id`	`str`	Message being replied to
`reactions`	`List[Reaction]`	Emoji reactions
`attachments`	`List[Attachment]`	File attachments
`embeds`	`List[Embed]`	Rich embeds
`metadata`	`dict`	Platform-specific data

Message Types¶

from chatom import MessageType

# Standard message
MessageType.DEFAULT

# System/notification messages
MessageType.SYSTEM

# Join/leave notifications
MessageType.JOIN
MessageType.LEAVE

# Pin notifications
MessageType.PIN

Detecting Mentions¶

# Check who is mentioned in a message
mentioned_user_ids = message.get_mentioned_user_ids()
mentioned_channel_ids = message.get_mentioned_channel_ids()

# Check if specific user is mentioned
if message.mentions_user("U123456"):
    print("User U123456 was mentioned!")

Response Convenience Methods¶

Messages have methods that construct new Message instances for responses:

Method	Description
`as_reply(content)`	Create a reply message
`as_thread_reply(content)`	Create a reply in the same thread
`as_forward(channel)`	Create a forwarded message
`as_quote_reply(content)`	Create a reply that quotes the original
`reply_context()`	Get context dict for custom handling

# Create a reply message
reply = message.as_reply("Thanks!")
print(reply.reply_to is message)  # True
print(reply.message_type)  # MessageType.REPLY

# Create a forward to another channel
forward = message.as_forward(log_channel)
print(forward.forwarded_from is message)  # True

See Messaging for full documentation.

## Reaction

The `Reaction` model represents emoji reactions on messages.

```python
from chatom import Emoji, Reaction

# Create an emoji
emoji = Emoji(
    name="thumbsup",
    unicode="👍",
    custom=False,
)

# Create a reaction
reaction = Reaction(
    emoji=emoji,
    count=5,
    users=["U123", "U456", "U789"],
)

Emoji Properties¶

Property	Type	Description
`name`	`str`	Emoji name (e.g., “thumbsup”)
`unicode`	`str`	Unicode character
`custom`	`bool`	Whether custom emoji
`id`	`str`	Custom emoji ID

Organization¶

The Organization model represents a workspace, guild, or pod.

from chatom import Organization

org = Organization(
    id="T123456",
    name="My Company",
    domain="mycompany.slack.com",
)

Organization Properties¶

Property	Type	Description
`id`	`str`	Unique identifier
`name`	`str`	Organization name
`domain`	`str`	Domain/URL
`icon_url`	`str`	Organization icon
`metadata`	`dict`	Platform-specific data

Attachment¶

The Attachment model represents file attachments.

from chatom import Attachment, AttachmentType

attachment = Attachment(
    id="F123",
    filename="report.pdf",
    url="https://example.com/files/report.pdf",
    attachment_type=AttachmentType.FILE,
    size=1024000,
    mime_type="application/pdf",
)

Attachment Types¶

Type	Description
`AttachmentType.FILE`	Generic file
`AttachmentType.IMAGE`	Image file
`AttachmentType.VIDEO`	Video file
`AttachmentType.AUDIO`	Audio file

Embed¶

The Embed model represents rich embeds (cards, previews).

from chatom import Embed, EmbedField, EmbedAuthor, EmbedFooter

embed = Embed(
    title="News Article",
    description="This is the article summary...",
    url="https://example.com/article",
    color=0x3498db,
    author=EmbedAuthor(name="John Doe"),
    fields=[
        EmbedField(name="Category", value="Technology", inline=True),
        EmbedField(name="Date", value="2024-01-15", inline=True),
    ],
    footer=EmbedFooter(text="Published by Example News"),
)

Model Conversion¶

Convert between base models and backend-specific models:

from chatom.base import promote, demote
from chatom import User

# Create a base user
base_user = User(id="U123", name="Alice")

# Promote to Slack-specific user
from chatom.slack import SlackUser
slack_user = promote(base_user, SlackUser)

# Demote back to base user
base_user_again = demote(slack_user)

Next Steps¶

Backends - Working with chat platforms
Backend Configuration - Platform credentials
Messaging - Sending and receiving messages