Autenticar com OAuth

O OAuth permite que os agentes verifiquem identidades e fornecer informações informações em conversas de forma segura. Ao solicitar que os usuários façam login provedor OAuth confiável, os agentes podem acessar dados do usuário que ajudam a fornecer a respostas com automação e economize tempo para atendentes.

O Business Messages é compatível com o OAuth 2.0 com o campo Solicitação de autenticação sugestão, que solicita que os usuários façam login em um provedor OAuth configurado para o agente. Depois que o usuário faz login, o Business Messages transmite uma autorização. código de volta para o agente como uma mensagem.

Depois de receber o código de autorização do provedor OAuth, você poderá se integram às APIs e dão suporte a fluxos de conversa que exigem que o usuário informações de identidade. Tenha em mente que cada serviço com o qual você interage tem próprios termos de uso.

Configurar o OAuth para um agente

Para ativar a sugestão de solicitação de autenticação para um agente, você precisa: configure o OAuth primeiro.

Para especificar uma configuração OAuth, faça uma solicitação PATCH com o grupo Business Communications API para atualizar o campo endpointUrl do agente.

Depois de especificar o URL do endpoint, armazene URIs de redirecionamento para seu agente e atualize os URIs de redirecionamento nas informações do seu provedor OAuth.

Pré-requisitos

Você precisa dos seguintes itens:

  • Um provedor OAuth que siga a especificação OAuth 2.0
  • Caminho para a chave da conta de serviço do projeto do GCP na máquina de desenvolvimento
  • O agente name (por exemplo, "brands/12345/agents/67890")

    Se você não souber o name do agente, consulte Listar todos os agentes de um marca.

  • O URL do endpoint em que os usuários fazem login no provedor de OAuth

Enviar a solicitação de atualização

Para atualizar o agente, execute o comando a seguir. Substituir variáveis por valores identificados em Pré-requisitos.

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID?updateMask=businessMessagesAgent.authorizationConfig" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
    'businessMessagesAgent': {
        'authorizationConfig': {
            'endpointUrl': '
ENDPOINT_URL',
        },
    },
}"

Atualizar URIs de redirecionamento

Agora que o OAuth está configurado para o agente, você precisa adicionar quatro URIs de redirecionamento ao seu provedor OAuth:

  • https://business.google.com/callback
  • https://business.google.com/callback?
  • https://business.google.com/message?az-intent-type=1
  • https://business.google.com/message?az-intent-type=1&

É necessário incluir todos os URLs de redirecionamento nas informações do seu provedor de OAuth.

O processo de atualização dos URIs de redirecionamento varia de acordo com o provedor OAuth. Consulte o provedor OAuth para mais instruções.

Agora que o OAuth está configurado para seu agente, é possível autenticar usuários com a opção Solicitação de autenticação sugestão.

Autenticar um usuário

Depois de configurar o OAuth para um agente, você pode solicitar que os usuários façam login com o Solicitação de autenticação sugestão.

Pré-requisitos

Você precisa dos seguintes itens:

  • Caminho para a chave da conta de serviço do projeto do GCP na máquina de desenvolvimento
  • O agente name (por exemplo, "brands/12345/agents/67890")

    Se você não souber o name do agente, consulte Listar todos os agentes de um marca.

  • ID do cliente do seu provedor de OAuth

  • Requisitos de desafio de código do provedor OAuth

  • Escopos do seu provedor de OAuth

Enviar a sugestão de solicitação de autenticação

Sugestão de solicitação de autenticação

Para autenticar um usuário,

  1. Gere o verificador de código e as strings de desafio de código para a solicitação do OAuth. Consulte seu provedor de OAuth para conferir os requisitos e as opções.
  2. Envie uma mensagem com a sugestão de solicitação de autenticação.
# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at

#     https://www.apache.org/licenses/LICENSE-2.0

# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This code sends a text message to the user with an authentication request suggestion
# that allows the user to authenticate with OAuth. It also has a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion

# Replace the __CONVERSATION_ID__ with a conversation id that you can send messages to
# Make sure a service account key file exists at ./service_account_key.json
# Replace the __CLIENT_ID__
# Replace the __CODE_CHALLENGE__
# Replace the __SCOPE__

curl
-X POST "https://businessmessages.googleapis.com/v1/conversations/__CONVERSATION_ID__/messages" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-messages" \
-H "$(oauth2l header --json ./service_account_key.json businessmessages)" \
-d "{
    'messageId': '$(uuidgen)',
    'text': 'Sign in to continue the conversation.',
    'fallback': 'Visit support.growingtreebank.com to continue.',
    'suggestions': [
      {
        'authenticationRequest': {
          'oauth': {
            'clientId': '__CLIENT_ID__',
            'codeChallenge': '__CODE_CHALLENGE__',
            'scopes': [
              '__SCOPE__',
            ],
          },
        },
      },
    ],
    'representative': {
      'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
      'displayName': 'Chatbot',
      'representativeType': 'BOT'
    }
  }"


/**
 * This code sends a text message to the user with an authentication request suggestion
 * that allows the user to authenticate with OAuth. It also has a fallback text.
 * Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
 * Business Messages client library.
 */


