Webex Messaging Rooms & Messages
Post updates into Webex spaces, reply in threads, DM a colleague by email and catch up on what was said in a room, with markdown messages and Adaptive Card attachments from a Webex bot or user token.
Connect this API to an AI agent Browse all specs
What you can do with Webex Messaging Rooms & Messages via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /people/me |
getMyDetails | Show who the token belongs to (bot or user) |
| GET | /rooms |
listRooms | List the spaces the bot or user is in, most recent first |
| POST | /rooms |
createRoom | Create a new group space |
| GET | /rooms/{roomId} |
getRoom | Get one space's title and details |
| GET | /messages |
listMessages | Read recent messages in a space |
| POST | /messages |
createMessage | Send a message to a space or a person (text, markdown or card) |
| GET | /messages/direct |
listDirectMessages | Read the 1:1 conversation with a person |
| GET | /messages/{messageId} |
getMessage | Get one message by id |
| PUT | /messages/{messageId} |
editMessage | Edit a message the bot or user sent |
| GET | /memberships |
listMemberships | List who is in a space |
| POST | /memberships |
createMembership | Add a person to a space by email or id |
Authentication
bearerAuth
Bearer token — sent as Authorization: Bearer <token>
How to get a credential
- Sign in at developer.webex.com with a Webex account (a free account works).
- Bot (recommended): open My Webex Apps → Create a New App → Bot, fill in name, username and icon, then copy the Bot access token. Bot tokens do not expire. Add the bot to each space it should read or post in.
- Acting as a user: create an Integration and use OAuth 2.0 authorization code with the scopes below. (The personal access token on the docs page lasts only 12 hours; use it for testing.)
Permissions used
| Scope | Operations |
|---|---|
| spark:people_read | getMyDetails |
| spark:rooms_read / spark:rooms_write | listRooms, getRoom / createRoom |
| spark:messages_read / spark:messages_write | listMessages, listDirectMessages, getMessage / createMessage, editMessage |
| spark:memberships_read / spark:memberships_write | listMemberships / createMembership |
Common errors
- 401 Unauthorized: the token expired (personal tokens last 12 hours) or is wrong.
- 403 Forbidden: the bot or user is not a member of that space, or a bot tried to list messages without
mentionedPeople=mein a group space. - 400 Bad Request: missing
roomId, or bothroomIdandtoPersonEmailwere sent. - 429 Too Many Requests: wait for the
Retry-Afterseconds.
Store the token as a VX Agents credential (Bearer token).
Usage guide
Setup
- Credential: a Webex bot access token (does not expire) or an Integration OAuth token, stored as a Bearer credential. Personal tokens from the docs page last 12 hours: testing only.
- A bot only sees spaces it has been added to. Worth pinning: the
roomIdof the space the agent posts in (fromlistRooms). - Call
getMyDetailsfirst to confirm which bot or user the token acts as.
Post an update and follow the conversation
listRoomswithtype=groupandsortBy=lastactivityto find the space;getRoomto confirm its title.createMessagewithroomIdandmarkdown(ortext). To reply in a thread, addparentId= the id of the first message in that thread. To DM someone, sendtoPersonEmailinstead ofroomId.- For a card, send
attachments: [{"contentType": "application/vnd.microsoft.card.adaptive", "content": {...Adaptive Card JSON...}}]plus atextfallback. listMessageswithroomId(newest first,maxup to 100; page back withbeforeMessage) to read what was said. A bot in a group space must addmentionedPeople=meand only sees messages that mention it.listDirectMessageswithpersonEmailto read a 1:1 conversation.editMessagewithroomIdand newmarkdown/textto fix a message the token sent.listMembershipswithroomIdto see who is in a space;createMembershipwithroomId+personEmailto add someone;createRoomwithtitlefor a new space.
Confirm with the user before createMessage, editMessage, createRoom or createMembership: they post to or change spaces other people see.
Good to know
- Ids (
roomId,messageId,personId) are long base64 strings; pass them exactly as returned. - Send either
roomIdortoPersonId/toPersonEmail, never both. markdownsupports bold, italics, lists, links and<@personEmail:[email protected]>mentions; max message size is 7,439 bytes.- Timestamps are ISO 8601 UTC (
created,lastActivity). - Messages can be edited, but only by the sender; edits show an "Edited" label.
- On 429, wait for the
Retry-Afterseconds before retrying.
Source: Webex Messaging API reference (https://developer.webex.com/messaging/docs/api/v1/messages), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Webex Messaging Rooms & Messages” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.