Integrar seu próprio canal personalizado usando o Direct Line

Com o Dynamics 365 Contact Center, você pode implementar um conector para integrar canais de mensagens personalizados usando a API de Linha Direta 3.0, que faz parte do SDK do .NET. O código de exemplo completo ilustra como você pode criar seu próprio conector. Para saber mais sobre a API Direct Line 3.0, consulte Principais conceitos na API Direct Line 3.0.

Este artigo explica como um canal está conectado ao Microsoft Direct Line Bot Framework, que é anexado internamente ao Dynamics 365 Contact Center. A seção a seguir inclui trechos de código que usam a API 3.0 do Direct Line para criar um cliente do Direct Line e a IChannelAdapter interface para criar um conector de exemplo.

Componentes

Serviço da API Webhook do adaptador

Quando o usuário insere uma mensagem, a API do adaptador é chamada a partir do canal. Ele processa a solicitação de entrada e envia um status de êxito ou falha como resposta. O serviço de API do adaptador deve implementar a IChannelAdapter interface e envia a solicitação de entrada para o respectivo adaptador de canal para processar a solicitação.

/// <summary>
/// Accept an incoming web-hook request from MessageBird Channel
/// </summary>
/// <param name="requestPayload">Inbound request Object</param>
/// <returns>Executes the result operation of the action method asynchronously.</returns>
    [HttpPost("postactivityasync")]
    public async Task<IActionResult> PostActivityAsync(JToken requestPayload)
    {
        if (requestPayload == null)
        {
            return BadRequest("Request payload is invalid.");
        }

        try
        {
            await _messageBirdAdapter.ProcessInboundActivitiesAsync(requestPayload, Request).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            _logger.LogError($"postactivityasync: {ex}");
            return StatusCode(500, "An error occured while handling your request.");
        }

        return StatusCode(200);
    }

Adaptadores de canal

O adaptador de canal processa as atividades de entrada e saída e deve implementar a IAdapterBuilder interface.

Processar atividades de entrada

O adaptador de canal executa as seguintes atividades de entrada:

1. Valide a assinatura de solicitação de mensagem de entrada.

A solicitação de entrada do canal é validada com base na chave de assinatura. Se a solicitação for inválida, uma mensagem de exceção de "assinatura inválida" será lançada. Se a solicitação for válida, ela procede da seguinte forma:

  /// <summary>
  /// Validate Message Bird Request
  /// </summary>
  /// <param name="content">Request Content</param>
  /// <param name="request">HTTP Request</param>
  /// <param name="messageBirdSigningKey">Message Bird Signing Key</param>
  /// <returns>True if there request is valid, false if there aren't.</returns>
  public static bool ValidateMessageBirdRequest(string content, HttpRequest request, string messageBirdSigningKey)
  {
      if (string.IsNullOrWhiteSpace(messageBirdSigningKey))
      {
          throw new ArgumentNullException(nameof(messageBirdSigningKey));
      }
      if (request == null)
      {
          throw new ArgumentNullException(nameof(request));
      }
      if (string.IsNullOrWhiteSpace(content))
      {
          throw new ArgumentNullException(nameof(content));
      }
      var messageBirdRequest = new MessageBirdRequest(
          request.Headers?["Messagebird-Request-Timestamp"],
          request.QueryString.Value?.Equals("?",
              StringComparison.CurrentCulture) != null
              ? string.Empty
              : request.QueryString.Value,
          GetBytes(content));

      var messageBirdRequestSigner = new MessageBirdRequestSigner(GetBytes(messageBirdSigningKey));
      string expectedSignature = request.Headers?["Messagebird-Signature"];
      return messageBirdRequestSigner.IsMatch(expectedSignature, messageBirdRequest);
  }

2. Converta a solicitação de entrada em uma atividade de bot.

O conteúdo da solicitação de entrada é convertido em uma atividade que o Bot Framework pode entender.

