# Shared

## Domain Types

### Attachment

- `Attachment`

  - `Type type`

    Attachment type.

  - `?string id`

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

  - `?float duration`

    Duration in seconds (audio/video).

  - `?string fileName`

    Original filename if available.

  - `?float fileSize`

    File size in bytes if known.

  - `?bool isGif`

    True if the attachment is a GIF.

  - `?bool isSticker`

    True if the attachment is a sticker.

  - `?bool isVoiceNote`

    True if the attachment is a voice note.

  - `?string mimeType`

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

  - `?string posterImg`

    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 size`

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

  - `?string srcURL`

    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

- `Error`

  - `string code`

    Machine-readable error code

  - `string message`

    Error message

  - `?Details details`

    Additional error details for debugging

### Message

- `Message`

  - `string id`

    Message ID.

  - `string accountID`

    Beeper account ID the message belongs to.

  - `string chatID`

    Unique identifier of the chat.

  - `string senderID`

    Sender user ID.

  - `string sortKey`

    A unique, sortable key used to sort messages.

  - `\Datetime timestamp`

    Message timestamp.

  - `?list<Attachment> attachments`

    Attachments included with this message, if any.

  - `?bool isSender`

    True if the authenticated user sent the message.

  - `?bool isUnread`

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

  - `?string linkedMessageID`

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

  - `?list<Reaction> reactions`

    Reactions to the message, if any.

  - `?string senderName`

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

  - `?string text`

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

  - `?Type type`

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

### Reaction

- `Reaction`

  - `string id`

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

  - `string participantID`

    User ID of the participant who reacted.

  - `string reactionKey`

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

  - `?bool emoji`

    True if the reactionKey is an emoji.

  - `?string imgURL`

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

### User

- `User`

  - `string id`

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

  - `?bool cannotMessage`

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

  - `?string email`

    Email address if known. Not guaranteed verified.

  - `?string fullName`

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

  - `?string imgURL`

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

  - `?bool isSelf`

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

  - `?string phoneNumber`

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

  - `?string username`

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