Publicar um copiloto a aplicativos móveis ou personalizados
Você pode conectar seu copiloto a um aplicativo personalizado para que os usuários do aplicativo possam interagir com o copiloto diretamente do aplicativo.
Na maioria dos casos, seu aplicativo personalizado é um aplicativo para dispositivo móvel baseado na Web ou aplicativo ou adaptador nativo para outros serviços exigidos por sua empresa.
Existem procedimentos diferentes para conectar ao seu aplicativo móvel, dependendo se ele é um aplicativo baseado na Web ou nativo.
A conexão do seu copiloto a um aplicativo baseado na Web é relativamente simples, pois envolve a cópia de um trecho de código no seu aplicativo. No entanto, aplicativos baseados na Web e aplicativos nativos ou personalizados ainda exigem considerável conhecimento de desenvolvedor para integrar totalmente o copiloto ao seu aplicativo. Os dois procedimentos são descritos neste artigo.
Pré-requisitos
- SDK do .NET Core versão 2.1.
- Pacote de NuGet Microsoft.Bot.Connector.DirectLine.
- Um copiloto criado no Copilot Studio que você deseja conectar ao seu aplicativo.
Conectar o copiloto a um aplicativo baseado na Web
No Copilot Studio, no menu de navegação em Configurações, selecione Canais.
Selecione o bloco Aplicativo móvel para abrir a janela de configuração.
Copie o código na seção Aplicativos baseados na Web e o forneça aos desenvolvedores do aplicativo para adicionar ao seu aplicativo baseado na Web.
Conecte seu copiloto a um aplicativo nativo ou personalizado
Dica
Embora esta seção descreva como se conectar a um aplicativo móvel, o mesmo processo pode ser aplicado a aplicativos personalizados ou nativos, como aplicativos IoT (Internet das Coisas).
Se seu objetivo é conectar-se aos canais do Serviço de Bot do Azure, além de seguir as instruções aqui, seus desenvolvedores podem aprender mais em Publicar um copiloto a canais do Serviço de Bot do Azure.
Importante
De acordo com as instruções nesta seção, seus desenvolvedores ou você precisam desenvolver um software. Elas são direcionadas a profissionais de TI experientes, como administradores ou desenvolvedores de TI que tenham um sólido entendimento de utilitários, IDEs e ferramentas para desenvolvedores.
Exemplos de códigos
Origem dos trechos de código usados neste documento:
Referências
As instruções neste documento fazem referência ao seguinte material de origem:
- API do Bot Framework Direct Line
- Autenticação da Direct Line
- Variáveis contextuais disponíveis na entrega
- Atividade do Microsoft Bot Framework
Recuperar os parâmetros do seu copiloto do Copilot Studio
Para se conectar ao copiloto criado, é necessário recuperar o nome e ponto de extremidade de token do copiloto para identificá-lo.
Copie o nome do seu copiloto no Copilot Studio.
No menu de navegação, em Configurações, selecione Canais.
Selecione Aplicativo móvel.
Ao lado de Ponto de Extremidade do Token, selecione Copiar. Você precisa este ponto de extremidade para a etapa Obter token da Direct Line.
Obter token da Direct Line
Para iniciar uma conversa com o copiloto, você precisa de um token da Direct Line. Esse token pode ser obtido fazendo uma solicitação GET ao ponto de extremidade indicado na tela do Copilot Studio. Esse token deve então ser usado como cabeçalho para chamadas subsequentes à API do directline.
Exemplo:
GET <BOT TOKEN ENDPOINT>
Se a solicitação for bem-sucedida, um token do Direct Line, hora de expiração e conversationId serão retornados para o copiloto solicitado. Exemplo:
{
"token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
"expires_in": 3600,
"conversationId": "abc123"
}
Exemplo de código
O exemplo a seguir usa exemplos do Código de exemplo do conector para obter um token do Direct Line para um copiloto do Copilot Studio.
/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
try
{
return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
}
catch (HttpRequestException ex)
{
throw ex;
}
}
/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
public string Token { get; set; }
public int Expires_in { get; set; }
public string ConversationId { get; set; }
}
O objeto de resposta é o mesmo da solicitação GET que vimos anteriormente.
{
"token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
"expires_in": 3600,
"conversationId": "abc123"
}
Usar Direct Line para se comunicar com o copiloto
Após recuperar o token da Direct Line você estará pronto para ter uma conversa com seu copiloto do Copilot Studio com a Direct Line. Para iniciar uma conversa e enviar e receber mensagens, siga as instruções em Bot Framework Direct Line API.
O exemplo a seguir usa amostras do Exemplo de código do conector para iniciar uma conversa e enviar e receber mensagens de um copiloto do Copilot Studio.
Inicialize uma instância DirectLineClient com o token da Direct Line e inicie uma conversa:
// Use the retrieved token to create a DirectLineClient instance using (var directLineClient = new DirectLineClient(token)) { var conversation = await directLineClient.Conversations.StartConversationAsync(); string conversationtId = conversation.ConversationId; }
Depois de iniciada, cada conversa pode ser identificada e conectada usando a combinação de
token
econversationtId
. Envie uma mensagem de usuário para uma conversa existente:// Use the retrieved token to create a DirectLineClient instance // Use the conversationId from above step // endConversationMessage is your predefined message indicating that user wants to quit the chat while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase)) { using (var directLineClient = new DirectLineClient(token)) { // Send user message using directlineClient // Payload is a Microsoft.Bot.Connector.DirectLine.Activity await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity() { Type = ActivityTypes.Message, From = new ChannelAccount { Id = "userId", Name = "userName" }, Text = inputMessage, TextFormat = "plain", Locale = "en-Us", }); } }
Recupere a resposta do copiloto usando o mesmo
token
econversationId
. As atividades da resposta recuperada da Direct Line contêm mensagens do usuário e do copiloto. Você pode filtrar as atividades de resposta pelo nome do seu copiloto para obter apenas a mensagem de resposta do copiloto.// Use the same token to create a directLineClient using (var directLineClient = new DirectLineClient(token)) { // To get the first response set string watermark = null // More information about watermark is available at // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0 // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark); // update watermark from response watermark = response?.Watermark; // response contains set of Activity from both user and bot // To display bot response only, filter Activity.From.Name equals to your bot name List<Activity> botResponses = response?.Activities?.Where(x => x.Type == ActivityTypes.Message && string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList(); // Display botResponses }
Atualizar token da Direct Line
Pode ser necessário adicionar código para atualizar o token da Direct Line se seu aplicativo tiver uma conversa longa com o copiloto. O token expira, mas pode ser atualizado antes de expirar; saiba mais em Autenticação da Direct Line.
O exemplo a seguir usa partes do Exemplo de código do conector para atualizar o token de uma conversa existente do Copilot Studio.
// DirectLine provides a token refresh method
// Requires the currentToken valid when refreshing
string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
// create a new directline client with refreshToken
directLineClient = new DirectLineClient(refreshToken);
// use new directLineClient to communicate to your bot
Analisar o conteúdo da conversa do copiloto
Após iniciar uma conversa com o copiloto, o conteúdo JSON da conversa usa a atividade padrão da Microsoft Bot Framework Direct Line. Saiba mais em Bot Framework Direct Line API.
Tratar a atividade de entrega
Se seu aplicativo tiver que transferir para um provedor de agente humano, você precisará tratar a atividade de entrega. A atividade de entrega é enviada quando chega no nó "Transferir para agente". Você pode saber mais sobre o conteúdo da atividade de entrega.
Disparar uma mensagem de boas-vindas
Se você deseja que seu copiloto envie o tópico do sistema de saudação automaticamente quando um usuário inicia uma conversa, envie uma atividade com Type=event
e Name=startConversation
.