simulator-chat

name

simulator-chat

description

Simulator.Company chat & messaging specialist — sending messages to a user, and creating or reusing p2p (1:1) and group chats. In Simulator a chat is an actor of the Events system form (data.chatType = "p2p" | "group"), its participants are the actor's access-rule members, and its messages are `comment` reactions. Use when the user wants to "message", "write to", "DM", "send a message to" someone, "open a chat with", "start a conversation", or "reply in the chat". Activate on "write a message to user N", "send N a message", "open a chat with", "message someone", "напиши повідомлення користувачу", "надішли повідомлення", "відкрий чат з", "почни розмову з", "напиши юзеру", "напиши сообщение пользователю", "отправь сообщение", "открой чат с", "напиши в чат". For comments/approvals on an arbitrary actor (not a chat) use `simulator-reactions`; for files use `simulator-attachments`; for sharing/access in general use `simulator-access`.

Curated tool names (v2 server): searchUsers, getUsers, getSystemActor, getForms, filterActors, createActor, getActorByRef, saveAccessRules, createReaction, getReactions. Call them by these exact names. There is no dedicated "create chat" / "send message" tool — a chat is composed from these.

Simulator.Company Chat Specialist

In Simulator.Company a chat is an actor of the Events system form:

• data.chatType = "p2p" → a 1:1 chat · "group" → a group chat · empty → a plain event / SIP meeting (not a chat).
• Participants = the chat actor's access-rule members (keyed by userId) — not a data field. The creator is the implicit owner; other participants are added with saveAccessRules.
• Messages = comment reactions posted under the chat actor.

There is no server-side "p2p has exactly two members / don't duplicate" enforcement — this skill owns that discipline, and it must match the platform's standard p2p convention or two clients will create duplicate chats for the same pair. The convention:

• Deterministic ref = p2pConversation_<minUserId>_<maxUserId> — both participants' raw workspace userIds sorted ascending, joined with _. This is the p2p dedup key; the UI finds/reuses a chat only by this ref.
• title = <nickA>:p2p:<nickB> — nicks ordered by the same ascending userId sort.
• data = { chatType:"p2p", startDate:<nowSec>, endDate:<nowSec>, scheduleMeeting:false }.
• Participants are added by a separate saveAccessRules call (never inline in the create body); the creator is owner implicitly.

Read $CLAUDE_PLUGIN_ROOT/docs/entities/chats.md for the full model, the verbatim Events-form field list, and the current-user constraint.

Reply to the user in their own language.

---

Test case: "write a message to user N"

This is the canonical flow. Each step names the exact tool.

1 — Resolve user N

searchUsers(query="N")          # accId defaults to the active workspace

Take N's userId from the result (e.g. 4210). If several match, ask the user which one (or show name + email). getUsers lists everyone if you need to browse.

getSystemActor(objType="user", objId=<userId>) returns N's system "twin" actor. You usually do not need it to chat — membership uses the raw userId — but it get-or-creates the twin if some flow needs N represented as an actor.

2 — Resolve the Events form id (per workspace)

getForms(formTypes="system")    # find the row whose title == "Events" → its id

The Events form id differs per workspace, so don't hardcode it. (You may instead pass formName="Events" to createActor and let it resolve the id.)

3 — Build the canonical ref + title (reuse key)

The p2p dedup key needs both userIds. The recipient's came from step 1; resolve the sender's userId too (see the box below), then:

ids   = sortAscending(senderUserId, N_userId)        # numeric ascending
ref   = "p2pConversation_" + ids[0] + "_" + ids[1]   # e.g. p2pConversation_4210_4310
title = nick(ids[0]) + ":p2p:" + nick(ids[1])        # e.g. olena:p2p:petro

Getting the sender's userId. There is no PAPI "current user" endpoint, and the auth token carries the caller's saId+nick, not the per-workspace userId. So: ask the user, take it from context, or getUsers and match the token's saId/nick to a member's id. If you cannot get it, fall back to discovery-by-member in step 4 and skip the ref (note: a ref-less chat may be duplicated later by the web UI, which keys reuse on ref).

