Mensagens proativas

Uma mensagem proativa é qualquer mensagem enviada por um agente que não está em resposta a uma solicitação de um usuário. Esta mensagem pode incluir conteúdo como:

Mensagem de boas-vindas
Notificações
Mensagens agendadas

Para enviar uma mensagem proativa a um usuário, um bate-papo em grupo ou uma equipe, seu agente deve ter o acesso necessário para enviar a mensagem. Para um chat em grupo ou equipe, o aplicativo que contém seu agente deve ser instalado primeiro nesse local.

Você pode instalar proativamente seu aplicativo usando o Microsoft Graph em uma equipe, se necessário, ou usar uma política de aplicativo personalizada para instalar um aplicativo em suas equipes e para os usuários da organização. Para determinados cenários, você deve instalar proativamente seu aplicativo usando o Graph. Para que um usuário receba mensagens proativas, instale o aplicativo para o usuário ou torne-o parte de uma equipe na qual o aplicativo está instalado.

Enviar uma mensagem proativa é diferente de enviar uma mensagem normal. Mensagens proativas são enviadas via aplicativo. Send() fora de um manipulador de atividade. O SDK cria a conversa automaticamente quando você chama o aplicativo. Enviar(). Você precisa de um conversationId, o SDK resolve a URL do serviço automaticamente. Por exemplo, um novo bate-papo privado ou um novo tópico de conversa em um canal. Não é possível criar um novo chat em grupo ou um novo canal em uma equipe com mensagens proativas.

Para enviar uma mensagem proativa, siga estas etapas:

Obtenha a ID do usuário, a ID do usuário, a ID da equipe ou a ID do canal do Microsoft Entra, se necessário.
Crie a conversa, se necessário.
Obtenha a ID da conversa.
Envie a mensagem.

Os snippets de código na seção de exemplos são para criar uma conversa individual. Para obter links para exemplos de conversas individuais e mensagens de grupo ou canais, consulte exemplos de código. Para usar mensagens proativas com eficiência, consulte as práticas recomendadas para mensagens proativas.

Obter a ID de usuário, ID de usuário, ID de equipe ou ID de canal do Microsoft Entra

Você pode criar uma nova conversa com um usuário ou uma conversa em um canal e deve ter a ID correta. Você pode receber ou recuperar essa ID usando qualquer uma das seguintes maneiras:

Quando seu aplicativo é instalado em um contexto específico, você recebe uma onMembersAdded atividade.
Quando um novo usuário é adicionado a um contexto em que seu aplicativo está instalado, você recebe uma onMembersAdded atividade.
Cada evento que o agente recebe contém as informações necessárias, que você pode obter do contexto do agente (contexto da atividade).
Você pode recuperar a lista de canais em uma equipe onde seu aplicativo está instalado.
Você pode recuperar a lista de membros de uma equipe onde seu aplicativo está instalado.

Independentemente de como você obtém as informações, armazene o tenantId e, em seguida, armazene o userId, ou channelId para criar uma nova conversa. Você também pode usar a teamId para criar um novo tópico de conversa no canal geral ou padrão de uma equipe. Certifique-se de que o agente esteja instalado na equipe antes de enviar uma mensagem proativa para um canal.

O aadObjectId é exclusivo para o usuário e pode ser recuperado usando a API do graph para criar uma nova conversa no chat pessoal. Certifique-se de que o agente esteja instalado no escopo pessoal antes de enviar uma mensagem proativa. Se o agente não estiver instalado em um escopo pessoal ao enviar uma mensagem proativa usando o aadObjectId, o agente retornará um 403 erro com ForbiddenOperationException mensagem.
O userId é exclusivo para sua ID de agente e para um usuário específico. Você não pode reutilizar o userId entre agentes.
O channelId é global.

Crie a conversa, depois de ter as informações do usuário ou do canal.

Observação

O envio de mensagens proativas usando aadObjectId é suportado apenas no escopo pessoal.

Criar a conversa

Você pode criar a conversa se ela não existir ou se você não souber o conversationIddomínio . Crie a conversa apenas uma vez e armazene o resultado conversationId para futuras mensagens proativas.

Para criar a conversa, você precisa de um aadObjectId ou userId, tenantId, e serviceUrl.

Observação

Para criar a conversa, passe o aadObjetId valor no Id parâmetro.

