Esta página foi traduzida pela API Cloud Translation.

Receber mensagens

Depois de se registrar com o Business Messages, você pode receber mensagens em nome do seu agente de teste. Você pode receber mensagens das marcas que gerencia após criar, verificar e iniciar agentes dessas marcas.

Quando um cliente envia uma mensagem a um agente que você gerencia, o Business Messages envia um payload JSON para o webhook que contém vários IDs, conteúdo de mensagens e informações de local.

Use a página de registros do Console do desenvolvedor do Business Communications para depurar problemas de entrega de mensagens.

Processar mensagens recebidas

A maneira como o agente processa e responde às mensagens dos usuários depende muito da lógica da sua empresa. No entanto, geralmente as etapas para responder a uma mensagem de usuário são consistentes.

Confirmar a mensagem

Para confirmar uma mensagem recebida pelo webhook, retorne uma resposta HTTP válida para as mensagens enviadas para o webhook.

Se uma mensagem não for entregue devido a problemas de tempo limite de entrega, acessibilidade de webhook, redirecionamento ou problemas de permissão, o Google armazenará e encaminhará a mensagem com várias repetições por sete dias ou até que o webhook receba a mensagem.

Verificar se a mensagem é do Google

Verifique se o Google enviou a mensagem antes de processar o conteúdo.

Para verificar se o Google enviou uma mensagem que você recebeu,

Analise o cabeçalho X-Goog-Signature da mensagem. Essa é uma cópia codificada em hash e base64 do payload do corpo da mensagem.
Usando seu token do cliente (que foi apresentado quando você configurou seu webhook) como uma chave, crie um HMAC SHA512 dos bytes do payload da mensagem e codifique o resultado em base64.

Observação: se você recebeu uma chave de parceiro durante o registro no Business Messages, use-a como a chave do HMAC SHA512 em vez do token do cliente. Se você atualizar seu webhook, use o token do cliente para validação da mensagem com a nova configuração do webhook.
Compare o hash X-Goog-Signature com o hash que você criou.
- Se os hashes forem correspondentes, você confirmou que o Google enviou a mensagem.
- Se os hashes não corresponderem, verifique seu processo de hash em uma mensagem conhecida. Se o processo de hash estiver funcionando corretamente e você receber uma mensagem que acredita ter sido enviada fraudulentamente para você, entre em contato conosco (faça login com uma Conta do Google do Business Messages).

Veja o exemplo de verificação de mensagem nos repositórios do GitHub para os bots de eco em Java, Node.js e Python

Identificar a localidade

Os usuários se comunicam de muitos locais e em vários idiomas. O Business Messages representa as preferências de idioma dos usuários com os campos resolvedLocale e userDeviceLocale, que são baseados nas configurações de localidade dos dispositivos. Consulte Localização e localidades.

Sempre que possível, encaminhe mensagens e escreva respostas com base nas preferências de idioma dos usuários.

Rotear a mensagem com base no contexto

O contexto da mensagem informa os tipos de informações que os usuários podem procurar. Por exemplo, se um usuário enviar uma mensagem com um valor placeId, ele enviou uma mensagem para um local específico (identificado por placeId) e provavelmente vai fazer perguntas específicas sobre o local. Da mesma forma, se uma mensagem tiver um valor nearPlaceId, que identifica um local próximo ao usuário, ele provavelmente quer saber informações específicas do local, mas o agente precisa confirmar o local com que o usuário quer conversar antes de iniciar a conversa.

Encaminhe a mensagem com as informações de contexto dela até o local mais adequado para responder:

Se a mensagem estiver em uma nova conversa e for uma pergunta comum, você poderá responder com automação.
Se a automação não processar a pergunta, encaminhe para um agente ativo.
Se a localidade da mensagem não corresponder à localidade padrão do seu agente, encaminhe a mensagem para um agente ativo que ofereça suporte a ela.
Se a pergunta for sobre um local específico, direcione-o para uma pessoa com informações sobre esse local.
Se a mensagem estiver em uma conversa em andamento, encaminhe-a para o agente ao vivo que participa dela.

Identificar o tipo de mensagem enviada pelo usuário

Os usuários podem enviar três tipos de mensagens:

As mensagens de texto são respostas em formato livre.
As mensagens Image incluem um URL assinado para uma imagem enviada pelo usuário.
As mensagens de sugestão incluem os dados de postback e o texto da ação sugerida ou a resposta sugerida em que o usuário tocou.

Processar o conteúdo da mensagem

Se o agente usar a automação, o conteúdo da mensagem do usuário deverá orientar a lógica do agente e a próxima resposta na conversa.

A maneira mais fácil de identificar a intenção do usuário é com dados de postback de uma resposta sugerida ou ação sugerida. Independentemente do texto associado à sugestão, os dados de postback são legíveis por máquina.

Se um usuário enviar uma mensagem de texto, seu agente poderá analisar a resposta das palavras-chave compatíveis ou usar o processamento de linguagem natural (como com a integração do Dialogflow para processar a mensagem do usuário e identificar um caminho a seguir).

Se o agente não souber responder à mensagem do usuário, ele precisará responder com um estado de erro e tentar continuar a conversa solicitando mais informações ao usuário, solicitando entrada de maneira diferente ou transmitindo a conversa para um agente em tempo real.

Responder ao usuário

Depois de identificar a resposta correta, seja por meio da automação ou de um agente em tempo real, o agente envia uma mensagem e continua a conversa com o usuário.

