Usar reações de emoji no chat do Teams

No chat do Teams, as reações são marcadores de emoji leves que os participantes podem anexar às mensagens de qualquer pessoa. Os agentes podem usar reações para reconhecer mensagens, exibir o status do fluxo de trabalho e apresentar outras informações sem interromper o fluxo da conversa. Os agentes também podem ouvir e responder às reações.

Adicionar e remover reações em mensagens

Assim como os usuários, os agentes podem anexar uma ou mais reações diferentes a qualquer mensagem em uma conversa e podem remover reações após adicioná-las. Tanto os usuários quanto os agentes só podem remover suas próprias reações, não reações colocadas por outras pessoas.

Para adicionar e remover reações de mensagens, use a AddAsync parte e DeleteAsync métodos no ReactionClient, do cliente da API do Teams.

O exemplo a seguir ilustra como adicionar uma reação a uma mensagem recebida e, em seguida, removê-la.

teams.OnMessage(async (context, cancellationToken) =>
{
    // First, add a reaction
    await context.Api.Conversations.Reactions.AddAsync(
        context.Activity.Conversation.Id,
        context.Activity.Id,
        new ReactionType("1f44b_wavinghand"),
        cancellationToken
    );

    // Wait a bit, then remove it
    await Task.Delay(2000, cancellationToken);
    await context.Api.Conversations.Reactions.DeleteAsync(
        context.Activity.Conversation.Id,
        context.Activity.Id,
        new ReactionType("1f44b_wavinghand"),
        cancellationToken
    );
});

Adicionar ou remover uma reação requer uma referência a uma mensagem e uma cadeia de caracteres de ID de reação que identifique exclusivamente o emoji a ser usado. Consulte a Referência de reações do Teams para obter uma lista completa de emojis disponíveis, incluindo variantes de tom de pele. Além disso, a ReactionTypes classe estática expõe constantes nomeadas para algumas das IDs de reação mais comumente usadas.

Para adicionar e remover reações de mensagens, use a add parte e delete métodos no ReactionClient, do cliente da API do Teams.

O exemplo a seguir ilustra como adicionar uma reação a uma mensagem recebida e, em seguida, removê-la.

app.on('message', async ({ activity, api }) => {
// First, add a reaction
  await api.reactions.add(activity.conversation.id, activity.id, '1f44b_wavinghand');

  // Wait a bit, then remove it
  await new Promise((resolve) => setTimeout(resolve, 2000));
  await api.reactions.delete(activity.conversation.id, activity.id, '1f44b_wavinghand');
});

Adicionar ou remover uma reação requer uma referência a uma mensagem e uma cadeia de caracteres de ID de reação que identifique exclusivamente o emoji a ser usado. Consulte a Referência de reações do Teams para obter uma lista completa de emojis disponíveis, incluindo variantes de tom de pele. Além disso, o SDK do Teams inclui constantes nomeadas para algumas das IDs de reação mais usadas.

Para adicionar e remover reações de mensagens, use a add parte e delete métodos no ReactionClient, do cliente da API do Teams.

O exemplo a seguir ilustra como adicionar uma reação a uma mensagem recebida e, em seguida, removê-la.

import asyncio

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # First, add a reaction
    await ctx.api.reactions.add(
        ctx.activity.conversation.id,
        ctx.activity.id,
        '1f44b_wavinghand'
    )

    # Wait a bit, then remove it
    await asyncio.sleep(2)
    await ctx.api.reactions.delete(
        ctx.activity.conversation.id,
        ctx.activity.id,
        '1f44b_wavinghand'
    )

Adicionar ou remover uma reação requer uma referência a uma mensagem e uma cadeia de caracteres de ID de reação que identifique exclusivamente o emoji a ser usado. Consulte a Referência de reações do Teams para obter uma lista completa de emojis disponíveis, incluindo variantes de tom de pele. Além disso, o SDK do Teams inclui constantes nomeadas para algumas das IDs de reação mais usadas.

Para substituir uma reação em uma mensagem, faça chamadas separadas para remover a reação existente e adicionar uma nova.

