Comprar on-line e retirar na loja: Bonjour Meal – Parte 1 - Primeiros passos

Comprar on-line e retirar na loja:
Bonjour Meal – parte 1:
como começar

Sobre este codelab

subjectÚltimo nov. 14, 2024 atualizado
account_circleEscrito por Adam Chan

1. Introdução

637766505206e0a1.png c604dca3ca211399.png

Última atualização:11/05/2022

Este é o Business Messages!

Este codelab é uma introdução à integração com as Mensagens para empresas, que permitem que os clientes se conectem com as empresas que você gerencia na Pesquisa Google e no Maps. Talvez você seja uma empresa que quer fazer a integração direta com o Business Messages ou talvez você trabalhe em uma empresa de software independente que cria soluções de mensagens para as empresas com que você trabalha. Ou talvez você tenha acabado de conhecer o Business Messages e queira mexer na plataforma.

Independentemente do motivo que trouxe você até aqui, este codelab é uma ótima maneira de começar. Ao final, você terá seu primeiro agente digital com quem os usuários podem interagir. Quando estiver tudo pronto para lançar o Business Messages, você poderá alcançar milhões de clientes.

O que faz um bom agente digital?

As Mensagens para empresas são uma plataforma de conversação que oferece uma experiência semelhante a um app em dispositivos móveis, permitindo que os consumidores se conectem com as empresas sem instalar outro app. Um agente digital é a lógica com que os clientes interagem. A lógica é gerenciada por um aplicativo da Web implantado na nuvem ou na sua infraestrutura. A decisão é sua. Os melhores agentes fornecem contexto para definir expectativas, manter os clientes engajados e oferecer funcionalidades que atendam às necessidades dos usuários.

O que você vai criar

Neste codelab, você vai criar um agente digital no Business Messages para uma empresa fictícia chamada Bonjour Meal. Esse agente digital vai responder a algumas perguntas simples, como "A que horas vocês fecham?" ou "Posso comprar on-line?".

Neste codelab, os usuários vão poder comprar itens pelo agente digital, direcionar o usuário a um processador de pagamentos para receber dinheiro e, em seguida, agendar a retirada dos itens fictícios na loja.

Neste codelab, seu app vai:

  • Responder a perguntas usando um ícone de sugestão
  • Orientar o usuário a fazer perguntas que seu agente digital possa responder
  • Ofereça recursos de conversa avançados para manter o usuário engajado

883b5a7f9f266276.png

O que você vai aprender

  • Como implantar um aplicativo da Web no App Engine no Google Cloud Platform. Como alternativa, use o ngrok para testar seu aplicativo local publicamente.
  • Como configurar sua conta do Business Messages com um webhook de aplicativo da Web para receber mensagens dos usuários
  • Como enviar recursos avançados, como cards, carrosséis e sugestões de conversa, com a API Business Messages
  • Como as Mensagens comerciais enviam suas mensagens

Este codelab é focado na criação do seu primeiro agente digital.

O que é necessário

  • Fazer o registro para uma conta de desenvolvedor de comunicações empresariais
  • Confira nosso site para desenvolvedores para ver instruções sobre como fazer isso
  • Um dispositivo Android com a versão 5 ou mais recente OU um dispositivo iOS com o app Google Maps
  • Experiência com programação de aplicativos da Web
  • Uma conexão com a Internet

2. Etapas da configuração

Ativar as APIs

Para este codelab, como vamos trabalhar com um aplicativo Django, vamos usar a API Cloud Build para implantar o aplicativo no App Engine. Se você estiver usando o ngrok, não é necessário ativar a API Cloud Build.

Para ativar a API Cloud Build:

  1. Abra a API Cloud Build no Console do Google Cloud.
  2. Clique em Ativar.

Criar uma conta de serviço

Você precisa criar uma conta de serviço para acessar as APIs Business Communications e Business Messages. Siga as etapas na documentação para criar uma conta de serviço no Business Communications Developer Console.

Implantar o código inicial do Django Python EchoBot

Em um terminal, clone a Amostra de bot do Django Echo no diretório de trabalho do seu projeto com o seguinte comando:

$ git clone https://github.com/google-business-communications/bm-bonjour-meal-django-starter-code

Copie o arquivo de credenciais JSON criado para a conta de serviço na pasta de recursos de amostra e renomeie as credenciais para "bm-agent-service-account-credentials.json".

bm-bonjour-meal-django-starter-code/bonjourmeal-codelab/step-1/resources/bm-agent-service-account-credentials.json

Em um terminal, acesse o diretório da etapa 1 do exemplo.

Execute os seguintes comandos em um terminal para implantar o exemplo:

$ gcloud config set project PROJECT_ID*
$
gcloud app create
$
gcloud app deploy
  • PROJECT_ID é o ID do projeto que você usou para se registrar nas APIs.

Observe o URL do aplicativo implantado na saída do último comando:

Deployed service [default] to [https://PROJECT_ID.appspot.com]

O código inicial que você acabou de implantar contém um aplicativo da Web com um webhook para receber mensagens do Business Messages. O aplicativo repete as mensagens para o usuário e pode mostrar alguns dos recursos avançados disponíveis na plataforma de conversação.

Configurar seu webook

Agora que o serviço está implantado, use o URL do aplicativo para definir o URL do webhook na página Configurações da conta no console do desenvolvedor de comunicações empresariais.

O URL do webhook será o URL do aplicativo + "/callback/". Por exemplo, pode ser algo como este: https://PROJECT_ID.appspot.com/callback/

Acesse a página "Configurações da conta" do Business Communications Console. No canto superior direito, abaixo da barra de navegação, você vai encontrar o nome do seu projeto do GCP. Se um menu suspenso aparecer, selecione seu projeto do GCP.

Preencha os detalhes do Ponto de contato técnico e atualize o Webhook com o URL do webhook do aplicativo implantado.

ceb66c905ded40be.png

Clique em Salvar ao lado da referência do seu projeto do GCP.

3. Como criar seu primeiro agente

Como usar o Business Communications Developer Console

No Business Communications Console, clique no logotipo no canto superior esquerdo para voltar ao painel do console e clique em Criar agente. Você cria uma marca ao mesmo tempo em que cria o agente. Selecione Mensagens comerciais para Tipo de agente e verifique se as Informações do parceiro estão corretas.

Em Marca, digite o nome da marca que você está criando.A marca é a empresa com que você está trabalhando, e os consumidores podem interagir com o agente. Em Nome do agente, especifique o que você quer que os usuários vejam na conversa do Business Messages. No caso da empresa fictícia Bonjour Meal, a Bonjour Rail é a empresa ferroviária que gerencia os restaurantes Bonjour Meal. Vou especificar Bonjour Rail como a marca e Bonjour Meal como o agente.

O agente é a entidade de conversação que representa a marca.

88a9798e6546eb4e.png

Clique em Criar agente e deixe o console fazer a mágica. Essa solicitação leva alguns segundos para fazer várias solicitações à API Business Communications para criar a marca e o agente. É possível usar a API Business Communications diretamente para criar um agente e uma marca. Confira a documentação para saber como uma solicitação do curl faria as mesmas coisas que o console.

Como ter a primeira conversa

Abra o agente que você acabou de criar. Uma página de Visão geral vai aparecer para que você possa começar a analisar os detalhes do agente. Confira os URLs de teste do agente. Eles são usados para invocar a plataforma de conversa no seu dispositivo.

f6bd8ded561db36f.png

Para copiar o URL de teste, clique em qualquer um dos ícones. É claro, copie o URL de teste do dispositivo que você tem em mãos para fazer o teste. Envie a mensagem copiada para seu dispositivo da maneira que preferir.

No dispositivo móvel, toque no link para abrir o iniciador de agentes do Business Messages com o URL de teste do agente pré-preenchido.

Toque em Iniciar para invocar a plataforma de conversa do seu agente.

2bf9f282e09062de.png

Interaja com o agente e saiba o que ele pode fazer. Na maioria das vezes, a plataforma de conversa vai apenas repetir suas mensagens. Envie algo como "Olá, Mundo!" e você vai ver que o agente vai enviar a mesma mensagem de volta.

O aplicativo implantado também contém uma lógica para mostrar os recursos avançados disponíveis no Business Messages.

  • Se você enviar "card", vai invocar um Rich Card.
  • Se você enviar "chips", vai acionar os ícones de sugestão
  • Se você enviar "carousel", vai invocar um carrossel de Rich Cards.

Parabéns! Esta é a primeira conversa do seu agente com você.

Cada um dos recursos avançados pode ser usado para fornecer um contexto melhor para a pessoa que está se comunicando com seu agente. Envie recursos gráficos em cards avançados para comunicar melhor as ideias ou use ícones de sugestão para orientar a conversa.

Como atualizar a mensagem de boas-vindas e usar ícones de conversa

Vamos praticar com o console do desenvolvedor. Veja como editar a mensagem de boas-vindas do agente e aproveitar os ícones de sugestão para ajudar o usuário a se comunicar.

Acesse a página Visão geral do agente e selecione Informações do agente. Role para baixo até a seção de mensagens de boas-vindas e tópicos de conversa.

4323f988216fa054.png

Atualize a mensagem de boas-vindas (o campo de entrada amarelo) para:

Este é o agente de inicialização do Bonjour Meal. Posso repetir suas mensagens e mostrar alguns dos recursos avançados compatíveis com a plataforma. Teste estas sugestões.

Clique em + Adicionar outra sugestão de conversa, conforme indicado na caixa roxa na imagem acima, para adicionar sugestões de conversa que invocam chips de sugestão, carrossel e card. Os iniciadores de conversa que você adicionar precisam de um componente de texto e um componente postbackData. O texto é o que aparece para o usuário, enquanto os dados de postback são enviados para o webhook do seu agente. O webhook analisa os dados de postback e envia a resposta adequada ao usuário. 906bc74668a1b215.png

A seção Informações do agente no console fica assim após a modificação:

8e96b0a10edd20af.png

No lado direito do console, você tem uma prévia de como o agente vai ficar. Percebeu como a mensagem de boas-vindas reflete o que você acabou de mudar e os ícones de sugestão abaixo dela?

Essa é uma ótima ferramenta para ter uma ideia de como será a experiência do usuário. Você pode usá-lo enquanto cria seu agente e planeja as jornadas do usuário que quer oferecer.

Infelizmente, não será possível ver essas mudanças refletidas na conversa imediatamente, porque os dados anteriores são armazenados em cache na infraestrutura das Mensagens comerciais. O cache é limpo aproximadamente a cada duas horas. Portanto, você poderá tentar novamente amanhã.

Enquanto isso, vamos conferir como tudo funciona.

4. Analisar o código inicial

Uma visualização de 3.000 metros do código-fonte

O código inicial implantado envia mensagens aos usuários e pode apresentar um card interativo, um carrossel ou ícones de sugestão. Vamos analisar melhor o código-fonte para entender como isso funciona. Depois vamos descobrir o que precisa ser alterado.

O código inicial é um projeto Django. Em uma parte posterior desta série de codelabs, vamos usar o Google Datastore para manter dados como carrinhos de compras e conversas associadas. Não se preocupe se você nunca usou o Django antes. Ele é bem simples, e você vai aprender como ele funciona ao final deste codelab.

De modo geral, o Django encaminha URLs para visualizações, e a lógica de visualização produz um modelo que é renderizado no navegador. Vamos conferir o urls.py do projeto.

bm-django-echo-bot/bmcodelab/urls.py [Linhas 31-37]

from django.urls import include, path
import bopis.views as bopis_views

urlpatterns = [
   
path('', bopis_views.landing_placeholder),
   
path('callback/', bopis_views.callback),
]

Duas rotas são definidas aqui, e o Django pode executar a lógica se esses dois URLs forem reconhecidos. Considerando que o URL do projeto é https://PROJECT_ID.appspot.com/, as rotas que o projeto conhece são:

  • https://PROJECT_ID.appspot.com/
  • https://PROJECT_ID.appspot.com/callback/

As duas rotas de URL se referem a bopis_views, que é de bopis/views.py. Vamos conferir o que está acontecendo nesse arquivo. Para começar, vamos entender bopis_views.landing_placeholder.

bm-django-echo-bot/bonjourmeal-codelab/step-1/bopis/views.py [Linhas 302-309]

... 
def landing_placeholder(request):
    return HttpResponse("<h1>Welcome to the Bonjour Meal Codelab</h1>
    <br/><br/>
    To message your Bonjour Meal agent, go to the Developer Console and retrieve
    the Test URLs for the agent you have created as described in the codelab
    <a href='https://codelabs.developers.google.com/codelabs/'>here</a>.")
...

Essa lógica é executada pelo servidor da Web quando ele recebe uma solicitação da Web que aponta para a raiz do projeto. Nada muito sofisticado acontece aqui: simplesmente retornamos uma HTTPResponse contendo um pouco de HTML para o navegador que fez a solicitação. É possível abrir o URL raiz do projeto, mas não há muito o que fazer lá, porque ele leva você de volta a este codelab.

O outro URL leva a uma função chamada callback, também em bopis/views.py. Vamos conferir essa função.

bm-django-echo-bot/bopis/views.py [Lines 60-101]

...
def callback(request):
    """
    Callback URL. Processes messages sent from user.
    """
    if request.method == "POST":
        request_data = request.body.decode('utf8').replace("'", '"')
        request_body = json.loads(request_data)

        print('request_body: %s', request_body)

        # Extract the conversation id and message text
        conversation_id = request_body.get('conversationId')
        print('conversation_id: %s', conversation_id)

        # Check that the message and text body exist

        if 'message' in request_body and 'text' in request_body['message']:
            message = request_body['message']['text']

            print('message: %s', message)
            route_message(message, conversation_id)
        elif 'suggestionResponse' in request_body:
            message = request_body['suggestionResponse']['postbackData']

            print('message: %s', message)
            route_message(message, conversation_id)
        elif 'userStatus' in request_body:
            if 'isTyping' in request_body['userStatus']:
                print('User is typing')
            elif 'requestedLiveAgent' in request_body['userStatus']:
                print('User requested transfer to live agent')

        return HttpResponse("Response.")

    elif request.method == "GET":
        return HttpResponse("This webhook expects a POST request.")
...

A lógica aqui analisa o corpo da solicitação para uma mensagem ou uma suggestionResponse e transmite essas informações para uma função chamada route_message. Em seguida, ela retorna uma HttpResponse para a infraestrutura de mensagens comerciais para confirmar o recebimento da mensagem.

Essa é uma função importante. Essa lógica é o webhook do seu aplicativo da Web, que recebe mensagens de usuários que interagem com seu agente. É possível estender o webhook para enviar mensagens a uma ferramenta de automação, como o Dialogflow, para entender o que um usuário pode estar dizendo e produzir uma resposta com base nessa inferência. Você também pode encaminhar a mensagem para que o usuário possa se conectar com um agente em tempo real. Confira o diagrama a seguir:

b10113f9d037e6a5.png

As Mensagens para Empresas enviam o conteúdo da mensagem como um payload JSON para seu webhook, onde ele é roteado para um agente ativo ou para alguma lógica para responder como um bot. Esse mecanismo de roteamento, no nosso caso, é route_message. Vamos conferir.

bm-django-echo-bot/bopis/views.py [Linhas 105-122]

...
def route_message(message, conversation_id):
   
'''
    Routes the message received from the user to create a response.

    Args:
        message (str): The message text received from the user.
        conversation_id (str): The unique id for this user and agent.
    '''

    normalized_message
= message.lower()

   
if normalized_message == CMD_RICH_CARD:
        send_rich_card
(conversation_id)
   
elif normalized_message == CMD_CAROUSEL_CARD:
        send_carousel
(conversation_id)
   
elif normalized_message == CMD_SUGGESTIONS:
        send_message_with_suggestions
(conversation_id)
   
else:
        echo_message
(message, conversation_id)
...

Essa lógica começa a examinar a mensagem recebida pelo usuário. Primeiro, a mensagem é normalizada, tornando todos os caracteres em letras minúsculas. Depois de normalizada, ela verifica se a mensagem é uma das constantes definidas na parte de cima do arquivo.

bm-django-echo-bot/bopis/views.py [Lines 40-42]

...
# Set of commands the bot understands
CMD_RICH_CARD
= 'card'
CMD_CAROUSEL_CARD
= 'carousel'
CMD_SUGGESTIONS
= 'chips'
...

Ou seja, o bot analisa mensagens que contêm especificamente qualquer uma das strings que colocamos no postback_data dos iniciadores de conversa da etapa anterior deste codelab. Se nenhuma dessas strings aparecer, ela simplesmente transmitirá a mensagem para uma função chamada echo_message, que, como você pode imaginar, vai repetir as mensagens.

Enviar mensagens

Até agora, você já deve ter uma ideia de como as mensagens são recebidas pelo aplicativo da Web. Tudo é feito pelo webhook.

Mas como o aplicativo envia uma mensagem de saída para um usuário usando o Business Messages?

a9475b1da93a83e8.png

Quando sua infraestrutura responde ao usuário, você envia a resposta para a API Business Messages, que entrega a mensagem ao usuário.

A API Business Messages tem bibliotecas em Python, Node.js e Java. Também temos uma API REST que você pode usar para fazer solicitações diretamente se a sua infraestrutura não estiver em um idioma com uma biblioteca. Consulte Enviar mensagens para saber como o cURL é usado para enviar uma mensagem a um ID de conversa específico.

Para este codelab, vamos nos concentrar no uso da biblioteca de cliente do Python que já está integrada ao código inicial do Bonjour Meal implantado no App Engine no seu projeto do GCP ou executado localmente pelo ngrok.

Vamos analisar a função echo_message e conferir como interagimos com a API para enviar a mensagem ao Business Messages.

bm-django-echo-bot/bopis/views.py [Lines 199-212]

...
def echo_message(message, conversation_id):
   
'''
    Sends the message received from the user back to the user.

    Args:
        message (str): The message text received from the user.
        conversation_id (str): The unique id for this user and agent.
    '''

    message_obj
= BusinessMessagesMessage(
        messageId
=str(uuid.uuid4().int),
        representative
=BOT_REPRESENTATIVE,
        text
=message)

    send_message
(message_obj, conversation_id)
...

Nessa função, uma BusinessMessagesMessage é instanciada com a variável de mensagem transmitida para a função echo_message. Depois de instanciado, o objeto é transmitido para send_message com o ID da conversa.

bm-django-echo-bot/bopis/views.py [Lines 214-236]

...
def send_message(message, conversation_id):
    '''
    Posts a message to the Business Messages API, first sending
    a typing indicator event and sending a stop typing event after
    the message has been sent.

    Args:
        message (obj): The message object payload to send to the user.
        conversation_id (str): The unique id for this user and agent.
    '''
    credentials = ServiceAccountCredentials.from_json_keyfile_name(
        SERVICE_ACCOUNT_LOCATION,
        scopes=['https://www.googleapis.com/auth/businessmessages'])

    client = bm_client.BusinessmessagesV1(credentials=credentials)

    # Create the message request
    create_request = BusinessmessagesConversationsMessagesCreateRequest(
        businessMessagesMessage=message,
        parent='conversations/' + conversation_id)

    bm_client.BusinessmessagesV1.ConversationsMessagesService(
        client=client).Create(request=create_request)
...

A função send_message usa as credenciais da sua conta de serviço para verificar se você pode enviar mensagens para essa conversa, instanciando um cliente do Business Messages e criando uma solicitação para enviar a mensagem ao conversation ID especificado.

Os recursos avançados também usam essa função send_message, mas as mensagens criadas são específicas para rich cards, carrosséis e ícones de sugestão. Os cards avançados e os carrosséis podem incluir recursos gráficos, enquanto os ícones de sugestão têm postback_data para que a lógica de callback possa ser analisada adequadamente.

Agora que você já sabe como enviar uma mensagem, confira como o exemplo envia cards avançados, carrosséis e ícones de sugestão. Na próxima seção, vamos modificar o código-fonte para enviar mensagens com alguns desses recursos avançados.

Quando estiver tudo pronto, vamos personalizar o agente do Bonjour Meal.

5. Personalizar seu agente

Se você seguiu o codelab até agora, vai encontrar nosso agente.

906bc74668a1b215.png

Ok, não é tão bonito, está um pouco vazio e não representa muito bem nossa empresa. Felizmente, temos um conhecimento básico do código que oferece suporte ao agente e as ferramentas necessárias para personalizar o agente da maneira que quisermos.

No restante deste codelab, vamos ampliar o agente com o seguinte:

  • Inclua um logotipo real
  • Mensagem de boas-vindas aprimorada
  • Fornecer informações sobre o horário de funcionamento
  • Informar ao usuário que a compra de itens on-line será lançada em breve
  • Uso de ícones de sugestão de conversa para facilitar a conversa

Vamos aproveitar o Business Communications Console para atualizar o logotipo e a mensagem de boas-vindas, mas você sempre tem a opção de usar as APIs Business Communications diretamente para fazer isso. Em seguida, vamos atualizar o código-fonte para enviar mensagens adequadas com informações sobre o horário de funcionamento e que o Bonjour Meal vai oferecer em breve um recurso de compras on-line. Depois disso, vamos voltar ao Business Communications Console e criar ícones de sugestão de conversa para ajudar a orientar a conversa para as experiências de caminho ideal que o agente digital oferece.

No Business Communications Console, selecione seu agente e acesse Informações do agente. Vamos atualizar o logotipo da empresa, conforme indicado em amarelo abaixo.

eb6b8ac6b62387ee.png

Clique em Fazer upload para selecionar uma imagem a ser enviada ou importada de um URL.

Consulte as diretrizes de design de logotipo na documentação para saber mais sobre as práticas recomendadas para usar seus próprios logotipos.

Vamos fazer o upload do logotipo localizado no código-fonte que você clonou no início deste codelab. Ele está no diretório ./assets/ do repositório e tem o nome "bonjour_meal-logo.png". Você pode arrastar o arquivo para o modal no navegador da Web. Uma ferramenta de edição leve será apresentada para manipular a qualidade e o corte da imagem. Ajuste a resolução da imagem e corte de modo que ela fique menor ou igual à restrição de 50 KB. Quando estiver satisfeito com a imagem, clique na marca de seleção no círculo azul para confirmar e clique em Selecionar na parte de baixo do modal.

1856081f59623ae2.png

Por fim, clique em Salvar no canto superior direito da página Informações do agente. Essa mudança vai levar algum tempo para aparecer no seu dispositivo, porque as informações do agente são armazenadas em cache nos nossos servidores e ficam visíveis em até duas horas após a mudança.

Atualizar a mensagem de boas-vindas

Já atualizamos a mensagem de boas-vindas anteriormente neste codelab. Vamos fazer isso de novo, mas desta vez vamos configurar uma mensagem de boas-vindas mais adequada à jornada do usuário do Bonjour Meal.

No Business Communications Console, selecione seu agente e acesse Informações do agente. Role a tela para baixo até encontrar o campo de entrada Mensagem de boas-vindas, onde você pode atualizar a mensagem.

6598fec47021136e.png

Sabendo que vamos adicionar iniciadores de conversa, podemos fazer referência a eles na mensagem de boas-vindas. No campo de entrada, vamos substituir por este texto:

"Bem-vindo ao Bonjour Meal. Sou um assistente que pode ajudar você com dúvidas sobre o Bonjour Meal. Tente algumas das opções a seguir."

Por fim, clique em Salvar no canto superior direito da página Informações do agente. Novamente, essa mudança vai levar algum tempo para ser refletida devido ao nosso mecanismo de armazenamento em cache.

Como informar o horário de funcionamento

Para fornecer essas informações aos usuários, vamos enviar uma mensagem personalizada usando a API Business Messages.

Você pode se lembrar que as mensagens são analisadas na função route_message de views.py. A função primeiro normaliza a string e depois começa a verificar se a mensagem normalizada corresponde a qualquer um dos parâmetros codificados. Para simplificar, vamos adicionar uma condição extra para verificar se a mensagem normalizada é igual a uma nova constante chamada CMD_BUSINESS_HOURS_INQUIRY e que vai conter o valor "business-hours-inquiry". Se a condição for avaliada como verdadeira, vamos invocar uma função chamada send_message_with_business_hours.

A função route_message vai ficar assim:

bm-django-echo-bot/bopis/views.py

...
def route_message(message, conversation_id):
   
'''
    Routes the message received from the user to create a response.

    Args:
        message (str): The message text received from the user.
        conversation_id (str): The unique id for this user and agent.
    '''

    normalized_message
= message.lower()

   
if normalized_message == CMD_RICH_CARD:
        send_rich_card
(conversation_id)
   
elif normalized_message == CMD_CAROUSEL_CARD:
        send_carousel
(conversation_id)
   
elif normalized_message == CMD_SUGGESTIONS:
        send_message_with_suggestions
(conversation_id)
   
elif normalized_message == CMD_BUSINESS_HOURS_INQUIRY:
        send_message_with_business_hours
(conversation_id)
   
else:
        echo_message
(message, conversation_id)
...

Para que o código funcione, precisamos fazer mais duas mudanças: a primeira é definir CMD_BUSINESS_HOURS_INQUIRY com as outras constantes, e a segunda é definir a função send_message_with_business_hours e enviar uma mensagem usando a API Business Messages.

Primeiro, vamos definir a constante na parte de cima do arquivo com as outras declarações de constantes:

bm-django-echo-bot/bopis/views.py

...
# Set of commands the bot understands
CMD_RICH_CARD
= 'card'
CMD_CAROUSEL_CARD
= 'carousel'
CMD_SUGGESTIONS
= 'chips'
CMD_BUSINESS_HOURS_INQUIRY
= 'business-hours-inquiry'
...

Agora, vamos definir send_message_with_business_hours. Você pode definir essa função em qualquer lugar no arquivo, seguindo a sintaxe adequada do Python. Como essa função simplesmente envia uma mensagem, assim como echo_message, ela pode ser usada como modelo para definir essa função.

bm-django-echo-bot/bopis/views.py

...
def send_message_with_business_hours(conversation_id):

    message
= '''Thanks for contacting us! The hours for the store are:\n
    MON 8am - 8pm\n
    TUE 8am - 8pm\n
    WED 8am - 8pm\n
    THU 8am - 8pm\n
    FRI 8am - 8pm\n
    SAT 8am - 8pm\n
    SUN 8am - 8pm
    '''


    message_obj
= BusinessMessagesMessage(
        messageId
=str(uuid.uuid4().int),
        representative
=BOT_REPRESENTATIVE,
        text
=message)

    send_message
(message_obj, conversation_id)
...

Com isso, nosso bot poderá responder ao usuário com essas informações de horário comercial quando ele enviar a seguinte mensagem: "business-hours-inquiry". Você vai encontrar algo como isto:

125802166995afd5.png

Depois que você implantar o código-fonte no GCP, as mudanças vão ficar visíveis imediatamente. Não armazenamos em cache o aplicativo da Web no Google Cloud Platform da mesma forma que as informações do agente, para que você possa testar essa experiência imediatamente.

Como temos um pouco de tempo para fazer mudanças na fonte, vamos fazer mais uma modificação que permitirá que um usuário pergunte sobre compras on-line. O agente digital vai responder dizendo que o recurso ainda não está disponível, mas que você pode voltar e conferir mais tarde.

Informar o usuário que as compras on-line vão ser lançadas em breve

Vamos fazer uma modificação semelhante à que fizemos para informar o usuário sobre o horário de funcionamento. Desta vez, vamos colocar as informações em um card avançado com uma imagem interessante.

Analise a mensagem normalizada e verifique uma condição para uma constante chamada CMD_ONLINE_SHOPPING_INQUIRY com o valor definido como "consulta-de-compras-on-line", que invoca send_online_shopping_info_message se a condição for verdadeira.

bm-django-echo-bot/bopis/views.py

...
# Set of commands the bot understands
CMD_RICH_CARD
= 'card'
CMD_CAROUSEL_CARD
= 'carousel'
CMD_SUGGESTIONS
= 'chips'
CMD_BUSINESS_HOURS_INQUIRY
= 'business-hours-inquiry'
CMD_ONLINE_SHOPPING_INQUIRY
= 'online-shopping-inquiry'
...
...
...
def route_message(message, conversation_id):
   
'''
    Routes the message received from the user to create a response.

    Args:
        message (str): The message text received from the user.
        conversation_id (str): The unique id for this user and agent.
    '''

    normalized_message
= message.lower()

   
if normalized_message == CMD_RICH_CARD:
        send_rich_card
(conversation_id)
   
elif normalized_message == CMD_CAROUSEL_CARD:
        send_carousel
(conversation_id)
   
elif normalized_message == CMD_SUGGESTIONS:
        send_message_with_suggestions
(conversation_id)
   
elif normalized_message == CMD_BUSINESS_HOURS_INQUIRY:
        send_message_with_business_hours
(conversation_id)
   
elif normalized_message == CMD_ONLINE_SHOPPING_INQUIRY:
        send_online_shopping_info_message
(conversation_id)
   
else:
        echo_message
(message, conversation_id)
...

Agora vamos definir send_online_shopping_info_message. Queremos que essa mensagem seja enviada em um card interativo com uma imagem. Vamos copiar a função send_rich_card para usar como modelo e definir send_online_shopping_info_message.

Primeiro, precisamos atualizar o texto alternativo para ter uma mensagem adequada. O texto alternativo é usado se o dispositivo não puder receber um card rico por algum motivo. Em seguida, atualize BusinessMessagesRichCard para incluir um título, uma descrição, sugestões e um campo de mídia relevantes. Nossa função vai ficar assim:

bm-django-echo-bot/bopis/views.py

...
def send_online_shopping_info_message(conversation_id):
    fallback_text
= ('Online shopping will be available soon!')

    rich_card
= BusinessMessagesRichCard(
        standaloneCard
=BusinessMessagesStandaloneCard(
            cardContent
=BusinessMessagesCardContent(
                title
='Online shopping info!',
                description
='Thanks for your business, we are located in SF near the Golden Gate Bridge. Online shopping is not yet available, please check back with us in a few days.',
                suggestions
=[],
                media
=BusinessMessagesMedia(
                    height
=BusinessMessagesMedia.HeightValueValuesEnum.MEDIUM,
                    contentInfo
=BusinessMessagesContentInfo(
                        fileUrl
=SAMPLE_IMAGES[4],
                        forceRefresh
=False
                   
))
               
)))

    message_obj
= BusinessMessagesMessage(
        messageId
=str(uuid.uuid4().int),
        representative
=BOT_REPRESENTATIVE,
        richCard
=rich_card,
        fallback
=fallback_text)

    send_message
(message_obj, conversation_id)
...

Uhuuu! Nosso agente digital agora pode responder a usuários que fazem perguntas sobre compras on-line. Por enquanto, nosso agente digital ainda não oferece suporte para compras on-line. Por isso, enviamos uma mensagem ao usuário informando que o recurso será lançado em breve. Confira como nosso agente digital fica quando o usuário pergunta sobre compras on-line.

5cd63c57c1b84f9a.png

Assim como a mudança anterior que fizemos para permitir que um usuário pergunte sobre o horário comercial, essa mudança pode ser vista imediatamente se você estiver usando o ngrok ou assim que implantar o código no App Engine do GCP.

Na próxima parte, vamos usar iniciadores de conversa e ícones de sugestão para guiar a conversa até o caminho ideal.

Como usar ícones para guiar a conversa

Fizemos algumas mudanças no código-fonte e implantamos o agente digital atualizado, mas nunca esperamos que os usuários digitem "business-hours-inquiry" ou "online-shopping-info" para fazer perguntas sobre a empresa. Vamos atualizar as sugestões de conversa para que, quando a conversa for aberta, o usuário não receba apenas uma mensagem de boas-vindas, mas também sugestões de conversa.

Acesse o Console Business Communications e a página Informações do agente. Já definimos iniciadores de conversa para "selos", "cards" e "carrinhos". Embora eles ainda funcionem, eles não são mais relevantes para nossa função comercial. Você pode deixá-los para continuar mostrando esses recursos avançados ou removê-los para que o agente digital mostre iniciadores de conversa específicos para a empresa Bonjour Meal.

Vamos criar duas novas maneiras de iniciar conversas. Para o primeiro, defina o texto como "Qual é o horário de funcionamento?" e defina os dados de Postback como "business-hours-inquiry". Para a segunda conversa, defina o texto como "Posso fazer compras aqui?" e defina os dados de postback como "informações de compras on-line".

O resultado será a configuração mostrada na captura de tela a seguir:

ef6e6888acea93e3.png

Assim como em outras mudanças feitas no Business Communications Console, isso vai levar algum tempo para ser propagado antes que você possa conferir as mudanças produzidas no seu dispositivo móvel.

Agora que terminamos com as perguntas iniciais, também precisamos de uma maneira de orientar o usuário para um caminho feliz depois que a conversa começar. É possível usar os ícones de forma contextual após o envio de uma mensagem para orientar o usuário a outros recursos que o agente digital é capaz de oferecer. Então, vamos enviar uma mensagem com uma sugestão para fazer outra coisa com o agente sempre que o usuário perguntar sobre o horário de funcionamento ou compras on-line.

No final da função, adicione o seguinte:

bm-django-echo-bot/bopis/views.py

...
def send_online_shopping_info_message(conversation_id):
...
   
# at the end of the function, send a message with suggestions
    message_obj
= BusinessMessagesMessage(
        messageId
=str(uuid.uuid4().int),
        representative
=BOT_REPRESENTATIVE,
        text
='Let us know how else we can help you:',
        fallback
='Please let us know how else we can help you.',
        suggestions
=[
           
BusinessMessagesSuggestion(
                reply
=BusinessMessagesSuggestedReply(
                text
='Business hours',
                postbackData
='business-hours-inquiry')
           
),
       
])

    send_message
(message_obj, conversation_id)
...

# Let's do the same with the business hours
def send_message_with_business_hours(conversation_id):
...
   
# at the end of the function, send a message with suggestions
    message_obj
= BusinessMessagesMessage(
        messageId
=str(uuid.uuid4().int),
        representative
=BOT_REPRESENTATIVE,
        text
='Let us know how else we can help you:',
        fallback
='Please let us know how else we can help you.',
        suggestions
=[
           
BusinessMessagesSuggestion(
                reply
=BusinessMessagesSuggestedReply(
                text
='Can I purchase online?',
                postbackData
='online-shopping-inquiry')
           
),
       
])

    send_message
(message_obj, conversation_id)
...

O campo de texto em uma BusinessMessagesSuggestion é limitado a 25 caracteres, conforme descrito na documentação.

Com as atualizações nas conversas iniciais e o uso estratégico dos ícones de sugestão, confira algumas capturas de tela da experiência esperada do usuário.

ef57695e2bacdd20.png

6. Parabéns

Parabéns! Você criou seu primeiro agente digital do Business Messages.

Você implantou um aplicativo da Web para oferecer suporte ao seu agente digital no Business Messages, usou o Business Communications Console para modificar o agente e moldou a experiência do usuário com um agente digital fazendo mudanças no código-fonte.

Agora você sabe as principais etapas necessárias para criar uma experiência interativa no Business Messages, e as possibilidades são incríveis. Seu agente pode ser estendido para oferecer suporte à pesquisa de inventário ou introduzir um carrinho de compras para acompanhar o que pode interessar ao usuário. Você pode usar um carrossel para mostrar os itens do menu e, usando sugestões, permitir que o usuário selecione os itens de interesse.

Confira um exemplo de como isso pode ficar.

57d2bb7b0ec38c81.png

Como criar uma ótima experiência de conversa?

Os melhores agentes fornecem informações contextuais ao usuário e oferecem funcionalidade durante a conversa para que ele possa se envolver e interagir com a empresa como faria normalmente por telefone ou até mesmo pessoalmente. Pense em como os tópicos a seguir podem ser aplicados a uma conversa que você gostaria de ter com uma empresa com a qual trabalha.

Fornecer contexto e definir expectativas

Fornecer contexto pode ser desde declarar explicitamente como você pode ajudar o usuário até apresentar o agente digital com uma persona com a qual o usuário se identifica. Os agentes bem-sucedidos nas Mensagens comerciais usam o avatar representativo para mostrar ao usuário com quem ele está conversando.

A definição de expectativas depende da experiência do usuário que você está criando. Por exemplo, se o agente oferece suporte à pesquisa de inventário, informe primeiro ao usuário que a disponibilidade pode estar baixa antes de dar a resposta.

Oferecer funcionalidade ao usuário

Os consumidores se conectam com as empresas o tempo todo. As Mensagens comerciais podem oferecer suporte a interações complexas do usuário, desde consultas como a verificação do status de um pedido até a verificação se um item está em estoque. Muitos usuários continuam ligando para as empresas por telefone para receber respostas, mesmo que elas estejam disponíveis no site. Como resultado, as empresas precisam investir mais recursos para lidar com o volume de chamadas, principalmente durante os feriados.

Manter o usuário engajado

Ofereça pontos de contato para manter o usuário engajado na conversa. Entre as mensagens, você pode invocar indicadores de digitação para informar ao usuário que está processando uma resposta.

Com recursos avançados, como indicadores de digitação, ícones de sugestão, cards avançados e carrosséis, é possível guiar o usuário por experiências de usuário de caminho ideal para ajudar a concluir determinadas tarefas, como fazer um pedido em um menu de itens. O objetivo é reduzir o tráfego de ligações para a linha telefônica de uma empresa.

É fundamental que uma conversa ofereça funcionalidade ao usuário. Os usuários que se conectam com uma empresa por mensagens esperam que as perguntas sejam respondidas rapidamente. Em uma situação não ideal, o agente digital não pode facilitar a conversa, o que pode levar a uma experiência ruim do usuário. Felizmente, há maneiras de contornar isso, como transferir a conversa para um agente ao vivo, que será abordado em um próximo codelab.

Qual é a próxima etapa?

Quando estiver tudo pronto, confira alguns dos seguintes tópicos para saber mais sobre as interações mais complexas que você pode realizar no Business Messages

Documentos de referência