Para serviceUrl, use o valor de uma atividade de entrada que dispara o fluxo ou uma das URLs de serviço global. Se não serviceUrl estiver disponível em uma atividade de entrada que dispara o cenário proativo, use os seguintes pontos de extremidade de URL globais:

Público: https://smba.trafficmanager.net/teams/
GCC: https://smba.infra.gcc.teams.microsoft.com/teams
GCC Alta: https://smba.infra.gov.teams.microsoft.us/teams
DoD: https://smba.infra.dod.teams.microsoft.us/teams

Aviso

Essas URLs são apenas para mensagens proativas. Evite codificá-los. Em vez disso, use serviceUrl a partir da referência de atividade ou conversa de entrada. Se não estiver disponível, use URLs globais com base na região e na nuvem.
Para qualquer resposta a mensagens, use serviceURL a partir da solicitação de entrada. Para obter mais informações, consulte a propriedade Activity.ServiceUrl .

Você pode obter a conversa quando o aplicativo é instalado pela primeira vez. Depois que a conversa for criada, obtenha o ID da conversa. O conversationId está disponível nos eventos de atualização da conversa.

O ID da conversa é exclusivo para cada agente em um canal específico, mesmo em um ambiente multilocatário. Essa ID garante que as mensagens do agente sejam direcionadas para o canal apropriado e não interrompa com outros agentes ou canais da mesma organização ou de organizações diferentes.

Se você não tiver o , poderá instalar proativamente seu aplicativo usando o conversationIdGraph para obter o conversationId.

Obter a ID da conversa

Use o objeto conversationReference ou a conversationId e tenantId para enviar a mensagem. É possível obter essa ID criando a conversa ou armazenando-a de qualquer atividade enviada a você desse contexto. Armazene essa ID para referência.

Depois de obter as informações de endereço apropriadas, é possível enviar sua mensagem.

Enviar a mensagem

Agora que você tem as informações de endereço corretas, pode enviar sua mensagem. Se você estiver usando o SDK, deverá usar o app.Send() método e o conversationId para fazer uma chamada direta à API. Para enviar sua mensagem, defina o conversationParameters. Consulte a seção de exemplos ou use um dos exemplos listados na seção exemplos de código .

Para enviar proativamente uma mensagem como uma resposta a um thread em um canal, use app.Reply() com a ID da conversa e a ID da mensagem raiz do thread.

Observação

O Teams não é compatível com o envio de mensagens proativas usando email ou nome UPN.

Agora que você enviou a mensagem proativa, deve seguir essas práticas recomendadas ao enviar mensagens proativas para uma melhor troca de informações entre os usuários e o agente.

Entenda quem bloqueou, silenciou ou desinstalou um agente

Como desenvolvedor, você pode criar um relatório para entender quais usuários em sua organização bloquearam, silenciaram ou desinstalaram um agente. Essas informações podem ajudar os administradores da sua organização a transmitir mensagens de toda a organização ou impulsionar o uso de aplicativos.

Usando o Teams, você pode enviar uma mensagem proativa ao agente para verificar se um usuário bloqueou ou desinstalou um agente. Se o agente estiver bloqueado ou desinstalado, o Teams retornará um código de 403 resposta com um subCode: MessageWritesBlocked. Essa resposta indica que a mensagem enviada pelo agente não é entregue ao usuário.

O código de resposta é enviado por usuário e inclui a identidade do usuário. Você pode compilar os códigos de resposta para cada usuário juntamente com sua identidade para criar um relatório de todos os usuários que bloquearam o agente.

A seguinte amostra de código é um exemplo de código de resposta 403:

HTTP/1.1 403 Forbidden
Cache-Control: no-store, must-revalidate, no-cache
Pragma: no-cache
Content-Length: 196
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0
ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0
Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\n}"}

Práticas recomendadas para mensagens proativas

Enviar mensagens proativas aos usuários é uma maneira eficaz de se comunicar com seus usuários. No entanto, da perspectiva do usuário, a mensagem aparece espontaneamente. Se houver uma mensagem de boas-vindas, ela marcará a primeira interação da pessoa com seu aplicativo. É importante usar essa funcionalidade e fornecer as informações completas ao usuário para entender a finalidade dessa mensagem.

Mensagem de boas-vindas