Várias reações podem ser adicionadas a uma única mensagem, mas as operações adicionar e remover para uma determinada ID de reação são idempotentes: chamadas repetidas para adicionar ou remover uma reação específica de uma mensagem não têm efeito, mas não geram uma exceção.

Tratamento de exceções

A atividade de reação é uma fonte comum de exceções e sempre deve usar tratamento de exceção dedicado.

Em particular, exceções de limitação de taxa (429 Too Many Requests) podem ser mais comuns do que os desenvolvedores esperam. As adições e remoções de reação são limitadas a duas por segundo em todas as conversas das quais um agente participa. Lide com exceções de limitação de taxa usando o valor do Retry-After cabeçalho da resposta como parte de uma estratégia exponencial de retirada e repetição.

As operações de reação falham se a mensagem de destino for excluída ou o agente for removido da conversa e não devem ser repetidas.

Escutar eventos de reação

Os agentes podem ouvir a atividade de reação nas conversas das quais fazem parte, manipulando o OnMessageReaction evento ou as atividades mais específicas OnMessageReactionAddedOnMessageReactionRemoved .

teams.OnMessageReactionAdded(async (context, cancellationToken) =>
{
    foreach (var reaction in context.Activity.ReactionsAdded ?? [])
    {
        Console.WriteLine($"User added reaction: {reaction.Type}");
    }
});

teams.OnMessageReactionRemoved(async (context, cancellationToken) =>
{
    foreach (var reaction in context.Activity.ReactionsRemoved ?? [])
    {
        Console.WriteLine($"User removed reaction: {reaction.Type}");
    }
});

Ao lidar com o evento, os agentes podem escutar a messageReaction atividade de reação nas conversas das quais fazem parte.

app.on('messageReaction', async ({ activity }) => {
  for (const reaction of activity.reactionsAdded ?? []) {
    console.log(`User added reaction: ${reaction.type}`);
  }

  for (const reaction of activity.reactionsRemoved ?? []) {
    console.log(`User removed reaction: ${reaction.type}`);
  }
});

Os agentes podem ouvir a atividade de reação nas conversas das quais fazem parte, lidando com o on_message_reaction evento.

@app.on_message_reaction
async def handle_reaction(ctx: ActivityContext[MessageReactionActivity]):
    for reaction in ctx.activity.reactions_added or []:
        print(f"User added reaction: {reaction.type}")

    for reaction in ctx.activity.reactions_removed or []:
        print(f"User removed reaction: {reaction.type}")

Práticas recomendadas e diretrizes de design

Tratamento de exceções: a atividade de reação é uma fonte comum de exceções. Sempre use o tratamento de exceções dedicado para operações de reação, especialmente para lidar com exceções de limitação de taxa. Para obter mais informações, consulte Tratamento de exceções.

Use reações com moderação e consistência: Agentes focados na produtividade devem evitar usar reações para adicionar personalidade. Os usuários geralmente esperam que agentes focados na produtividade usem reações para comunicar reconhecimento ou status, não sentimento. Use um pequeno conjunto de emojis inequívocos que não exijam um guia para serem compreendidos.

Reconhecendo solicitações: Os agentes devem ser consistentes e previsíveis em sua confirmação de comandos e solicitações. O reconhecimento imediato de mensagens com reações é eficaz em muitos cenários, mas pode ser excessivo se o agente responder rapidamente com uma mensagem de qualquer maneira, especialmente se o agente usar streaming de mensagens e indicadores de pensamento.

Reações como indicadores de status: as reações podem passar despercebidas pelos usuários, especialmente em conversas ativas. Atualizar (remover e adicionar) reações de status em uma mensagem é uma maneira eficaz de registrar resultados para referência histórica, mas é fácil perder quando usado para atualizações de status ao vivo. Use mensagens, incluindo mensagens direcionadas, para comunicar o status ao vivo e a conclusão de tarefas de execução mais longas.

Interpretando eventos de reação: as reações do usuário não são um indicador confiável ou consistente de intenção e não devem orientar o comportamento do agente. Use ações ou cartões sugeridos para apresentar interações claramente definidas. Implemente controles de comentários para fornecer aos usuários uma maneira inequívoca de fornecer comentários ao agente.

Confira também

  • Última atualização em