/**
 * Before continuing, learn more about the prerequisites for authenticating
 * with OAuth at: https://developers.google.com/business-communications/business-messages/guides/how-to/integrate/oauth?hl=en
 *
 * Edit the values below:
 */

const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = 'EDIT_HERE';
const OAUTH_CLIENT_ID = 'EDIT_HERE';
const OAUTH_CODE_CHALLENGE = 'EDIT_HERE';
const OAUTH_SCOPE = 'EDIT_HERE';

const businessmessages = require('businessmessages');
const uuidv4 = require('uuid').v4;
const {google} = require('googleapis');

// Initialize the Business Messages API
const bmApi = new businessmessages.businessmessages_v1.Businessmessages({});

// Set the scope that we need for the Business Messages API
const scopes = [
 
'https://www.googleapis.com/auth/businessmessages',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

/**
 * Posts a message to the Business Messages API along with an authentication request.
 *
 * @param {string} conversationId The unique id for this user and agent.
 * @param {string} representativeType A value of BOT or HUMAN.
 */

async
function sendMessage(conversationId, representativeType) {
 
const authClient = await initCredentials();

 
if (authClient) {
   
// Create the payload for sending a message along with an authentication request
   
const apiParams = {
      auth
: authClient,
      parent
: 'conversations/' + conversationId,
      resource
: {
        messageId
: uuidv4(),
        representative
: {
          representativeType
: representativeType,
       
},
        fallback
: 'Visit support.growingtreebank.com to continue.',
        text
: 'Sign in to continue the conversation.',
        suggestions
: [
         
{
            authenticationRequest
: {
              oauth
: {
                clientId
: OAUTH_CLIENT_ID,
                codeChallenge
: OAUTH_CODE_CHALLENGE,
                scopes
: [OAUTH_SCOPE]
             
}
           
}
         
},
       
],
     
},
   
};

   
// Call the message create function using the
   
// Business Messages client library
    bmApi
.conversations.messages.create(apiParams,
     
{auth: authClient}, (err, response) => {
      console
.log(err);
      console
.log(response);
   
});
 
}
 
else {
    console
.log('Authentication failure.');
 
}
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */

 async
function initCredentials() {
 
// configure a JWT auth client
 
const authClient = new google.auth.JWT(
    privatekey
.client_email,
   
null,
    privatekey
.private_key,
    scopes
,
 
);

 
return new Promise(function(resolve, reject) {
   
// authenticate request
    authClient
.authorize(function(err, tokens) {
     
if (err) {
        reject
(false);
     
} else {
        resolve
(authClient);
     
}
   
});
 
});
}

sendMessage
(CONVERSATION_ID, 'BOT');

"""Sends a text message to the user with an authentication request suggestion.

It allows the user to authenticate with OAuth and has a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#authentication-request-suggestion

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""


import uuid

from businessmessages import businessmessages_v1_client as bm_client
from businessmessages.businessmessages_v1_messages import BusinessMessagesAuthenticationRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesAuthenticationRequestOauth
from businessmessages.businessmessages_v1_messages import BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials

# Before continuing, learn more about the prerequisites for authenticating
# with OAuth at: https://developers.google.com/business-communications/business-messages/guides/how-to/integrate/oauth?hl=en

# Edit the values below:
path_to_service_account_key
= './service_account_key.json'
conversation_id
= 'EDIT_HERE'
oauth_client_id
= 'EDIT_HERE'
oauth_code_challenge
= 'EDIT_HERE'
oauth_scope
= 'EDIT_HERE'

credentials
= ServiceAccountCredentials.from_json_keyfile_name(
    path_to_service_account_key
,
    scopes
=['https://www.googleapis.com/auth/businessmessages'])

client
= bm_client.BusinessmessagesV1(credentials=credentials)

representative_type_as_string
= 'BOT'
if representative_type_as_string == 'BOT':
  representative_type
= BusinessMessagesRepresentative.RepresentativeTypeValueValuesEnum.BOT
else:
  representative_type
= BusinessMessagesRepresentative.RepresentativeTypeValueValuesEnum.HUMAN

# Create a text message with an authentication request
message
= BusinessMessagesMessage(
    messageId
=str(uuid.uuid4().int),
    representative
=BusinessMessagesRepresentative(
        representativeType
=representative_type
   
),
    text
='Sign in to continue the conversation.',
    fallback
='Visit support.growingtreebank.com to continue.',
    suggestions
=[
       
BusinessMessagesSuggestion(
            authenticationRequest
=BusinessMessagesAuthenticationRequest(
                oauth
=BusinessMessagesAuthenticationRequestOauth(
                    clientId
=oauth_client_id,
                    codeChallenge
=oauth_code_challenge,
                    scopes
=[oauth_scope])
               
)
           
),
       
]
   
)

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

# Send the message
bm_client
.BusinessmessagesV1.ConversationsMessagesService(
    client
=client).Create(request=create_request)
  1. Quando o usuário tocar na sugestão e fizer login, você receber um no webhook do agente. Recupere o código de autorização do authenticationResponse.code.

Depois de receber a mensagem, você poderá trocar o código de autorização e o código para um token de acesso do seu provedor OAuth. Você pode acessar os dados do usuário com o token de acesso.

Para acessar um exemplo de conversa com autenticação, incluindo exemplos de código, consulte Autentique o usuário.