Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Com mensagens direcionadas, usuários e agentes podem interagir de forma privada sem distrair outros usuários ou expor informações que não são destinadas ao grupo. Considere as seguintes situações:
- Um usuário pode pedir a um agente para gerar um resumo da discussão sem que os outros participantes vejam a solicitação ou a resposta.
- Um usuário pode solicitar informações em particular a um agente com a intenção de compartilhá-las com o grupo, mas deseja confirmar o conteúdo da mensagem primeiro. O agente pode responder de forma privada, com uma ação sugerida solicitando a aprovação do usuário para compartilhar sua resposta. Quando o usuário aprova, o agente reenvia a mensagem publicamente. Para obter mais informações, consulte práticas recomendadas e diretrizes de design.
- Um usuário pode dirigir e monitorar o trabalho em segundo plano com os agentes, referenciando o contexto da conversa, sem distrair os outros participantes.
- Um agente pode detectar um novo usuário entrando em uma conversa grande e de longa duração e enviar proativamente a ele uma mensagem privada de boas-vindas e um resumo.
Importante
As mensagens direcionadas são uma parte fundamental do design do agente para conversas em grupo e exigem um tratamento cuidadoso das expectativas de privacidade do usuário. Para obter mais informações, consulte práticas recomendadas e diretrizes de design.
Principais aspectos das mensagens direcionadas
Mensagens direcionadas:
- Pode ser usado apenas para interações individuais entre um agente e um usuário em canais, chats em grupo e chats de reunião.
- É compatível com todos os recursos de mensagens padrão , como botões, imagens, Cartões Adaptáveis e arquivos, mas não oferece suporte a reações, respostas ou encaminhamento.
- Geralmente operam da mesma forma que mensagens padrão, com as mesmas operações de API. Usuários e agentes podem modificar ou excluir mensagens direcionadas após enviá-las, mas não podem alterar sua visibilidade. Se um cenário exigir que uma mensagem privada seja tornada pública, o remetente deverá excluí-la e reenviá-la como uma mensagem padrão; Consulte Práticas recomendadas e diretrizes de design.
- Expira 24 horas após ser enviado. Quando uma mensagem direcionada expira, o Teams a exclui de todos os clientes, embora possa ser mantida no armazenamento seguro com base na política organizacional.
- Não são visíveis para usuários não direcionados, mesmo se eles estiverem usando uma versão mais antiga do cliente do Teams que não oferece suporte a mensagens direcionadas.
Experiência do usuário
As mensagens direcionadas enviadas ou recebidas por um usuário são apresentadas no fluxo da conversa com um indicador que indica Somente você pode ver esta mensagem.
Os usuários enviam mensagens direcionadas a um agente em um canal, chat em grupo ou chat de reunião invocando seu nome como um comando de barra.
Quando um usuário insere um / em uma caixa de composição vazia, o Teams exibe um menu de preenchimento automático contendo comandos internos para tarefas comuns. Se a conversa incluir agentes qualificados para receber mensagens direcionadas, o menu também incluirá um comando de mensagem direcionada para cada um deles, com o nome do agente e exibindo seu ícone.
A ativação do comando de mensagem direcionada de um agente alterna a caixa de redação para o modo de mensagem direcionada. Depois que o usuário redigir uma mensagem e selecionar Enviar, a mensagem resultante será direcionada ao agente e não poderá ser vista por outros participantes da conversa.
Para obter mais informações sobre comandos de barra, incluindo como registrar comandos de barra nomeados extras que podem ser despachados para seu agente, consulte Expor comandos de barra de agentes e aplicativos.
Visualização de Prompt em mensagens direcionadas
A visualização de prompt ajuda a preservar o contexto de conversa em cenários de mensagens direcionadas, exibindo uma visualização compacta da solicitação original do usuário acima da resposta do agente. A Visualização de Prompt ajuda os usuários a entender o contexto de uma resposta sem expor o prompt original a outros participantes. Uma única resposta de agente pode conter várias visualizações de prompt.
A visualização do prompt pode aparecer nas respostas do agente público e privado:
O agente responde em particular à mensagem de destino do usuário, para que apenas o usuário pretendido possa ver a resposta e a visualização do prompt.
Respostas entre aspas em mensagens direcionadas
As respostas citadas fazem referência a uma mensagem anterior em um thread, ajudando os leitores a identificar com o que uma resposta se relaciona e navegar de volta ao contexto original. Use uma resposta entre aspas ao responder a um ponto anterior em um tópico ocupado ou quando os leitores precisarem retornar à mensagem referenciada. As respostas entre aspas dão suporte à navegação por thread, enquanto a Visualização do prompt preserva a relação privada prompt-resposta para respostas direcionadas do agente e compartilhamento baseado em aprovação.
Para obter mais informações, consulte as respostas citadas.
Implementar mensagens direcionadas
As mensagens direcionadas são enviadas e recebidas usando as mesmas operações que as mensagens padrão de destinatário único no SDK do Teams, mas têm uma propriedade booleana que indica se são direcionadas.
Receba mensagens direcionadas
Um agente deve aceitar por meio de seu manifesto para poder receber mensagens direcionadas. Se não for aceito, o Teams não dará aos usuários a opção de enviar uma mensagem direcionada ao agente.
Os agentes que optam por receber mensagens direcionadas devem sempre marcar a visibilidade das mensagens que recebem e levar isso em consideração ao gerar respostas e rastrear o contexto de uma conversa. Para obter mais informações, consulte práticas recomendadas e diretrizes de design.
Para optar por receber mensagens direcionadas, defina supportsTargetedMessages a propriedade como true na entrada do bots seu agente no manifesto do aplicativo.
{
"bots": [
{
"botId": "{{BOT_ID}}",
"scopes": ["personal", "team", "groupChat"],
"supportsTargetedMessages": true
}
]
}
Os agentes recebem mensagens por meio de eventos de mensagem padrão. As mensagens direcionadas podem ser diferenciadas das mensagens públicas, conforme mostrado no snippet a seguir:
app.on('message', async ({ send, activity }) => {
if(activity.Recipient.isTargeted) {
// Handle message event
}
});
teams.OnMessage(async (context, cancellationToken) => {
if (context.Activity.Recipient?.IsTargeted == true){
// Handle message event
}
});
@app.on_message
async def handle_message(ctx):
if getattr(ctx.activity.recipient, "is_targeted", False):
# Handle message event
Enviar uma mensagem direcionada
Todos os agentes no Teams são automaticamente qualificados para enviar mensagens direcionadas. Para enviar uma mensagem de destino, use withRecipient para especificar um único destinatário por sua ID e forneça um valor de true para o isTargeted argumento. O destinatário deve ser um membro do chat ou canal.
import { MessageActivity } from '@microsoft/teams.api';
app.on('message', async ({ send, activity }) => {
// Using withRecipient with isTargeted=true explicitly targets the specified recipient
await send(
new MessageActivity('This message is only visible to you!')
.withRecipient(activity.from, true)
);
});
app.OnMessage(async context =>
{
// Using WithRecipient with isTargeted=true explicitly targets the specified recipient
await context.Send(
new MessageActivity("This message is only visible to you!")
.WithRecipient(context.Activity.From, isTargeted: true)
);
});
from microsoft_teams.api import MessageActivity, MessageActivityInput
from microsoft_teams.apps import ActivityContext
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
# Using with_recipient with is_targeted=True explicitly targets the specified recipient
await ctx.send(
MessageActivityInput(text="This message is only visible to you!")
.with_recipient(ctx.activity.from_, is_targeted=True)
)
Observação
Se a tentativa de enviar uma mensagem direcionada resultar em um erro, considere enviar uma mensagem de chat 1:1 como fallback.
Integrar a visualização do prompt em uma mensagem direcionada
A visualização do prompt pode aparecer em respostas de agentes públicos e privados, mas o mecanismo de implementação é o mesmo em ambos os casos: o agente inclui targetedMessageInfo que faz referência à mensagem de destino original. A diferença é apenas quem pode ver a resposta depois que ela é enviada.
A Visualização de Prompt é automaticamente suportada em cenários reativos , como quando um agente responde à mensagem de destino de um usuário ou solicitação de comando de barra usando send() ou reply() por meio do SDK do Teams ou da API REST. Nesses casos, o SDK normalmente adiciona a targetedMessageInfo entidade automaticamente, vinculando a resposta à solicitação original do usuário.
Em cenários proativos , a resposta é enviada fora do turno de conversa original. Como resultado, o agente deve incluir explicitamente a targetedMessageInfo entidade e fornecer a ID da mensagem de destino antes de enviar a mensagem privada ou pública.
Isso garante que a resposta permaneça associada à solicitação original correta e permite que a Visualização do prompt exiba o prompt de usuário apropriado.
Para renderizar a visualização do prompt, inclua uma targetedMessageInfo entidade na atividade de resposta e defina seu messageId valor como a ID da mensagem de destino original, que o Teams usa para mostrar a solicitação original do usuário acima da resposta do agente, conforme mostrado neste exemplo:
if (isTargeted) {
response.addTargetedMessageInfo(targetedMessageId);
}
if (isTargeted)
{
response.AddTargetedMessageInfo(targetedMessageId);
}
if is_targeted:
response.add_targeted_message_info(activity.id)
Enviar respostas usando APIs REST
Se você estiver enviando respostas por meio de APIs REST, use a mesma targetedMessageInfo entidade no conteúdo da atividade.
POST {cloud}/v3/conversations/{conversationId}/activities?isTargetedActivity=true
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
JSON
{
"type": "message",
"from": {
"id": "28:c9e...",
"name": "Contoso"
},
"conversation": {
"id": "x:17I0...",
"name": "Convo1"
},
"recipient": {
"id": "29:1XJ...",
"name": "Megan Bowen"
},
"text": "My agent's reply",
"entities": [
{
"type": "targetedMessageInfo",
"messageId": "1772129782775"
}
]
}
Use isTargetedActivity=true para a resposta privada. Para uma repostagem pública, envie a mensagem normalmente, mas mantenha a mesma targetedMessageInfo entidade.
Para renderizar a visualização do prompt, inclua uma targetedMessageInfo entidade na atividade de resposta e defina seu messageId valor como a ID da mensagem de destino original para mostrar a solicitação original do usuário acima da resposta do agente, conforme mostrado neste exemplo:
"entities": [{
"type": "targetedMessageInfo",
"messageId": "xxxxxxxxxxxxx"
}]
Este exemplo adiciona uma targetedMessageInfo entidade type à matriz da entities atividade e faz referência à mensagem original do usuário por meio de seu messageId. Essa associação ativa a visualização do prompt e permite que a solicitação original apareça acima da resposta do agente.
Atualizar ou excluir uma mensagem direcionada
As mensagens direcionadas podem ser atualizadas e excluídas da mesma maneira que as mensagens padrão, com as seguintes limitações:
- A visibilidade de uma mensagem direcionada não pode ser alterada.
- As mensagens direcionadas expiram após 24 horas e são excluídas automaticamente dos clientes. A tentativa de modificar ou excluir uma mensagem expirada resulta em um erro.
Para obter mais informações sobre como atualizar ou excluir uma mensagem direcionada, consulte SDK do Teams.
Fluxo de trabalho de aprovação usando ações sugeridas
A aprovação do usuário é uma proteção fundamental em fluxos de trabalho de mensagens direcionadas. Como a resposta de um agente pode conter informações específicas do usuário, o consentimento explícito do usuário é necessário antes de compartilhá-la em uma conversa pública.
O agente pode responder de forma privada, com uma ação sugerida solicitando a aprovação do usuário para compartilhar sua resposta. Quando o usuário aprova, o agente reenvia a mensagem publicamente. A experiência de aprovação pode ser implementada por meio de superfícies de revisão interativas, como Cartões Adaptáveis ou ações sugeridas. Aqui está um fluxo de trabalho de aprovação de usuário recomendado:
- Receba a solicitação direcionada do usuário.
- Envie a resposta do agente em particular, incluindo uma visualização de prompt para contexto.
- Apresente opções de aprovação usando Ações Sugeridas ou um Cartão Adaptável.
- Publique a resposta à conversa somente depois que o usuário aprovar o compartilhamento.
As ações recomendadas podem incluir Aprovar, Rejeitar, Compartilhar e Atualizar.
Práticas recomendadas e diretrizes de design
A capacidade de usuários e agentes se comunicarem de forma privada com mensagens direcionadas é uma consideração fundamental em conversas em grupo. Os agentes devem sempre considerar a visibilidade das mensagens que recebem e usá-la para informar a geração de respostas, a visibilidade da resposta e se a solicitação original deve ser rastreada como parte do contexto da conversa.
Ao projetar interações de agente para conversas em grupo, escolher entre mensagens públicas e direcionadas em diferentes situações requer um julgamento cuidadoso:
- Uma solicitação direcionada a um agente deve resultar em uma resposta direcionada, a menos que o usuário ou a situação exija explicitamente uma resposta pública.
- As mensagens públicas devem ser usadas em situações puramente informativas e que não exijam contexto específico do usuário. Eles devem beneficiar todo o grupo e não devem conter nenhuma informação privada.
- Tome cuidado ao usar Cartões Adaptáveis em mensagens direcionadas. Embora a mensagem em si seja direcionada, as interações com um card ainda podem gerar atividades públicas que os usuários talvez não esperem.
- Use a visualização do prompt sempre que um agente responder a uma solicitação de usuário direcionada. Em comparação com as respostas citadas, isso ajuda os usuários a entender a relação entre o prompt original e a resposta do agente sem exigir que eles localizem a mensagem anterior.
Lidar com erros
Certifique-se de lidar com esses erros adequadamente em seu agente ou aplicativo.
Aqui está uma lista de códigos de erro, descrições de erro e ações do desenvolvedor para o SDK do Teams:
| Código de status | Código de erro | Descrição | Ação do desenvolvedor |
|---|---|---|---|
| 400 | Bad argument |
Ao criar, a carga é inválida porque o destinatário está ausente. | Chamada WithRecipient(account, isTargeted: true) com um objeto Account válido. |
| 400 | Bad argument |
Os dados do destinatário foram incluídos em uma operação de atualização ou exclusão, onde isso não é permitido. | Não passe um destinatário na atualização ou exclusão. |
| 400 | INVALID_TARGETED_MESSAGE_ID |
Em cenários de visualização de prompt, a ID da mensagem de destino é inválida. | No cenário de visualização de prompt, verifique se a ID da mensagem de destino está correta. |
| 403 | BotNotInConversationRoster |
O aplicativo de agente ou bot não é membro da conversa. | Certifique-se de que o bot esteja instalado na conversa antes de enviar mensagens direcionadas. |
| 404 | ActivityNotFoundInConversation |
A ID da mensagem não foi encontrada. A mensagem pode ter sido excluída ou expirado após 24 horas. | Certifique-se de que o agente envie uma nova mensagem direcionada ou aguarde a entrada do usuário, de acordo com a lógica de negócios. |
| 404 | TARGETED_MESSAGE_EXPIRED_OR_DELETED |
Em cenários de visualização de prompt, a mensagem referenciada foi excluída ou expirou após 24 horas. | Envie uma nova mensagem direcionada ou aguarde a entrada do usuário, com base na lógica de negócios. |
Mais detalhes sobre outros códigos de erro de mensagens podem ser encontrados aqui.
Exemplo de código
| Nome do exemplo | Descrição | .NET | TypeScript | Python |
|---|---|---|---|---|
| Mensagens direcionadas do agente | Este exemplo demonstra como usar mensagens direcionadas no Microsoft Teams. Mensagens direcionadas são mensagens privadas que aparecem em um canal ou chat em grupo, mas são visíveis apenas para um usuário específico. O exemplo implementa um agente de lembrete em que todas as respostas do agente — confirmações, entregas de lembretes, listas de lembretes ativas e confirmações de adiamento — são enviadas como mensagens direcionadas. | View | View | View |
Conteúdo relacionado
Colaborar conosco no GitHub
A fonte deste conteúdo pode ser encontrada no GitHub, onde você também pode criar e revisar problemas e solicitações de pull. Para obter mais informações, confira o nosso guia para colaboradores.