Step by step
Create or find the room
ethora-app-create-chat { title, pinned } creates a group room in an app you own and returns its JID; pinned: true makes new users auto-join. ethora-app-get-default-rooms lists the selected app’s rooms. ethora-app-delete-chat { chatJid } removes the room, its archive and all memberships; irreversible, and only registered when the dangerous-tools flag is on.
Post a message and wait for the agent
ethora-chats-message-v2 { text, roomJid, senderName, waitForReplySec } posts into one room in user auth, the hosted default. Set waitForReplySec up to 60 and the call holds until an AI agent in the room answers, returning it in replies.
Read the archive
ethora-chats-history-v2 { roomJid, limit, before } returns results newest last, each with from, nick, body and ts, plus a nextBefore cursor for older pages. It works in user or B2B auth, not app-token. A 502 MAM_READ_FAILED or mamUnavailable: true means the deployment has no message archive.
Broadcast to many rooms as a job
ethora-chats-broadcast-v2 { appId, text, allRooms | chatIds | chatNames } enqueues a job and returns a jobId; nothing is sent synchronously and the three targets are exclusive. It needs app-token or B2B mode with an explicit appId. ethora-chats-broadcast-job-v2 { jobId } reads the state once with per-room results; ethora-wait-broadcast-job-v2 { jobId, timeoutMs } blocks until a terminal state, under the same auth that enqueued it.
You: Tell every room in Ward Rounds that handover starts in 10 minutes and confirm delivery.
Assistant: ethora-chats-broadcast-v2 { appId, text, allRooms: true } ... jobId 7f3e.
ethora-wait-broadcast-job-v2 { appId, jobId: "7f3e", timeoutMs: 60000 } ... completed, 14 rooms, 0 failed.Search messages and pull context
ethora-messages-search-v2 { q, chatId, fromUserId, since, until, sort, limit, offset } searches an app’s messages under B2B or tenant-actor auth. ethora-messages-context-v2 { chatId, aroundStanzaId | aroundMessageId, radius } returns the messages before and after a hit, so an agent can quote a thread rather than a lone line.
Unread counts for notification logic
ethora-unread-counts-v2 { userIds, mode, cap } returns per-room unread counts for a set of users in one batch: mode: count gives capped numbers, mode: flag booleans. It requires Mongo message archiving. Pair it with a broadcast to nudge only users who have not read the room.
The tools this uses
Names and descriptions come from the server’s own tool list. Read-only tools are safe to auto-approve; destructive ones make your client ask first. Full reference.
| Tool | Name | What it does | Access |
|---|---|---|---|
| Create Chat Room | ethora-app-create-chat | Create a new chat room (MUC room) inside an app the caller owns. | write |
| Delete Chat Room | ethora-app-delete-chat | Permanently delete a chat room from an app the caller owns - removes the MUC room, its message archive, and all member affiliations. | destructive |
| Get Default Rooms | ethora-app-get-default-rooms | List the default chat rooms (MUC rooms) of the currently selected Ethora app - every new user auto-joins these. | read-only |
| Send Chat Message | ethora-chats-message-v2 | Post a message into a chat room of an app (POST /v2/apps/:appId/chats/broadcast targeting one room). | write |
| Get Chat History | ethora-chats-history-v2 | Read the archived messages of a chat room (GET /v2/apps/:appId/chats/:chatId/messages, newest last). | read-only |
| Broadcast Message | ethora-chats-broadcast-v2 | Enqueue an asynchronous broadcast job posting a message to one or more chat rooms of an app - returns a jobId; messages are not sent synchronously. | write |
| Get Broadcast Job | ethora-chats-broadcast-job-v2 | Fetch the current status and per-room results of a broadcast job by jobId (one-shot, no polling). | read-only |
| Wait for Broadcast Job | ethora-wait-broadcast-job-v2 | Block until a broadcast job reaches a terminal state (completed or failed) or until timeoutMs - read-only polling wrapper around ethora-chats-broadcast-job-v2. | read-only |
| Search Messages | ethora-messages-search-v2 | Search an App’s chat messages (GET /v2/apps/:appId/messages/search). | read-only |
| Get Message Context | ethora-messages-context-v2 | Fetch the messages surrounding a target message (GET /v2/apps/:appId/chats/:chatId/messages/context). | read-only |
| Get Unread Counts | ethora-unread-counts-v2 | Batch per-room unread message counts for a set of users (POST /v2/apps/:appId/users/unread-counts). | read-only |
Announce, verify, then nudge the stragglers
“In the Ward Rounds app, post 'Handover starts in 10 minutes in room B' to every room, wait for the job and tell me which rooms failed. Then check whether users u_101, u_102 and u_103 have anything unread, and show me the last five messages in Night shift.”
ethora-chats-broadcast-v2{ appId: "66f3d0e1f2a3b4c5d6e7f8a9", text: "Handover starts in 10 minutes in room B", allRooms: true }ethora-wait-broadcast-job-v2{ appId: "66f3d0e1f2a3b4c5d6e7f8a9", jobId: "7f3e2c1b", timeoutMs: 60000, intervalMs: 2000 }ethora-unread-counts-v2{ appId: "66f3d0e1f2a3b4c5d6e7f8a9", userIds: ["u_101", "u_102", "u_103"], mode: "flag" }ethora-chats-history-v2{ roomJid: "66f3d0e1f2a3b4c5d6e7f8a9_nightshift", limit: 5 }
One message delivered to every room with per-room results, a list of who still has unread messages, and the tail of Night shift.
Good to know
ethora-app-create-chatreturns the JID asjid; every room tool accepts the JID or the barechatIdwith a selected app.- Broadcast is never synchronous: the send tool returns a
jobId, the job tool is a one-shot read, the wait tool polls. MixingallRooms,chatIdsandchatNamesreturns 400. - Auth modes differ: message and history work in user auth; broadcast needs app-token or B2B with an explicit
appId; search and unread counts use B2B auth. waitForReplySeccaps at 60. With no agent in the room the call returns without replies rather than failing.
