Advanced Social, Groups, and Session Control¶

This page covers social MCP workflows: friends/friendship operations, teleport offers/requests, and group membership/session control.

Chat authorization and routing model¶

The bot enforces a trust gate before routing chat text to the AI backend.

Access policy by channel¶

im-<sender-uuid> (direct IM): allow only handler or C&C group members.
local-chat (spatial/local): allow only handler or C&C group members.
group-<group-uuid>:
if <group-uuid> is the bot's own C&C group, accept all instructions in that session.
otherwise, allow only handler or C&C group members.

Unauthorized speakers receive a polite refusal reply and are not routed to AI execution.

Wake-word behavior¶

Direct IM does not require a wake word.
Multi-participant chats (group and local) require wake word prefixing:
@<botFirst> <botLast> ...
@Bot ... is additionally accepted in the bot's own C&C group chat.

Chat modalities (send-side)¶

Local chat send tools support explicit modality selection:
Chat(message, channel, chatType?) where chatType is optional and case-insensitive.
ChatWhisper(message, channel) as a convenience wrapper.
ChatShout(message, channel) as a convenience wrapper.
If chatType is omitted, the tool defaults to Normal.
Typical use is:
Whisper for nearby/quiet interaction,
Normal for standard local chat,
Shout for wider local radius.

Chat modalities (receive-side filter)¶

Incoming local and group chat is filtered by modality before AI routing.
Configure allow-list with env var LOCAL_CHAT_ALLOWED_TYPES.
Format: comma/pipe/space-separated ChatType names (case-insensitive), for example: Normal,Whisper.
Default is Normal, which keeps existing behavior for most setups.
Group IM receive messages (SessionSend) are treated as Normal for this filter.
Messages with filtered-out modalities are ignored (with a diagnostic log line).

Command authorization¶

Star commands (*help, *status, *cancel, *configure, etc.) are handler-only across all chat channels.
If handler identity is not configured, star commands are refused.

Session and concurrency notes¶

Conversation keys are channel-specific and stable:
local: local-chat
IM: im-<sender-uuid>
group: group-<group-uuid>
Only one AI request can be active at a time per bot; overlapping requests from another session receive a busy response.

Operational notes:

FriendList includes online status; use includeDetails=true to inspect rights from both sides.
FriendOfferRespond uses pending incoming offers tracked by FriendsManager (accept or decline).
FriendSetRights maps directly to the three viewer toggles for a friend: see online, locate on map, and modify/take objects.
FriendRightsGet returns one-friend rights status with both directions: theirRights (what the bot grants) and myRights (what the friend grants).
Accepting a friendship offer from a configured handler automatically grants all three rights by default.
FriendMapLocate supports wait mode (waitForReplySeconds > 0) to return region-handle and local/global coordinates.
TeleportOffersList and TeleportRequestsList expose pending IM-based teleport signals seen during this bot session.
TeleportOfferRespond requires requester UUID plus IM session UUID from a pending offer row.

Directory and search tools¶

DirectorySearchPeople
DirectorySearchGroups
DirectorySearchPlaces
DirectorySearchLand

Operational notes:

All directory tools return summary, pagination, and results payload blocks.
pagination.hasMore=true means you should call the same tool again with pagination.nextQueryStart.
DirectorySearchPeople, DirectorySearchGroups, and DirectorySearchPlaces usually use queryStart as page index (0,1,2,...).
DirectorySearchLand uses land-sale query offsets more often represented as 0,100,200,....
DirectorySearchLand supports landType values: any, mainland, estate, auction plus optional maxPrice and minArea filters.

Avatar profile tools¶

AvatarProfileGet
AvatarPicksList
AvatarClassifiedsList

Operational notes:

AvatarProfileGet returns UDP profile/interests fields and can optionally include AgentProfile capability payloads when available.
AvatarPicksList returns pick IDs/names first; use includeDetails=true to request per-pick details such as sim name, description, and global position.
AvatarClassifiedsList returns classified IDs/names first; includeDetails=true enriches with parcel/sim data, pricing, and creation/expiration timestamps.
Detail lookups are best-effort; missing detail IDs are returned in missingDetailPickIds or missingDetailClassifiedIds.

Group discovery and profile tools¶

GroupListCurrent
GroupGetProfile
GroupGetMembers
GroupGetRoles
GroupGetRoleMembers
GroupGetTitles

Use includeDetails=false for fast summaries and includeDetails=true when you need full payloads.

Group chat/session tools¶

GroupChatJoin
GroupChatLeave
GroupChatSend
GroupChatSessionsList
GroupChatAcceptInvite

Operational notes:

GroupChatSend requires an active tracked session; join first if needed.
GroupChatJoin supports waitForJoinSeconds (0 = fire-and-forget, >0 = wait for GroupChatJoined).
GroupChatSessionsList with includeDetails=true surfaces per-member moderation/voice flags.

Role/title action tools¶