Esse objeto Activity inclui os seguintes atributos:

  /// <summary>
  /// Build Bot Activity type from the inbound MessageBird request payload<see cref="Activity"/>
  /// </summary>
  /// <param name = "messagePayload"> Message Bird Activity Payload</param>
  /// <returns>Direct Line Activity</returns>
  public static Activity PayloadToActivity(MessageBirdRequestModel messagePayload)
  {
  if (messagePayload == null)
  {
      throw new ArgumentNullException(nameof(messagePayload));
  }
  if (messagePayload.Message?.Direction == ConversationMessageDirection.Sent ||
  messagePayload.Type == ConversationWebhookMessageType.MessageUpdated)
  {
      return null;
  }
  var channelData = new ActivityExtension
  {
      ChannelType = ChannelType.MessageBird,
      // Add Conversation Context in below dictionary object. Please refer the document for more information.
      ConversationContext = new Dictionary<string, string>(),
      // Add Customer Context in below dictionary object. Please refer the document for more information.
      CustomerContext = new Dictionary<string, string>()
  };
  var activity = new Activity
      {
          From = new ChannelAccount(messagePayload.Message?.From, messagePayload.Contact?.DisplayName),
          Text = messagePayload.Message?.Content?.Text,
          Type = ActivityTypes.Message,
          Id = messagePayload.Message?.ChannelId,
          ServiceUrl = Constant.DirectLineBotServiceUrl,
          ChannelData = channelData
      };

      return activity;
  }

O conteúdo JSON de exemplo é o seguinte:

{
    "type": "message",
    "id": "bf3cc9a2f5de...",    
    "serviceUrl": https://directline.botframework.com/,
    "channelId": "directline",
    "from": {
        "id": "1234abcd",// userid which uniquely identify the user
        "name": "customer name" // customer name as First Name <space> Last Name
    },
    "text": "Hi,how are you today.",
    "channeldata":{
        "channeltype":"messageBird",
        "conversationcontext ":{ // this holds context variables defined in Workstream
            "ProductName" : "XBox",
            "Issue":"Installation"
        },
        "customercontext":{            
            "email":email@email.com,
            "phonenumber":"1234567890"           
        }
    }
}

3. Envie a atividade para o processador de retransmissão de mensagens.

Depois de criar o conteúdo da atividade, ele chama o método PostActivityAsync do processador de retransmissão de mensagens para enviar a atividade para o Direct Line. O adaptador de canal também deve transmitir o manipulador de eventos, que o processador de retransmissão invoca quando receber uma mensagem de saída do Dynamics 365 Contact Center por meio do Direct Line.

Processar atividades de saída

O processador de retransmissão chama o manipulador de eventos para enviar atividades de saída para o respectivo adaptador de canal e, em seguida, o adaptador processa as atividades de saída. O adaptador de canal executa as seguintes atividades de saída:

1. Converta atividades de saída no modelo de resposta do canal.

As atividades da Linha Direta são convertidas em um modelo de resposta específico para o canal.

  /// <summary>
  /// Creates MessageBird response object from a Bot Framework <see cref="Activity"/>.
  /// </summary>
  /// <param name="activities">The outbound activities.</param>
  /// <param name="replyToId">Reply Id of Message Bird user.</param>
  /// <returns>List of MessageBird Responses.</returns>
  public static List<MessageBirdResponseModel> ActivityToMessageBird(IList<Activity> activities, string replyToId)
  {
      if (string.IsNullOrWhiteSpace(replyToId))
      {
          throw new ArgumentNullException(nameof(replyToId));
      }

      if (activities == null)
      {
          throw new ArgumentNullException(nameof(activities));
      }

      return activities.Select(activity => new MessageBirdResponseModel
      {
          To = replyToId,
          From = activity.ChannelId,
          Type = "text",
          Content = new Content
          {
              Text = activity.Text
          }
      }).ToList();
  }

2. Envie respostas por meio da API REST do canal.