Quando as mensagens proativas são usadas para enviar uma mensagem de boas-vindas a um usuário, não há contexto para o motivo pelo qual o usuário recebe a mensagem. Além disso, essa é a primeira interação do usuário com seu aplicativo. É uma oportunidade para criar uma boa primeira impressão. Uma boa experiência do usuário garante uma melhor adoção do aplicativo. Mensagens de boas-vindas ruins podem levar os usuários a bloquear seu aplicativo. Escreva uma mensagem de boas-vindas clara e repita a mensagem de boas-vindas se ela não estiver surtindo o efeito desejado.

Uma boa mensagem de boas-vindas pode incluir as seguintes informações:

Motivo da mensagem - Deve ficar claro para o usuário por que ele está recebendo a mensagem. Se o seu agente foi instalado em um canal e você enviou uma mensagem de boas-vindas a todos os usuários, informe-os em qual canal ele foi instalado e quem o instalou.
Sua oferta: os usuários devem ser capazes de identificar o que podem fazer com seu aplicativo e que valor você pode agregar a eles.
Próximas etapas - Os usuários devem entender as próximas etapas. Por exemplo, convide os usuários para experimentar um comando ou interagir com seu aplicativo.

Mensagens de notificação

Para enviar notificações usando mensagens proativas, verifique se os usuários têm um caminho claro para executar ações comuns com base em sua notificação. Se forem necessárias ações do usuário em um aplicativo de guia, use as notificações do feed de atividades em vez de um agente. Verifique se os usuários têm uma compreensão clara do motivo pelo qual receberam uma notificação. Boas mensagens de notificação incluem os seguintes itens:

O que está acontecendo? Uma indicação clara do que aconteceu para causar a notificação.
Qual foi o resultado? Deve ser claro, qual item está atualizado para receber a notificação.
Quem ou o que a disparou? Quem ou o que tomou a ação que fez com que a notificação fosse enviada.
O que os usuários podem fazer em resposta? Facilite para que seus usuários realizem ações com base nas suas notificações.
Como os usuários podem optar por sair? Você deve fornecer um caminho para que os usuários recusem mais notificações.

Para enviar mensagens para um grande grupo de usuários, por exemplo, para sua organização, instale proativamente seu aplicativo usando o Graph.

Para atualizar ou excluir uma mensagem proativa enviada por um agente somente de notificação:

Acompanhe as mensagens enviadas armazenando suas IDs de mensagem ou referências de conversa ao enviar a mensagem proativa.
Uso context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity) de métodos OR context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId) para atualizar ou excluir a mensagem original.

Mensagens agendadas

Ao usar mensagens proativas para enviar mensagens agendadas aos usuários, verifique se o fuso horário está atualizado com o fuso horário deles. Isso garante que as mensagens sejam entregues aos usuários no momento relevante. As mensagens de agendamento incluem:

Por que o usuário está recebendo a mensagem? Facilite para que seus usuários entendam o motivo pelo qual estão recebendo a mensagem.
O que o usuário pode fazer a seguir? Os usuários podem executar as ações necessárias com base no conteúdo da mensagem.

Instalar proativamente seu aplicativo usando o Graph

Você pode usar a API do Graph para instalar proativamente seu aplicativo para seus usuários. Armazene em cache os valores necessários do evento conversationUpdate que seu aplicativo recebe após a instalação.

Você só pode instalar aplicativos que estão em seu catálogo de aplicativos organizacional ou na Microsoft Teams Store.

Confira instalar aplicativos para usuários na documentação do Graph e instalação e sistema de mensagens do agente proativo no Teams com o Graph.

Exemplos

Certifique-se de autenticar e ter um token de portador antes de criar uma nova conversa usando a API REST. A seguir estão a API REST para criar uma conversa em diferentes contextos:

API REST para criar uma conversa em um chat individual.
API REST para criar uma conversa em um canal.
API REST para atualizar a mensagem na conversa: Para atualizar uma atividade existente em uma conversa, inclua o conversationId e o activityId no endpoint da solicitação. Para concluir esse cenário, você deve armazenar em cache a ID da atividade retornada pela pós-chamada original.
```
PUT {Service URL of your agent}/v3/conversations/{conversationId}/activities/{activityId}
```
```
{
    "type": "message",
    "text": "This message has been updated"
}
```
Para atualizar uma atividade existente em uma conversa, inclua o conversationId e activityId no ponto de extremidade de solicitação. Para concluir esse cenário, você deve armazenar em cache o activity ID retornado pela chamada de postagem original. Se a chamada for bem-sucedida, a API retornará o seguinte objeto de resposta.
```
{
    "id": "{{activityID}}"
}
```

