send_chat_message

Send formatted messages to Microsoft Teams chats with mentions and priority settings to communicate effectively within conversations.

Instructions

Send a message to a specific chat conversation. Supports text and markdown formatting, mentions, and importance levels.

Input Schema

TableJSON Schema

Name	Required	Description
`chatId`	Yes	Chat ID
`message`	Yes	Message content
`importance`	No	Message importance
`format`	No	Message format (text or markdown)
`mentions`	No	Array of @mentions to include in the message

Implementation Reference

src/tools/chats.ts:233-337 (handler)

The handler function that implements the core logic of the 'send_chat_message' tool. It handles message formatting (text/markdown), processes mentions by fetching user display names and generating HTML mention tags, builds the payload, and sends the POST request to Microsoft Graph API `/me/chats/{chatId}/messages`.

  async ({ chatId, message, importance = "normal", format = "text", mentions }) => {
    try {
      const client = await graphService.getClient();

      // Process message content based on format
      let content: string;
      let contentType: "text" | "html";

      if (format === "markdown") {
        content = await markdownToHtml(message);
        contentType = "html";
      } else {
        content = message;
        contentType = "text";
      }

      // Process @mentions if provided
      const mentionMappings: Array<{ mention: string; userId: string; displayName: string }> = [];
      if (mentions && mentions.length > 0) {
        // Convert provided mentions to mappings with display names
        for (const mention of mentions) {
          try {
            // Get user info to get display name
            const userResponse = await client
              .api(`/users/${mention.userId}`)
              .select("displayName")
              .get();
            mentionMappings.push({
              mention: mention.mention,
              userId: mention.userId,
              displayName: userResponse.displayName || mention.mention,
            });
          } catch (_error) {
            console.warn(
              `Could not resolve user ${mention.userId}, using mention text as display name`
            );
            mentionMappings.push({
              mention: mention.mention,
              userId: mention.userId,
              displayName: mention.mention,
            });
          }
        }
      }

      // Process mentions in HTML content
      let finalMentions: Array<{
        id: number;
        mentionText: string;
        mentioned: { user: { id: string } };
      }> = [];
      if (mentionMappings.length > 0) {
        const result = processMentionsInHtml(content, mentionMappings);
        content = result.content;
        finalMentions = result.mentions;

        // Ensure we're using HTML content type when mentions are present
        contentType = "html";
      }

      // Build message payload
      const messagePayload: any = {
        body: {
          content,
          contentType,
        },
        importance,
      };

      if (finalMentions.length > 0) {
        messagePayload.mentions = finalMentions;
      }

      const result = (await client
        .api(`/me/chats/${chatId}/messages`)
        .post(messagePayload)) as ChatMessage;

      // Build success message
      const successText = `✅ Message sent successfully. Message ID: ${result.id}${
        finalMentions.length > 0
          ? `\n📱 Mentions: ${finalMentions.map((m) => m.mentionText).join(", ")}`
          : ""
      }`;

      return {
        content: [
          {
            type: "text" as const,
            text: successText,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text" as const,
            text: `❌ Failed to send message: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

src/tools/chats.ts:216-232 (schema)

Zod input schema for the 'send_chat_message' tool defining parameters: chatId (required string), message (required string), importance (optional enum: normal/high/urgent), format (optional enum: text/markdown), mentions (optional array of objects with mention text and userId).

{
  chatId: z.string().describe("Chat ID"),
  message: z.string().describe("Message content"),
  importance: z.enum(["normal", "high", "urgent"]).optional().describe("Message importance"),
  format: z.enum(["text", "markdown"]).optional().describe("Message format (text or markdown)"),
  mentions: z
    .array(
      z.object({
        mention: z
          .string()
          .describe("The @mention text (e.g., 'john.doe' or 'john.doe@company.com')"),
        userId: z.string().describe("Azure AD User ID of the mentioned user"),
      })
    )
    .optional()
    .describe("Array of @mentions to include in the message"),
},

src/tools/chats.ts:213-337 (registration)

The server.tool() call that registers the 'send_chat_message' tool on the MCP server, providing the tool name, description, input schema, and handler function.

server.tool(
  "send_chat_message",
  "Send a message to a specific chat conversation. Supports text and markdown formatting, mentions, and importance levels.",
  {
    chatId: z.string().describe("Chat ID"),
    message: z.string().describe("Message content"),
    importance: z.enum(["normal", "high", "urgent"]).optional().describe("Message importance"),
    format: z.enum(["text", "markdown"]).optional().describe("Message format (text or markdown)"),
    mentions: z
      .array(
        z.object({
          mention: z
            .string()
            .describe("The @mention text (e.g., 'john.doe' or 'john.doe@company.com')"),
          userId: z.string().describe("Azure AD User ID of the mentioned user"),
        })
      )
      .optional()
      .describe("Array of @mentions to include in the message"),
  },
  async ({ chatId, message, importance = "normal", format = "text", mentions }) => {
    try {
      const client = await graphService.getClient();

      // Process message content based on format
      let content: string;
      let contentType: "text" | "html";

      if (format === "markdown") {
        content = await markdownToHtml(message);
        contentType = "html";
      } else {
        content = message;
        contentType = "text";
      }

      // Process @mentions if provided
      const mentionMappings: Array<{ mention: string; userId: string; displayName: string }> = [];
      if (mentions && mentions.length > 0) {
        // Convert provided mentions to mappings with display names
        for (const mention of mentions) {
          try {
            // Get user info to get display name
            const userResponse = await client
              .api(`/users/${mention.userId}`)
              .select("displayName")
              .get();
            mentionMappings.push({
              mention: mention.mention,
              userId: mention.userId,
              displayName: userResponse.displayName || mention.mention,
            });
          } catch (_error) {
            console.warn(
              `Could not resolve user ${mention.userId}, using mention text as display name`
            );
            mentionMappings.push({
              mention: mention.mention,
              userId: mention.userId,
              displayName: mention.mention,
            });
          }
        }
      }

      // Process mentions in HTML content
      let finalMentions: Array<{
        id: number;
        mentionText: string;
        mentioned: { user: { id: string } };
      }> = [];
      if (mentionMappings.length > 0) {
        const result = processMentionsInHtml(content, mentionMappings);
        content = result.content;
        finalMentions = result.mentions;

        // Ensure we're using HTML content type when mentions are present
        contentType = "html";
      }

      // Build message payload
      const messagePayload: any = {
        body: {
          content,
          contentType,
        },
        importance,
      };

      if (finalMentions.length > 0) {
        messagePayload.mentions = finalMentions;
      }

      const result = (await client
        .api(`/me/chats/${chatId}/messages`)
        .post(messagePayload)) as ChatMessage;

      // Build success message
      const successText = `✅ Message sent successfully. Message ID: ${result.id}${
        finalMentions.length > 0
          ? `\n📱 Mentions: ${finalMentions.map((m) => m.mentionText).join(", ")}`
          : ""
      }`;

      return {
        content: [
          {
            type: "text" as const,
            text: successText,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text" as const,
            text: `❌ Failed to send message: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

src/index.ts:135-135 (registration)
Invocation of registerChatTools(server, graphService) in the main MCP server setup, which registers all chat tools including 'send_chat_message'.
```
registerChatTools(server, graphService);
```

Teams MCP