O adaptador de canal chama a API REST para enviar uma resposta de saída ao canal, que é enviada ao usuário.

  /// <summary>
  /// Send Outbound Messages to Message Bird
  /// </summary>
  /// <param name="messageBirdResponses">Message Bird Response object</param>
  /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
  public async Task SendMessagesToMessageBird(IList<MessageBirdResponseModel> messageBirdResponses)
  {
      if (messageBirdResponses == null)
      {
          throw new ArgumentNullException(nameof(messageBirdResponses));
      }

      foreach (var messageBirdResponse in messageBirdResponses)
      {
          using (var request = new HttpRequestMessage(HttpMethod.Post, $"{MessageBirdDefaultApi}/send"))
          {
              var content = JsonConvert.SerializeObject(messageBirdResponse);
              request.Content = new StringContent(content, Encoding.UTF8, "application/json");
              await _httpClient.SendAsync(request).ConfigureAwait(false);
          }
      }
  }

Processador de retransmissão de mensagens

O processador de retransmissão de mensagens recebe a atividade de entrada do adaptador de canal e faz a validação do modelo de atividade. Antes de enviar esta atividade para o Direct Line, o processador de retransmissão verifica se a conversa está ativa para a atividade específica

Para verificar se a conversação está ativa, o processador de retransmissão mantém uma coleção de conversações ativas em um dicionário. Este dicionário utiliza User ID como chave, que identifica o usuário de forma única, e Value como um objeto da seguinte classe:

 /// <summary>
/// Direct Line Conversation to store as an Active Conversation
/// </summary>
public class DirectLineConversation
{
    /// <summary>
    /// .NET SDK Client to connect to Direct Line Bot
    /// </summary>
    public DirectLineClient DirectLineClient { get; set; }

    /// <summary>
    /// Direct Line response after start a new conversation
    /// </summary>
    public Conversation Conversation { get; set; }

    /// <summary>
    /// Watermark to guarantee that no messages are lost
    /// </summary>
    public string WaterMark { get; set; }
}

Se a conversa não estiver ativa para a atividade recebida pelo processador de retransmissão, ele executará as seguintes etapas:

1. Inicia uma conversa com o Direct Line e armazena o objeto de conversa enviado pelo Direct Line em relação à ID do usuário no dicionário.

 /// <summary>
 /// Initiate Conversation with Direct Line Bot
 /// </summary>
 /// <param name="inboundActivity">Inbound message from Aggregator/Channel</param>
 /// <param name="adapterCallBackHandler">Call Back to send activities to Messaging API</param>
 /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
 private async Task InitiateConversation(Activity inboundActivity, EventHandler<IList<Activity>> adapterCallBackHandler)
 {
     var directLineConversation = new DirectLineConversation
     {
         DirectLineClient = new DirectLineClient(_relayProcessorConfiguration.Value.DirectLineSecret)
     };
     // Start a conversation with Direct Line Bot
     directLineConversation.Conversation = await directLineConversation.DirectLineClient.Conversations.
         StartConversationAsync().ConfigureAwait(false);

     await directLineConversation.DirectLineClient.Conversations.
         StartConversationAsync().ConfigureAwait(false);
     if (directLineConversation.Conversation == null)
     {
         throw new Exception(
             "An error occurred while starting the Conversation with direct line. Please validate the direct line secret in the configuration file.");
     }

     // Adding the Direct Line Conversation object to the lookup dictionary and starting a thread to poll the activities from the direct line bot.
     if (ActiveConversationCache.ActiveConversations.TryAdd(inboundActivity.From.Id, directLineConversation))
     {
         // Starts a new thread to poll the activities from Direct Line Bot
         new Thread(async () => await PollActivitiesFromBotAsync(
             directLineConversation.Conversation.ConversationId, inboundActivity, adapterCallBackHandler).ConfigureAwait(false))
         .Start();
     }
 }

2. Inicia um novo thread para sondar as atividades de saída do bot Direct Line com base no intervalo de sondagem configurado no arquivo de configuração. O thread de sondagem fica ativo até que o fim da atividade de conversa seja recebido do Direct Line.