4 — Find an existing chat (reuse, don't duplicate)

Canonical — by the deterministic ref, exactly as the web UI does:

getActorByRef(formId=<EventsFormId>, ref=<ref>)     # found → reuse its id, skip to step 6

Fallback when the sender's userId is unknown — discover by participant (still finds UI-created chats, since the recipient is an access member):

filterActors(formId=<EventsFormId>, q="chatType=p2p", members="<N_userId>:view")

5 — Create the p2p chat (only if none exists)

createActor(
  formName="Events",                       # or formId=<EventsFormId>
  title=<title>,                           # "<nickA>:p2p:<nickB>"
  ref=<ref>,                               # p2pConversation_<minId>_<maxId> — REQUIRED for UI reuse
  data={ "chatType": "p2p",
         "startDate": <nowUnixSeconds>,
         "endDate":   <nowUnixSeconds>,
         "scheduleMeeting": false })        # plain unix SECONDS on Events — not a calendar object

startDate/endDate are required by the Events form. On a chat they are just "now" as integer unix seconds (the nested calendar {startDate,endDate,...} object used elsewhere does not apply here).

Then add N as the second participant (the creator is owner implicitly — do not add a self access-rule):

saveAccessRules(
  objType="actor", objId="<newChatId>",
  rules=[{ "action":"create",
           "data":{ "userId": <N_userId>,
                    "privs":{ "view":true, "modify":true, "remove":true } } }])

saveAccessRules is applied asynchronously and returns a taskId; posting the message next still works.

6 — Post the message (a comment reaction)

createReaction(type="comment", actorId="<chatId>", description="<the message text>")

That comment reaction under the chat actor is the chat message. To read the conversation back: getReactions(actorId="<chatId>", view="flat", orderValue="ASC").

---

Variations

• Group chat. Create with data.chatType="group" and no ref (the UI gives group chats no dedup), then saveAccessRules (or bulkSaveAccessRules) for every participant userId. To find a group's members later, filter by them: filterActors(members="11:view,22:view,33:view", q="chatType=group").
• Reply in a thread. Pass parentId=<reactionId> to createReaction (see simulator-reactions).
• Attach a file to a message. Upload first (uploadBase64 → attachId), then createReaction(..., attachments=[{attachId:<id>}]) — see simulator-attachments.
• Post quietly (no notification). createReaction(..., notify=false).
• Hand the message to the AI agent. createReaction(..., extra={mcp:true}) runs the platform AI agent on it under the requesting user's access (see simulator-reactions).

Reuse & safety rules

• Always look up (step 4) before creating (step 5). Creating a second p2p Events actor for the same pair silently produces a duplicate chat — the platform does not dedupe; only the deterministic ref does.
• Always set the canonical ref on create (p2pConversation_<minId>_<maxId>) so the web UI reuses the same chat instead of making its own duplicate.
• Participants are access rules, never data fields. Do not store member ids in data, and do not add a self access-rule (the creator is owner implicitly).
• Confirm before messaging on the user's behalf if the message is outward-facing — a chat message notifies the recipient.
• A chat needs chatType set; an Events actor without it is a plain event/meeting, and comments on it are ordinary discussion, not chat messages.

---

Relationship to the other skills

Skill	Boundary
simulator-agents	Delegating work to a person as an agent (assess who fits, then act / task / message) — it composes this p2p flow for its "message the person" outcome.
simulator-reactions	Generic comments/approvals/ratings on any actor (a chat message is a comment reaction — that skill covers the reaction mechanics).
simulator-actors	The Events actor's own data fields and the actor data value protocol.
simulator-access	Access rules in general (chat participants are access-rule members).
simulator-attachments	Files on a message/actor.
simulator-init	Login + workspace selection (needed before any of this).

Reference Documents

Path	When to read
$CLAUDE_PLUGIN_ROOT/docs/entities/chats.md	The chat model: Events form, chatType, members-as-access, messages-as-reactions
$CLAUDE_PLUGIN_ROOT/docs/entities/reactions.md	Reaction types, tree/threading, AI-agent reactions
$CLAUDE_PLUGIN_ROOT/docs/entities/system-forms.md	The Events system form among the built-ins

Tips

• accId/workspace defaults to the active one — make sure simulator-init ran first.
• The Events form id is per workspace — resolve it (getForms/formName), never hardcode.
• On Events, startDate/endDate are plain unix seconds, both "now" for a chat.
• Canonical reuse = getActorByRef(ref="p2pConversation_<minId>_<maxId>") (matches the web UI); it needs both userIds — the sender's isn't in the token (saId/nick only, no PAPI /me), so derive it or fall back to filterActors(members=…, q="chatType=p2p").
• A message is just createReaction(type="comment", actorId=<chatId>, description=...).