[Content request]: Is this API correct? https://canary.botapi.skype.com/teams/v3/conversations How to test this canary API endpoint?

[ChetanSharma-msft]

Issue type

Update to existing content

Details

1. Is this API correct? https://canary.botapi.skype.com/teams/v3/conversations

We have tried to execute the code but no luck. Please let us know How to test this API?

2. Access token related endpoint also looks wrong to me. Please validate the doc and update it accordingly.

3. What will be the behavior or format of notification in M365 Copilot chat installed CEA agent for this proactive message.
   Can we add any reference notification screenshot?

4. Added reference doc for creating the conversation is going to the below doc which is related to creating the group chat related conversation but not for 1:1.
   https://learn.microsoft.com/en-us/graph/api/group-post-conversations?view=graph-rest-1.0&tabs=http

Is this group chat related conversation is valid for M365 Copilot installed CEA agent?

5. We have tried to execute below code which is not throwing any error but not able to get any proactive message in Teams/M365 Copilot chat:

const config = require("./config");
async function getToken() {
const url =
"https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token";
const params = new URLSearchParams();
params.append("grant_type", "client_credentials");
params.append("client_id", "xxxxxxxx");
params.append("client_secret", "xxxxxxxx");
params.append("scope", "https://api.botframework.com/.default");

const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/x-www-form-urlencoded",
},
body: params.toString(),
});

if (!response.ok) {
throw new Error(Error! status: ${response.status});
}

const data = await response.json();
return data;
}

async function proactiveMessage(userId, tenantId, customMessage) {
// Use provided values or fallback to hardcoded defaults
const USER_AAD_OBJECT_ID = userId || "xxxxxxxxxxxxxxx";
const TENANT_ID = tenantId || "xxxxxxxxxxxxx";
const messageText = customMessage || "Hello proactive world";

let accessToken;
try {
console.log("Fetching access token...");
const tokenResponse = await getToken();
accessToken = tokenResponse.access_token;
if (!accessToken) {
throw new Error("Failed to obtain access token");
}
} catch (error) {
console.error("Error retrieving access token:", error);
throw error;
}

const createConversationBody = {
members: [{ id: USER_AAD_OBJECT_ID }],
tenantId: TENANT_ID,
channelData: {
productContext: "Copilot",
conversation: {
conversationSubType: "AgentProactive",
},
},
};

try {
const createConversationResponse = await fetch(
"https://smba.trafficmanager.net/teams/v3/conversations",
// Tried this as well: "https://canary.botapi.skype.com/teams/v3/conversations"
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: Bearer ${accessToken},
},
body: JSON.stringify(createConversationBody),
}
);

if (!createConversationResponse.ok) {
  const errorText = await createConversationResponse.text();
  console.error("Create conversation error:", errorText);
  throw new Error(`Failed to create conversation: ${createConversationResponse.status} - ${errorText}`);
}

const createConversationResponseData = 
  await createConversationResponse.json(); 
console.log("Create conversation response", createConversationResponseData); 

const body = { 
  text: messageText, 
  type: "message", 
}; 


const response = await fetch( 
  `https://smba.trafficmanager.net/fr/67174xxxxxxxxxxxxxxxxx4096de8b66d3/v3/conversations/${createConversationResponseData.id}/activities`, 
  { 
    method: "POST", 
    headers: { 
      "Content-Type": "application/json", 
      Authorization: `Bearer ${accessToken}`, 
    }, 
    body: JSON.stringify(body), 
  } 
);

if (!response.ok) {
  const errorText = await response.text();
  console.error("Send message error:", errorText);
  throw new Error(`Failed to send message: ${response.status} - ${errorText}`);
}

const responseData = await response.json();
console.log("Proactive message sent", responseData);
return responseData;

} catch (error) {
console.error("Error sending proactive message:", error);
throw error;
}
}

module.exports = { proactiveMessage };`

Getting below logs:
Calling proactiveMessage()... Fetching access token... Create conversation response { id: '19:XxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxT5vxM1@thread.v2' } Proactive message sent { id: '1766579384826' }

Subject matter expert

Lauragra

Priority

P2 - The request is a high priority but not urgent.

Target publish date

No response

Approximate size of the work item

None

Additional details

Doc link: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/custom-engine-agent-asynchronous-flow#proactive-messages

[Benjiiim]

May I add that it would be very interesting to have some explanation on how to handle the difference between Teams and Copilot Chat regarding proactive notifications for Custom Engine Agents?
As far as I understand, a new API has been built to allow the creation of a new conversation in Copilot Chat to send proactive messages, given a user id.
In Teams, the process is far more complex as developers need to keep the conversationId / conversation reference of an existing conversation between the agent and the user (or should create a new conversation if needed). Then, the proactive message should be sent to this single conversation as we can't create a new conversation for the same agent/bot:user combination. That can create confusion for the user and the next interaction with the agent as this unique conversation can be used for multiple subjects in parallel.
Insights on these would be very helpful.

[Prasad-MSFT]

We are currently reviewing this with the engineering team to validate the expected behavior and required updates. Once we receive confirmation and guidance from them, we will proceed with updating the documentation accordingly and keep you informed.