Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In chats and channels that support threading, messages appear at two levels:
- L1 (top-level): A message in the main chat or channel conversation. An L1 message can be the root of a thread.
- L2 (in-thread): A reply in the thread under a top-level (L1) message. All replies in that thread share the same root. An L2 reply can't start a nested thread.
An agent can start a new thread or respond within an existing thread to keep a discussion together under its original message. Threads help users work through a task without mixing follow-up questions with other conversations.
The threading capabilities described in this article are in preview. They are available in channels and in one-on-one agent chats, including chats with agentic users.
Recommended agent behavior
Where threading is supported, agents should always respond in a thread:
- If the user's message is top-level (L1), reply in a thread under that message.
- If the user's message is already in a thread (L2), reply in the same thread.
Send a new top-level message only to start a separate discussion.
For example, a user sends "Help me plan a trip" as a top-level message. The agent replies in a thread under that request, where the user and agent discuss dates, hotels, and itinerary changes.
Identify and track discussions
Get the discussion IDs
Use the following IDs from the incoming activity to identify a discussion and choose where to send responses:
| ID | Incoming activity field |
|---|---|
| Containing chat or channel ID | channelData.chat.id or channelData.channel.id |
| Thread root message ID | channelData.replyChain.id |
Both top-level messages (L1) and thread replies (L2) include channelData.replyChain.id when threading is supported. This field always identifies the top-level message at the root of the discussion.
Before attempting a thread reply for an incoming activity, check that it provides channelData.replyChain.id. If the field is absent, don't attempt a thread reply for that activity.
If your agent needs to handle these levels differently, see Identify the incoming activity's level.
Store data by scope
Your agent might store conversation history or task progress to continue a discussion across multiple messages. Choose a storage key based on the scope of that data:
- For data about the entire chat or channel, use
channelData.chat.idorchannelData.channel.id. - For data about a specific thread, use the containing chat or channel ID together with the L1 root message ID (
channelData.replyChain.id).
Don't assume a particular meaning for conversation.id or use it as the storage key for this data. Treat it as an opaque value: don't parse it or use it to distinguish L1 from L2.
Implement threading with Teams SDK
The activity context (ctx below) represents the incoming activity; app represents the agent application. With context-level send and reply methods, the SDK chooses where the response appears based on the incoming activity level and conversation type. With app-level send and reply methods, you specify the destination yourself. You can call the app-level methods while handling an incoming activity or later for proactive messaging, such as notifications or scheduled reminders that aren't direct responses to user requests.
Choose where a message goes
Important
In a one-on-one chat, the send and reply methods on the incoming context object respond to a top-level (L1) message at L1. This default differs from the recommended agent behavior, which is to respond in the message's thread (L2). To respond at L2 in a supported chat, use the app-level reply method with the containing chat ID and the root message ID. In channels, context-based responses already go to L2.
| To do this | Call | One-on-one chat | Channel |
|---|---|---|---|
| Respond where the user wrote | ctx.SendAsync(message) |
In the same thread if the user's message is L2; otherwise L1. | In the thread of the user's message. |
| Respond and quote the user's message | ctx.ReplyAsync(message) |
Same placement as SendAsync. |
Same placement as SendAsync. |
| Post a new top-level message | app.SendAsync(chatOrChannelId, message) |
At the top level (L1). | At the top level (L1). |
| Reply in a thread | app.ReplyAsync(chatOrChannelId, rootMessageId, message) |
In the specified root message's thread (L2), starting it if needed. No automatic quote. | In the specified root message's thread (L2). No automatic quote. |
Take chatOrChannelId from ChannelData.Chat.Id or ChannelData.Channel.Id, and rootMessageId from ChannelData.ReplyChain.Id.
| To do this | Call | One-on-one chat | Channel |
|---|---|---|---|
| Respond where the user wrote | ctx.send(message) |
In the same thread if the user's message is L2; otherwise L1. | In the thread of the user's message. |
| Respond and quote the user's message | ctx.reply(message) |
Same placement as send. |
Same placement as send. |
| Post a new top-level message | app.send(chatOrChannelId, message) |
At the top level (L1). | At the top level (L1). |
| Reply in a thread | app.reply(chatOrChannelId, rootMessageId, message) |
In the specified root message's thread (L2), starting it if needed. No automatic quote. | In the specified root message's thread (L2). No automatic quote. |
Take chatOrChannelId from channelData.chat.id or channelData.channel.id, and rootMessageId from channelData.replyChain.id.
| To do this | Call | One-on-one chat | Channel |
|---|---|---|---|
| Respond where the user wrote | ctx.send(message) |
In the same thread if the user's message is L2; otherwise L1. | In the thread of the user's message. |
| Respond and quote the user's message | ctx.reply(message) |
Same placement as send. |
Same placement as send. |
| Post a new top-level message | app.send(chat_or_channel_id, message) |
At the top level (L1). | At the top level (L1). |
| Reply in a thread | app.reply(chat_or_channel_id, root_message_id, message) |
In the specified root message's thread (L2), starting it if needed. No automatic quote. | In the specified root message's thread (L2). No automatic quote. |
Take chat_or_channel_id from channel_data.chat.id or channel_data.channel.id, and root_message_id from channel_data.reply_chain.id.
Sending a reply
The following examples show how to send a thread reply (L2) in a chat. They assume you've initialized a Teams SDK app and use the app-level methods to explicitly reply in the thread. For channels, use the channel ID as indicated in the table above.
When responding as an agentic user, app-level send and reply methods require you to pass the agentic identity explicitly, even when called inside an incoming activity handler. Context-level methods use the incoming activity's identity automatically. For more information, see Receiving and sending messages as an Agentic User.
Use Teams SDK version 2.2 or later for these examples.
Configure the app's serviceUrl with the destination's full incoming service URL before using app-level methods. These methods use the app configuration, then SERVICE_URL, then https://smba.trafficmanager.net/teams; they don't take a per-call URL or automatically use the incoming activity's URL.
import { getAgenticIdentity } from '@microsoft/teams.api';
app.on('message', async (ctx) => {
const activity = ctx.activity;
const chatId = activity.channelData?.chat?.id;
const rootMessageId = activity.channelData?.replyChain?.id;
if (!chatId || !rootMessageId) {
throw new Error('A chat ID and thread root message ID are required.');
}
await app.reply(chatId, rootMessageId, 'Let us plan your trip in this thread.', {
agenticIdentity: getAgenticIdentity(activity.recipient),
});
});
To start a separate discussion at L1, use app.send(chatId, message) instead of app.reply(). A root message ID is not required.
await app.send(chatId, 'A new travel policy is available.', {
agenticIdentity: getAgenticIdentity(activity.recipient),
});
Use Teams SDK version 2.2 or later for these examples.
app.OnMessage(async (ctx, cancellationToken) =>
{
var activity = ctx.Activity;
string? chatId = activity.ChannelData?.Chat?.Id;
string? rootMessageId = activity.ChannelData?.ReplyChain?.Id;
if (string.IsNullOrEmpty(chatId) || string.IsNullOrEmpty(rootMessageId))
{
throw new InvalidOperationException(
"A chat ID and thread root message ID are required.");
}
await app.ReplyAsync(
chatId,
rootMessageId,
"Let us plan your trip in this thread.",
serviceUrl: activity.ServiceUrl,
agenticIdentity: activity.Recipient?.GetAgenticIdentity(),
cancellationToken: cancellationToken);
});
To start a separate discussion at L1, use app.SendAsync(chatId, message) instead of app.ReplyAsync(). A root message ID is not required.
await app.SendAsync(
chatId,
"A new travel policy is available.",
serviceUrl: activity.ServiceUrl,
agenticIdentity: activity.Recipient?.GetAgenticIdentity(),
cancellationToken: cancellationToken);
Without an explicit serviceUrl, C# app-level sends use the last inbound activity's service URL; they throw until the app has received an activity.
Use Teams SDK version 2.2 or later for these examples.
from microsoft_teams.api import MessageActivity
from microsoft_teams.apps import ActivityContext
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
activity = ctx.activity
data = activity.channel_data
chat_id = data.chat.id if data and data.chat else None
root_message_id = data.reply_chain.id if data and data.reply_chain else None
if not chat_id or not root_message_id:
raise ValueError("A chat ID and thread root message ID are required.")
await app.reply(
chat_id,
root_message_id,
"Let us plan your trip in this thread.",
service_url=activity.service_url,
agentic_identity=activity.recipient.agentic_identity,
)
To start a separate discussion at L1, use app.send(chat_id, message) instead of app.reply(). A root message ID is not required.
await app.send(
chat_id,
"A new travel policy is available.",
service_url=activity.service_url,
agentic_identity=activity.recipient.agentic_identity,
)
Without an explicit service_url, Python app-level sends use the app's configured URL, then SERVICE_URL, then https://smba.trafficmanager.net/teams.
Implement threading with the REST API
These endpoints use the Agent Communication Service (ACS) REST API. Use the full serviceUrl from the incoming activity. Follow the token acquisition and request construction instructions in Connect an agent to Teams without an SDK. In the following examples, {accessToken} is the resulting ACS access token.
Send a top-level message
To send a top-level message (L1) with the REST API, use the containing chat or channel ID. Set chatOrChannelId to channelData.chat.id for a chat or channelData.channel.id for a channel:
POST {serviceUrl}/v3/conversations/{chatOrChannelId}/activities
Authorization: Bearer {accessToken}
Content-Type: application/json
{
"type": "message",
"text": "A new travel policy is available."
}
This is the REST API equivalent of app.send(chatOrChannelId, message).
A successful top-level send returns a ResourceResponse containing the sent message's id. For example:
{
"id": "{messageId}"
}
Store this ID as the root message ID if your agent needs to send replies in this message's thread later.
Send an in-thread reply
For new implementations, use the following /replyChains endpoint to send in-thread replies (L2). Use the same containing chat or channel ID for chatOrChannelId. Set rootMessageId to the incoming activity's channelData.replyChain.id, or to the stored id returned when your agent sent the top-level message:
POST {serviceUrl}/v3/conversations/{chatOrChannelId}/replyChains/{rootMessageId}
Authorization: Bearer {accessToken}
Content-Type: application/json
{
"type": "message",
"text": "Let us plan your trip in this thread."
}
This is the REST API equivalent of app.reply(chatOrChannelId, rootMessageId, message).
Existing integrations that already send L2 messages directly through /activities can continue using that route.
Threading-specific error responses
Sending an in-thread reply can return the following errors:
| Condition | HTTP status code | Response error code | Error message |
|---|---|---|---|
chatOrChannelId isn't a containing chat or channel ID. |
400 |
BadArgument |
conversationId must be a thread id (19:...@...), not a reply-chain id (;messageid=) or a user id; the reply chain is identified by replyChainId |
| The chat or channel doesn't exist or was deleted. | 404 |
ConversationNotFound |
Conversation not found. |
rootMessageId doesn't exist in the specified chat or channel. |
404 |
ActivityNotFoundInConversation |
Message does not exist in the thread. |
rootMessageId identifies a targeted message. |
400 |
BadArgument |
Replies are not allowed for Targeted Messages. |
| The chat doesn't support threads. | 400 |
BadArgument |
Reply chains is not allowed in this thread type. |
Identify the incoming activity's level
Identifying the incoming activity's level is optional. If your agent handles top-level messages and thread replies differently, use the following criteria.
To classify an activity as L2, channelData.replyChain.id (the root message ID) must be present. Then apply the additional conditions in the table:
| Incoming activity | Additional condition for L2 |
|---|---|
User-typed message, messageUpdate, or messageDelete |
activity.id differs from the root message ID. |
messageReaction activity |
replyToId differs from the root message ID. |
Card button response sent as a message with channelData.source |
replyToId differs from the root message ID. |
Message-action invoke with value.messagePayload |
value.messagePayload.id differs from the root message ID. |
Other invoke with replyToId |
replyToId differs from the root message ID. |
invoke with neither value.messagePayload nor replyToId |
No additional condition. |
Other activity types, such as installationUpdate or conversationUpdate |
Never classified as L2. |