GroupSetActive
GroupSetActiveTitle
GroupRoleCreate
GroupRoleUpdate
GroupRoleDelete
GroupRoleAddMember
GroupRoleRemoveMember

Verification notes:

GroupRoleAddMember and GroupRoleRemoveMember support verifyAfterSubmit and verifyWaitSeconds.
When verification is enabled, tools classify outcomes as confirmed vs submitted-but-unverified.

Structured role payload (Option B)¶

GroupRoleCreate and GroupRoleUpdate accept this object schema:

{
  "name": "Builder",
  "title": "Builder",
  "description": "Can edit and maintain builds",
  "powers": "ObjectManipulate,ObjectSetForSale"
}

powers supports either:

comma/pipe-separated GroupPowers enum names, or
numeric bitmask string.

Group invite and ban tools¶

GroupInviteUser
GroupInviteRespond
GroupBanListGet
GroupBanSet

Structured invite payload¶

{
  "targetAgentId": "99999999-8888-7777-6666-555555555555",
  "roleIdsCsv": null,
  "useEveryoneRoleIfEmpty": true
}

Structured ban payload¶

{
  "action": "ban",
  "agentIdsCsv": "99999999-8888-7777-6666-555555555555"
}

Ban notes:

Incoming group invitations are emitted as runtime event groups.invite.received (channel friends) with groupId and sessionId attributes.
GroupInviteRespond accepts action=accept|decline; pass sessionId when you want strict invite/session matching.
GroupBanSet supports verifyAfterSubmit and verifyWaitSeconds.
Verification uses read-back from GroupBanListGet-equivalent state and returns classified outcomes.

Notice tools¶

GroupNoticesList
GroupNoticeSend

Structured notice payload¶

{
  "subject": "Weekly restart",
  "message": "Region restart in 10 minutes.",
  "attachmentItemId": null,
  "attachmentOwnerId": null
}

If attachment fields are used, both IDs are required and must be UUIDs.

Group create/update tools (structured payload)¶

GroupCreate
GroupUpdate

Structured group payload (Option B)¶

{
  "name": "OpenSim Builders",
  "charter": "Collaborative build group",
  "insigniaId": null,
  "membershipFee": 0,
  "openEnrollment": true,
  "showInList": true,
  "allowPublish": false,
  "maturePublish": false
}

Suggested execution order¶

Query current state (GroupListCurrent, GroupGetRoles, GroupGetTitles).
Apply one change (GroupRoleUpdate, GroupSetActiveTitle, or GroupNoticeSend).
Re-read state to verify (GroupGetRoles/GroupGetTitles/GroupNoticesList/GroupBanListGet).
For chat automation, verify active sessions with GroupChatSessionsList before sending.

Prompt examples¶

List my friends with detailed rights and online status.

Show pending friendship offers and accept one from 99999999-8888-7777-6666-555555555555.

Get friend rights for 99999999-8888-7777-6666-555555555555.

Set friend rights for 99999999-8888-7777-6666-555555555555 with canSeeOnline true, canSeeOnMap true, canModifyObjects true.

Send a teleport offer to 99999999-8888-7777-6666-555555555555 with message "Join me at the sandbox stage".

Show pending teleport offers and decline the newest one.

Search people for "cube" starting at page 0.

Search groups for "builders" and continue with the returned nextQueryStart if hasMore is true.

Search places for "sandbox" from queryStart 0.

Search land listings of type mainland with maxPrice 5000 and minArea 512 starting at 0.

Get avatar profile and interests for 99999999-8888-7777-6666-555555555555 with capability details enabled.

List picks for 99999999-8888-7777-6666-555555555555 with details.

List classifieds for 99999999-8888-7777-6666-555555555555 with details.

List my groups with details.

Join group chat for 11111111-2222-3333-4444-555555555555 and wait up to 12 seconds.

Create role Moderators in group 11111111-2222-3333-4444-555555555555 with powers Invite and ChangeOptions.

Send a notice to group 11111111-2222-3333-4444-555555555555 saying deployment starts in 5 minutes.

Invite avatar 99999999-8888-7777-6666-555555555555 to group 11111111-2222-3333-4444-555555555555 using Everyone role fallback.

Ban avatar 99999999-8888-7777-6666-555555555555 from group 11111111-2222-3333-4444-555555555555 and verify for 15 seconds.

Advanced Social, Groups, and Session Control¶

Chat authorization and routing model¶

Access policy by channel¶

Wake-word behavior¶

Chat modalities (send-side)¶

Chat modalities (receive-side filter)¶

Command authorization¶

Session and concurrency notes¶

Friends and teleport tools¶

Directory and search tools¶

Avatar profile tools¶

Group discovery and profile tools¶

Group chat/session tools¶

Role/title action tools¶

Structured role payload (Option B)¶

Group invite and ban tools¶

Structured invite payload¶

Structured ban payload¶

Notice tools¶

Structured notice payload¶

Group create/update tools (structured payload)¶

Structured group payload (Option B)¶

Suggested execution order¶

Prompt examples¶