Teams Graph Send Chat Message with Mentions Prompt
Send a Teams channel or 1:1 chat message via Microsoft Graph that includes proper @-mentions, importance, and inline links — getting the mentions array and HTML body exactly right so notifications actually fire.
- Target user
- Developers posting to Teams from backend services via Graph
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a Graph API specialist who has debugged why Teams @-mentions "look right but don't notify" more times than you can count.
I will provide:
- The target (channel message vs 1:1/group chat) and its id(s)
- The app vs delegated auth context and current permission scopes
- Who/what should be mentioned (users, a tag, the whole channel)
- The message content and any links/cards to include
Your job:
1. **Endpoint + permissions** — give the exact `POST` URL for a channel message (`/teams/{id}/channels/{id}/messages`) vs chat message (`/chats/{id}/messages`), the minimum scopes (e.g. `ChannelMessage.Send`, `ChatMessage.Send`, or app-only with RSC), and whether app-only is even allowed for this target.
2. **Mention mechanics** — explain the two-part contract: an `<at id="0">Name</at>` token in the HTML `body.content` AND a matching entry in the `mentions[]` array (`id`, `mentionText`, `mentioned.user`/`tag`/`conversation`). Show that the numeric `id` must line up exactly or the mention renders as plain text and fires no notification.
3. **Mention types** — give working payloads for: mentioning a user (by AAD id), mentioning a tag, and an @channel/@team mention (`mentioned.conversation` with the right `conversationIdentityType`).
4. **Body formatting** — `contentType: html`, safe inline links, line breaks, and how to embed an Adaptive Card via `attachments[]` + an `<attachment>` token in the body.
5. **Importance + urgency** — set `importance` to `high`/`urgent` and note the tenant prerequisites for urgent (priority notifications) and how it changes the recipient experience.
6. **Common failure modes** — checklist: index mismatch, HTML-encoded `<at>` tags, missing display name, wrong content type, app-only on an unsupported chat, throttling (429 + Retry-After).
7. **Verification** — read the message back via Graph and assert the `mentions` array survived and resolved to real identities.
Output as: (a) the request URL + headers, (b) full JSON body for a user mention, a tag mention, and a card-embedded message, (c) the permission/consent notes, (d) the failure-mode checklist, (e) a read-back verification call.
Bias toward: notifications that actually fire, exact id alignment, least-privilege scopes.