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 --jsonPATH_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
Para autenticar um usuário,
- 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.
- 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)
- 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.