Exemplos

O código a seguir mostra como enviar mensagens proativas usando o SDK do Teams (Biblioteca de IA do Teams):

// Save the conversation ID and schedule a proactive reminder on install
teams.OnInstall(async (context, cancellationToken) =>
{
    context.Storage.Set(context.Activity.From.AadObjectId!, context.Activity.Conversation.Id);
    await context.Send("Hi! I am going to remind you to say something to me soon!", cancellationToken);
    notificationQueue.AddReminder(context.Activity.From.AadObjectId!, Notifications.SendProactive, 10_000);
});
 
// Send proactive message using stored conversation ID
public static class Notifications
{
    public static async Task SendProactive(string userId)
    {
        var conversationId = (string?)storage.Get(userId);
        if (conversationId is null) return;
        await app.Send(conversationId, "Hey! It's been a while. How are you?");
    }
}


// This would be some persistent storage
const myConversationIdStorage = new Map<string, string>();
 
// Save the conversation ID on app install
app.on('install.add', async ({ activity, send }) => {
  myConversationIdStorage.set(activity.from.aadObjectId!, activity.conversation.id);
  await send('Hi! I am going to remind you to say something to me soon!');
  notificationQueue.addReminder(activity.from.aadObjectId!, sendProactiveNotification, 10_000);
});
 
// Send proactive message using stored conversation ID
const sendProactiveNotification = async (userId: string) => {
  const conversationId = myConversationIdStorage.get(userId);
  if (!conversationId) {
    return;
  }
  const activity = new MessageActivity('Hey! It\'s been a while. How are you?');
  await app.send(conversationId, activity);
};

# This would be some persistent storage
storage = dict[str, str]()

# Save the conversation_id when the app is installed
@app.on_install_add
async def handle_install_add(ctx: ActivityContext[InstalledActivity]):
    storage[ctx.activity.from_.aad_object_id] = ctx.activity.conversation.id
    await ctx.send("Hi! I am going to remind you to say something to me soon!")
    notification_queue.add_reminder(ctx.activity.from_.aad_object_id, send_proactive_notification, 60000)

# Send proactive message using stored conversation ID
async def send_proactive_notification(user_id: str):
    conversation_id = storage.get(user_id, "")
    if not conversation_id:
        return
    activity = MessageActivityInput(text="Hey! It's been a while. How are you?")
    await app.send(conversation_id, activity)

POST /v3/conversations
{
  "bot": {
    "id": "28:10j12ou0d812-2o1098-c1mjojzldxcj-1098028n ",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

É preciso fornecer a ID do usuário e a ID do locatário. Se a chamada for bem-sucedida, a API retornará o seguinte objeto de resposta:

{
  "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"
}

Exemplos de código

A tabela a seguir fornece exemplos de código que incorporam o fluxo de conversa básico e mensagens proativas em um aplicativo do Teams usando o SDK do Teams:

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Noções básicas de conversa do Teams	Este aplicativo de exemplo mostra como usar diferentes eventos de conversa de agente disponíveis no SDK do Teams v2 para escopo pessoal e de equipes.	View	View	View	View
Mensagem Proativa do Bot	Este exemplo mostra como capturar e armazenar uma ID de conversa de uma atividade de instalação e usá-la para enviar mensagens proativas imediatas e atrasadas a um usuário.	View	View	View	NA

Próximas etapas

Formatar mensagens do agente

Confira também

Conversas de chat de canal e grupo com um agente

Comentários

Esta página foi útil?

Last updated on 2026-08-20

Mensagens proativas

Obter a ID de usuário, ID de usuário, ID de equipe ou ID de canal do Microsoft Entra

Criar a conversa

Obter a ID da conversa

Enviar a mensagem

Entenda quem bloqueou, silenciou ou desinstalou um agente

Práticas recomendadas para mensagens proativas

Mensagem de boas-vindas

Mensagens de notificação

Mensagens agendadas

Instalar proativamente seu aplicativo usando o Graph

Exemplos

Exemplos

Exemplos de código

Próximas etapas

Confira também

Comentários

Recursos adicionais