sometimesgroups, friends and presence
social actions use the installer’s relationships and authority. group ownership never expands access to other members’ private accounts.
group operations
bot.groups.create creates a group attributed to the bot while assigning human ownership to the installer. include the installer automatically; invited members must satisfy existing friendship, blocking and capacity rules. a single-chat installation does not gain access to the new group automatically: return its creation receipt, then the user can authorize a new installation there. existing group edits and membership changes require both the matching grant and current installer ownership at commit. ownership transfer, group destruction and group bot exclusions are human-only in v1.
addressing users
bots use stable IDs obtained from granted group/friend/request/profile surfaces or explicit command user selections. GET /profiles/resolve?username=HANDLE requires profile.read_others and returns a basic identity only if the installer could normally view that account; it is not a global account directory. human developer invite-list editing uses the dashboard’s own user picker. invalid or hidden identities return not_found without differentiating the reason.
presence and typing privacy
presence reads are limited to eligible friends, members of authorized chats or permitted bot DM peers. privacy opt-outs yield no online state; do not report a hidden user as offline. only online boolean and lease expiry are exposed, never device count, activity timestamps or last-seen history. typing is delivered only as transient gateway events and expires in five seconds. bots cannot publish human typing events, extend human presence, suppress human notifications by sending activity heartbeats or mark a conversation as read.
notifications to the installer
POST /notifications requires notifications.send and accepts {title,body,chat_id?,message_id?}. title is at most 80 characters, body at most 240; destination must be a currently authorized Sometimes resource. no arbitrary URL, recipient ID or push token is accepted. return {id,accepted:true} without delivery/read status. obey quiet hours, per-device categories, preview privacy and chat mutes before queueing and again before delivery. notifications containing message data require that message to remain readable. mute and notification grants cannot bypass OS permissions or spam limits.
group and relationship routes
FriendRequest is {id,sender,recipient,direction,created_at,revision}; basic identities contain no contact details. accepting/denying requires a request actually addressed to the installer. cancellation applies only to the installer’s outgoing request. block changes immediately affect message/event/media authorization; the response is a mutation receipt, not a full block-list export.
scroll the table horizontally to see all columns.