Ao escrever uma resposta, considere a localidade do usuário. Também é possível personalizar as respostas recuperando valores do objeto userInfo em cada mensagem recebida.

Tipos de mensagem

O código a seguir mostra como o agente recebe mensagens.

Para informações sobre formatação e valor, consulte UserMessage.

Texto

A forma mais comum de o usuário responder é em texto simples. As mensagens de texto têm o seguinte formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "message": {
    "messageId": "MESSAGE_ID",
    "name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "text": "MESSAGE_TEXT",
    "createTime": "MESSAGE_CREATE_TIME",
  },
  "dialogflowResponse": {
    "autoResponded": "BOOLEAN",
    "faqResponse": {
      "userQuestion": "USER_QUESTION",
      "answers": [{
        "faqQuestion": "FAQ_QUESTION",
        "faqAnswer": "FAQ_ANSWER",
        "matchConfidenceLevel": "CONFIDENCE_LEVEL",
        "matchConfidence": "CONFIDENCE_NUMERIC",
      }],
    },
  },
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para opções de formatação e valor, consulte Message.

Imagem

Além de enviar texto, os usuários podem enviar imagens para seu agente como mensagens. O Business Messages armazena imagens compartilhadas por sete dias em URLs assinados e inclui esses URLs no campo text do payload da mensagem.

Se o agente incluir automação, verifique se a automação sabe como responder se um usuário compartilha uma imagem. Para agentes ativos, verifique se as imagens são transmitidas ou se os URLs nas mensagens são clicáveis.

...
"message": {
    "text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
  }
...

Para opções de formatação e valor, consulte Message.

Sugestão

As respostas e ações sugeridas permitem que os usuários respondam ou realizem ações com um toque. Quando um usuário toca em uma sugestão, o agente recebe um payload com o texto da sugestão e os dados de postback.

As mensagens de sugestão têm o seguinte formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "suggestionResponse": {
    "message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
    "postbackData": "POSTBACK_DATA",
    "createTime": "RESPONSE_CREATE_TIME",
    "text": "SUGGESTION_TEXT",
    "suggestionType": "SUGGESTION_TYPE",
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para opções de formatação e valor, consulte SuggestionResponse.

Solicitação de autenticação

A sugestão de solicitação de autenticação permite que os usuários façam login com um provedor de OAuth para fornecer detalhes de identidade com o agente ou para permitir que o agente execute ações em nome dos usuários. Consulte Autenticar com o OAuth.

Se um usuário fizer login com o provedor de OAuth especificado, o agente receberá um payload com o código de autorização. Se um usuário não conseguir fazer login, o agente receberá um payload com detalhes do erro.

As mensagens de solicitação de autenticação têm o seguinte formato.

{
  "agent": "brands/BRAND_ID/agents/AGENT_ID",
  "conversationId": "CONVERSATION_ID",
  "customAgentId": "CUSTOM_AGENT_ID",
  "requestId": "REQUEST_ID",
  "authenticationResponse": {
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "REDIRECT_URI",
    "errorDetails": {
      "error": "ERROR",
      "errorDescription": "ERROR_DESCRIPTION",
    },
  }
  "context": {
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
  },
  "sendTime": "SEND_TIME",
}

Para opções de formatação e valor, consulte AuthenticationResponse.

Contexto da mensagem

Cada mensagem contém informações de contexto sobre a origem dela.

...
  "context": {
    "customContext": "CUSTOM_CONTEXT",
    "entryPoint": "CONVERSATION_ENTRYPOINT",
    "placeId": "LOCATION_PLACE_ID",
    "nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
    "deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
    "resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
    "userInfo": {
      "displayName": "USER_NAME",
      "userDeviceLocale": "USER_LOCALE",
    },
    "widget": {
      "url": "WEBSITE_URL",
      "widgetContext": "WIDGET_CONTEXT",
    },
  },
...

Campo	Descrição
`customContext`	Dados de contexto especificados pelo parceiro.
`entryPoint`	A superfície de mensagem de onde o usuário iniciou a conversa, conforme definido pelo EntryPoint.
`placeId`	Um identificador exclusivo do banco de dados do Google Places para o local em que o usuário enviou uma mensagem. Ele só aparece nas mensagens de pontos de entrada específicos do local.
`nearPlaceId`	Um identificador exclusivo do banco de dados do Google Places para o primeiro local em um pacote local. Confirme os locais com que os usuários querem conversar quando você receber valores `nearPlaceId`.
`deflectedPhoneNumber`	O número de telefone que o Business Messages desviau do usuário da chamada quando a conversa começou.
`resolvedLocale`	A melhor correspondência calculada da localidade do usuário (informada em `userDeviceLocale`) e das localidades compatíveis do agente (determinadas pelas configurações de conversa especificadas). Consulte Localização e Iniciar a conversa. O valor da localidade é uma tag de idioma IETF BCP 47 bem formada.
`userInfo.displayName`	O nome do usuário que enviou a mensagem. Se o usuário desativar o compartilhamento de identidade, esse campo ficará vazio.
`userInfo.userDeviceLocale`	A localidade do usuário, informada pelo dispositivo, como uma tag de idioma IETF BCP 47 bem formada.
`widget.url`	É o URL do site em que a superfície de conversa foi iniciada.
`widget.widgetContext`	O valor do atributo `data-bm-widget-context` do widget usado para iniciar a conversa.

Histórico da conversa

O Google não fornece históricos de conversa. Mantenha suas próprias conversas históricas, de acordo com a Política de Privacidade e as práticas recomendadas, para enviar respostas fundamentadas a mensagens futuras dos usuários.