# Shared

## Domain Types

### Attachment

- `class Attachment: …`

  - `type: Literal["unknown", "img", "video", "audio"]`

    Attachment type.

    - `"unknown"`

    - `"img"`

    - `"video"`

    - `"audio"`

  - `id: Optional[str]`

    Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path.

  - `duration: Optional[float]`

    Duration in seconds (audio/video).

  - `file_name: Optional[str]`

    Original filename if available.

  - `file_size: Optional[float]`

    File size in bytes if known.

  - `is_gif: Optional[bool]`

    True if the attachment is a GIF.

  - `is_sticker: Optional[bool]`

    True if the attachment is a sticker.

  - `is_voice_note: Optional[bool]`

    True if the attachment is a voice note.

  - `mime_type: Optional[str]`

    MIME type if known (e.g., 'image/png').

  - `poster_img: Optional[str]`

    Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed.

  - `size: Optional[Size]`

    Pixel dimensions of the attachment: width/height in px.

    - `height: Optional[float]`

    - `width: Optional[float]`

  - `src_url: Optional[str]`

    Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed.

### Error

- `class Error: …`

  - `code: str`

    Machine-readable error code

  - `message: str`

    Error message

  - `details: Optional[Details]`

    Additional error details for debugging

    - `class DetailsValidationDetails: …`

      Validation error details

      - `issues: List[DetailsValidationDetailsIssue]`

        List of validation issues

        - `code: str`

          Validation issue code

        - `message: str`

          Human-readable description of the validation issue

        - `path: List[Union[str, float]]`

          Path pointing to the invalid field within the payload

          - `str`

          - `float`

    - `Dict[str, Optional[object]]`

      Additional error context

    - `Optional[object]`

      Arbitrary details payload supplied by the server

### Message

- `class Message: …`

  - `id: str`

    Message ID.

  - `account_id: str`

    Beeper account ID the message belongs to.

  - `chat_id: str`

    Unique identifier of the chat.

  - `sender_id: str`

    Sender user ID.

  - `sort_key: str`

    A unique, sortable key used to sort messages.

  - `timestamp: datetime`

    Message timestamp.

  - `attachments: Optional[List[Attachment]]`

    Attachments included with this message, if any.

    - `type: Literal["unknown", "img", "video", "audio"]`

      Attachment type.

      - `"unknown"`

      - `"img"`

      - `"video"`

      - `"audio"`

    - `id: Optional[str]`

      Attachment identifier (typically an mxc:// URL). Use with /v1/assets/download to get a local file path.

    - `duration: Optional[float]`

      Duration in seconds (audio/video).

    - `file_name: Optional[str]`

      Original filename if available.

    - `file_size: Optional[float]`

      File size in bytes if known.

    - `is_gif: Optional[bool]`

      True if the attachment is a GIF.

    - `is_sticker: Optional[bool]`

      True if the attachment is a sticker.

    - `is_voice_note: Optional[bool]`

      True if the attachment is a voice note.

    - `mime_type: Optional[str]`

      MIME type if known (e.g., 'image/png').

    - `poster_img: Optional[str]`

      Preview image URL for video attachments (poster frame). May be temporary or local-only to this device; download promptly if durable access is needed.

    - `size: Optional[Size]`

      Pixel dimensions of the attachment: width/height in px.

      - `height: Optional[float]`

      - `width: Optional[float]`

    - `src_url: Optional[str]`

      Public URL or local file path to fetch the asset. May be temporary or local-only to this device; download promptly if durable access is needed.

  - `is_sender: Optional[bool]`

    True if the authenticated user sent the message.

  - `is_unread: Optional[bool]`

    True if the message is unread for the authenticated user. May be omitted.

  - `linked_message_id: Optional[str]`

    ID of the message this is a reply to, if any.

  - `reactions: Optional[List[Reaction]]`

    Reactions to the message, if any.

    - `id: str`

      Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

    - `participant_id: str`

      User ID of the participant who reacted.

    - `reaction_key: str`

      The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face".

    - `emoji: Optional[bool]`

      True if the reactionKey is an emoji.

    - `img_url: Optional[str]`

      URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed.

  - `sender_name: Optional[str]`

    Resolved sender display name (impersonator/full name/username/participant name).

  - `text: Optional[str]`

    Plain-text body if present. May include a JSON fallback with text entities for rich messages.

  - `type: Optional[Literal["TEXT", "NOTICE", "IMAGE", 7 more]]`

    Message content type. Useful for distinguishing reactions, media messages, and state events from regular text messages.

    - `"TEXT"`

    - `"NOTICE"`

    - `"IMAGE"`

    - `"VIDEO"`

    - `"VOICE"`

    - `"AUDIO"`

    - `"FILE"`

    - `"STICKER"`

    - `"LOCATION"`

    - `"REACTION"`

### Reaction

- `class Reaction: …`

  - `id: str`

    Reaction ID, typically ${participantID}${reactionKey} if multiple reactions allowed, or just participantID otherwise.

  - `participant_id: str`

    User ID of the participant who reacted.

  - `reaction_key: str`

    The reaction key: an emoji (😄), a network-specific key, or a shortcode like "smiling-face".

  - `emoji: Optional[bool]`

    True if the reactionKey is an emoji.

  - `img_url: Optional[str]`

    URL to the reaction's image. May be temporary or local-only to this device; download promptly if durable access is needed.

### User

- `class User: …`

  User the account belongs to.

  - `id: str`

    Stable Beeper user ID. Use as the primary key when referencing a person.

  - `cannot_message: Optional[bool]`

    True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

  - `email: Optional[str]`

    Email address if known. Not guaranteed verified.

  - `full_name: Optional[str]`

    Display name as shown in clients (e.g., 'Alice Example'). May include emojis.

  - `img_url: Optional[str]`

    Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.

  - `is_self: Optional[bool]`

    True if this user represents the authenticated account's own identity.

  - `phone_number: Optional[str]`

    User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown.

  - `username: Optional[str]`

    Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique.