Vamos desativar o Google Business Messages em 31 de julho de 2024. Clique aqui para mais informações.

Esta página foi traduzida pela API Cloud Translation.

Receber mensagens

Depois de se registrar no Perfil da Empresa Mensagens, você pode receber mensagens em nome do agente de teste. Você pode receber mensagens para as marcas que você gerencia depois de criar, verificar e iniciar agentes dessas marcas.

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

Usar os registros do Business Communications Developer Console página para depurar problemas na entrega de mensagens.

Processar mensagens recebidas

A forma como o agente lida e responde às mensagens dos usuários depende muito em sua lógica de negócios. Geralmente, no entanto, as etapas para responder a um sejam consistentes.

Confirmar a mensagem

Para confirmar uma mensagem recebida pelo webhook, retorne uma resposta HTTP válida às mensagens enviadas ao webhook.

Se uma mensagem não for entregue devido ao tempo limite de entrega, à acessibilidade do webhook, redirecionamentos ou problemas de permissão, o Google armazena e encaminha a mensagem com várias novas tentativas, por sete dias ou até que o webhook receba mensagem.

Verificar se a mensagem é do Google

Verifique se o Google enviou a mensagem antes de processá-la conteúdo.

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

analisar o cabeçalho X-Goog-Signature da mensagem; Ela é uma string com hash cópia codificada em base64 do payload do corpo da mensagem.
Usando seu token de cliente (que foi apresentado quando você configurou seu webhook). como 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 Perfil da Empresa Mensagens: use-o como a chave para o HMAC SHA512 em vez do cliente com base no token correto anterior. Se você atualizar o webhook, use o token do cliente para a mensagem validação com a nova configuração do webhook.
Compare o hash X-Goog-Signature com o hash que você criou.
- Se os hashes forem correspondentes, isso significa que você confirmou que o Google enviou a mensagem.
- Se os hashes não corresponderem, verifique seu processo de hash em uma mensagem. Se o processo de hash estiver funcionando corretamente e você receber uma uma mensagem que você acredita ter sido enviada de maneira fraudulenta; entre em contato (você deve assinar login com uma Conta do Google no Business Messages).

Confira o exemplo de verificação de mensagens nos repositórios do GitHub para Echo Bots em Java, Node.js, e Python.

Identificar a localidade

Os usuários se comunicam de vários locais e em muitos idiomas. Mensagens comerciais representa preferências de idioma com os resolvedLocale e userDeviceLocale, que são baseados nos dispositivos configurações de localidade. Consulte Localização e localidades.

Sempre que possível, encaminhe mensagens e escreva respostas com base no idioma preferências.

Encaminhar a mensagem com base no contexto

O contexto da mensagem indica que tipo de informação o usuário pode estar procurando. Por exemplo, se um usuário envia uma mensagem com um placeId eles enviaram uma mensagem para um local específico (identificados por placeId) e estão propensas a fazer perguntas específicas sobre o local. Da mesma forma, se uma mensagem tem um Valor nearPlaceId, que identifica um local próximo ao usuário, que provavelmente quiser saber informações específicas do local, mas o agente precisa confirmar local com o qual o usuário quer bater papo antes de iniciar a conversa.

Com as informações de contexto da mensagem, encaminhe-a para o melhor local adequado para responder:

Se a mensagem estiver em uma nova conversa e for uma pergunta comum, você pode responder com a automação.
Se a automação não conseguir lidar com a pergunta, encaminhe-a para um agente humano.
Se a localidade da mensagem não corresponder à localidade padrão do seu agente, encaminhe o para um agente em tempo real que ofereça suporte na localidade.
Se a pergunta for sobre um local específico, encaminhe-a para alguém com informações sobre esse local.
Se a mensagem estiver em uma conversa, encaminhe-a para um atendente participando da conversa.

Identifique o tipo de mensagem que o usuário enviou

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

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

Processar o conteúdo da mensagem

Caso seu agente use automação, o conteúdo da mensagem do usuário vai orientar suas 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 ou ação sugerida. Independentemente do texto associado a 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 para palavras-chave com suporte ou usar processamento de linguagem natural (como com o Dialogflow integração para processar a mensagem do usuário e identificar um caminho a seguir.

Se o agente não souber como responder à mensagem do usuário, ele deverá responda com um estado de erro e tente continuar a conversa solicitar informações adicionais ao usuário, solicitando a entrada de um de maneira diferente ou passando a conversa para um atendente.

Responder ao usuário

Depois que o agente identifica a resposta correta, seja por automação ou agente em tempo real: ele 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 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 maneira mais comum de os usuários responderem é com texto simples. As mensagens de texto têm no formato a seguir.

{
  "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 mensagens de texto, os usuários podem enviar imagens para seu agente como mensagens. O Business Messages armazena imagens compartilhadas por sete dias assinado URLs e inclui esses URLs no campo text do payload da mensagem.

Se o agente incluir automação, verifique se ela sabe como responder se um usuário compartilhar uma imagem. Para atendentes, verifique se as imagens foram transmitidas por meio de 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 sugeridas e as ações sugeridas pelos usuários 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 de 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 do Authentication permite que os usuários façam login com uma conta do provedor para fornecer detalhes de identidade ou permitir que o agente executar ações no conjunto de dados nome de usuário. Consulte Autenticar com OAuth.

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

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

{
  "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 o local de 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 plataforma de mensagens em que o usuário iniciou a conversa, conforme definido por EntryPoint.
`placeId`	Um identificador exclusivo do banco de dados do Google Places para o local que o usuário enviou. Ela só aparece em mensagens específicas do local e pontos de entrada.
`nearPlaceId`	Um identificador exclusivo do banco de dados do Google Places para o primeiro local em um pacote local. Confirmar os locais em que os usuários querem conversar ao receber valores de `nearPlaceId`.
`deflectedPhoneNumber`	O número de telefone para o qual o Business Messages desviou o usuário de ligar quando a conversa começou.
`resolvedLocale`	A melhor correspondência calculada da localidade do usuário (informada em `userDeviceLocale`) e as localidades aceitas do agente (determinado 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 compartilhamento de identidade, esse campo ficará vazio.
`userInfo.userDeviceLocale`	A localidade do usuário, informada pelo dispositivo, como um endereço Tag de idioma IETF BCP 47.
`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. Manter seu próprio histórico conversas, de uma maneira em conformidade com sua política de privacidade e práticas recomendadas, para que você possa enviar respostas informadas para futuras mensagens dos usuários.