# Shared ## Domain Types ### Chat Handle - `class ChatHandle: …` - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` ### Link Part Response - `class LinkPartResponse: …` A rich link preview part - `reactions: Optional[List[Reaction]]` Reactions on this message part - `handle: ChatHandle` - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `is_me: bool` Whether this reaction is from the current user - `type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `id: Optional[str]` Identifier for this reaction. Pass it to `PATCH /v3/messages/{messageId}/reactions/{reactionId}` to move a sticker. Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so `PATCH` returns 404 for those. - `custom_emoji: Optional[str]` Custom emoji if type is "custom", null otherwise - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL ### Media Part Response - `class MediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `reactions: Optional[List[Reaction]]` Reactions on this message part - `handle: ChatHandle` - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `is_me: bool` Whether this reaction is from the current user - `type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `id: Optional[str]` Identifier for this reaction. Pass it to `PATCH /v3/messages/{messageId}/reactions/{reactionId}` to move a sticker. Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so `PATCH` returns 404 for those. - `custom_emoji: Optional[str]` Custom emoji if type is "custom", null otherwise - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). ### Reaction - `class Reaction: …` - `handle: ChatHandle` - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `is_me: bool` Whether this reaction is from the current user - `type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `id: Optional[str]` Identifier for this reaction. Pass it to `PATCH /v3/messages/{messageId}/reactions/{reactionId}` to move a sticker. Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so `PATCH` returns 404 for those. - `custom_emoji: Optional[str]` Custom emoji if type is "custom", null otherwise - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels ### Reaction Type - `Literal["love", "like", "dislike", 5 more]` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` ### Service Type - `Literal["iMessage", "SMS", "RCS"]` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` ### Text Decoration - `class TextDecoration: …` - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` ### Text Part Response - `class TextPartResponse: …` A text message part - `reactions: Optional[List[Reaction]]` Reactions on this message part - `handle: ChatHandle` - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `is_me: bool` Whether this reaction is from the current user - `type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `id: Optional[str]` Identifier for this reaction. Pass it to `PATCH /v3/messages/{messageId}/reactions/{reactionId}` to move a sticker. Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so `PATCH` returns 404 for those. - `custom_emoji: Optional[str]` Custom emoji if type is "custom", null otherwise - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `mention: Optional[str]` DEPRECATED: Use `mentions` instead. Handle (E.164 phone number or Apple ID email) of the **first** mention on this part. A part may carry several mentions; this field shows only the first in `value` order, so it cannot be used to determine whether a given participant was mentioned. `null` when the part carries no mention. - `mention_range: Optional[List[int]]` DEPRECATED: Use `mentions[].range` instead. Character range `[start, end)` in `value` highlighted as the **first** mention only. `null` when the range was omitted (the whole `value` is highlighted) or the part carries no mention. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `mentions: Optional[List[Mention]]` Every mention on this part, in the order they appear in `value`. `null` when the part carries no mention. A part can carry several mentions of different people — check `is_me` to tell whether this line was one of them. Only iMessage carries mentions. On a received message this is populated when the sender was on iMessage; SMS and RCS have no way to mark a mention, so a message from an SMS or RCS participant arrives as plain text with `mentions` null, even in a group where other participants are on iMessage. - `handle: str` Address of the mentioned participant, exactly as the device recorded it — an E.164 phone number or an email address. - `is_me: bool` Whether the mentioned participant is this line. - `range: List[int]` Character range `[start, end)` in `value` highlighted as this mention. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"`