/// <summary>
/// Polling the activities from BOT for the active conversation
/// </summary>
/// <param name="conversationId">Direct Line Conversation Id</param>
/// <param name="inboundActivity">Inbound Activity from Channel/Aggregator</param>
/// <param name="lineActivitiesReceived">Call Back to send activities to Messaging API</param>
/// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
private async Task PollActivitiesFromBotAsync(string conversationId, Activity inboundActivity, EventHandler<IList<Activity>> lineActivitiesReceived)
{
    if (!int.TryParse(_relayProcessorConfiguration.Value.PollingIntervalInMilliseconds, out var pollingInterval))
    {
        throw new FormatException($"Invalid Configuration value of PollingIntervalInMilliseconds: {_relayProcessorConfiguration.Value.PollingIntervalInMilliseconds}");
    }
    if (!ActiveConversationCache.ActiveConversations.TryGetValue(inboundActivity.From.Id,
        out var conversationContext))
    {
        throw new KeyNotFoundException($"No active conversation found for {inboundActivity.From.Id}");
    }
    while (true)
    {
        var watermark = conversationContext.WaterMark;
        // Retrieve the activity set from the bot.
        var activitySet = await conversationContext.DirectLineClient.Conversations.
            GetActivitiesAsync(conversationId, watermark).ConfigureAwait(false);
        // Set the watermark to the message received
        watermark = activitySet?.Watermark;

        // Extract the activities sent from our bot.
        if (activitySet != null)
        {
            var activities = (from activity in activitySet.Activities
                              where activity.From.Id == _relayProcessorConfiguration.Value.BotHandle
                              select activity).ToList();
            if (activities.Count > 0)
            {
                SendReplyActivity(activities, inboundActivity, lineActivitiesReceived);
            }
            // Update Watermark
            ActiveConversationCache.ActiveConversations[inboundActivity.From.Id].WaterMark = watermark;
            if (activities.Exists(a => a.Type.Equals("endOfConversation", StringComparison.InvariantCulture)))
            {
                if (ActiveConversationCache.ActiveConversations.TryRemove(inboundActivity.From.Id, out _))
                {
                    Thread.CurrentThread.Abort();
                }
            }
        }
        await Task.Delay(TimeSpan.FromMilliseconds(pollingInterval)).ConfigureAwait(false);
    }
}

Enviar a atividade para a Linha Direta

 /// <summary>
 /// Send the activity to the bot using Direct Line client
 /// </summary>
 /// <param name="inboundActivity">Inbound message from Aggregator/Channel</param>
 /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
 private static async Task SendActivityToBotAsync(Activity inboundActivity)
 {
     if (!ActiveConversationCache.ActiveConversations.TryGetValue(inboundActivity.From.Id,
         out var conversationContext))
     {
         throw new KeyNotFoundException($"No active conversation found for {inboundActivity.From.Id}");
     }
     await conversationContext.DirectLineClient.Conversations.PostActivityAsync(
         conversationContext.Conversation.ConversationId, inboundActivity).ConfigureAwait(false);
 }

Se a conversação estiver ativa para a atividade recebida pelo processador de retransmissão, ela enviará a atividade para o processador de retransmissão de mensagens.

Encerrar uma conversa

Para encerrar a conversa, consulte Encerrar uma conversa no Direct Line.

Formatos de markdown em canais personalizados

Você pode enviar e receber mensagens formatadas com Markdown em canais de mensagens personalizadas usando a Direct Line API 3.0. Entender como o formato de markdown é transmitido pelo canal e conhecer os detalhes do formato ajuda você a atualizar o estilo e as tags HTML em sua própria interface de usuário.

No canal Direct Line, quando um representante do serviço de atendimento ao consumidor (representante do serviço ou representante) envia (saída) uma mensagem formatada com Markdown para um bot de Direct Line, o bot recebe a mensagem em determinado formato. Agora, se um bot receber (entrada) uma mensagem formatada de um cliente, ele deve ser capaz de interpretar corretamente a mensagem que está formatada com markdown. Como desenvolvedor, você precisa usar o markdown de forma adequada para que a mensagem seja formatada corretamente para seus representantes do serviço e clientes.

Saiba mais sobre formatos de markdown em Formatos de markdown para mensagens de chat.

Próximas etapas

Suporte para chat ao vivo e canais assíncronos

Informações relacionadas

Configurar canal de mensagens personalizadas
Referência da API MessageBird
Melhores práticas para configurar bots