Autentica con OAuth

OAuth permite a los agentes verificar las identidades de los usuarios y proporcionar información personalizada en las conversaciones de manera segura. Cuando los usuarios acceden a un proveedor de OAuth de confianza, los agentes pueden acceder a los datos del usuario que pueden ayudar a proporcionar respuestas rápidas a través de la automatización y ahorrarles tiempo a los agentes humanos.

Business Messages admite OAuth 2.0 con la sugerencia de solicitud de autenticación, que solicita a los usuarios que accedan a un proveedor de OAuth que configures para el agente. Después de que el usuario accede correctamente, Business Messages pasa un código de autorización al agente como un mensaje.

Una vez que tengas el código de autorización del proveedor de OAuth, podrás integrarlo a sus API y admitir los flujos de conversación que requieran información de identidad del usuario. Ten en cuenta que cada servicio con el que interactúas tiene sus propias condiciones de uso.

Configura OAuth para un agente

Para habilitar la sugerencia de solicitud de autenticación de un agente, primero debes configurar OAuth.

Para especificar una configuración de OAuth, realiza una solicitud PATCH con la API de Business Communications a fin de actualizar el campo endpointUrl del agente.

Después de especificar la URL de extremo, debes almacenar los URI de redireccionamiento para tu agente y actualizar los URI de redireccionamiento en la información de tu proveedor de OAuth.

Requisitos previos

Necesitas los siguientes elementos:

• Un proveedor de OAuth que sigue la especificación de OAuth 2.0
• Ruta de acceso a la clave de la cuenta de servicio de tu proyecto de GCP en la máquina de desarrollo

• El agente name (por ejemplo, &brands/12345/agents/67890")

  Si no conoces el name del agente, consulta Enumera todos los agentes de una marca.

• La URL de extremo en la que los usuarios acceden al proveedor de OAuth

Envía la solicitud de actualización

Para actualizar el agente, ejecuta el siguiente comando. Reemplaza las variables con valores que hayas identificado en Requisitos previos.

Nota: No puedes actualizar la configuración de autorización de un agente después de que se verifica. Si necesitas actualizar la configuración de un agente verificado, comunícate con nosotros. (Primero debes acceder con una Cuenta de Google de Business Messages. Para registrarte en una cuenta, consulta Regístrate con Business Messages.

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',
        },
    },
}"

Actualizar URI de redireccionamiento

Ahora que OAuth está configurado para el agente, debes agregar cuatro URI de redireccionamiento a tu proveedor de 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&

Debes incluir todas las URL de redireccionamiento en la información de tu proveedor de OAuth.

El proceso para actualizar los URI de redireccionamiento varía según el proveedor de OAuth. Consulta a tu proveedor de OAuth para obtener instrucciones.

Ahora que OAuth está configurado para tu agente, puedes autenticar usuarios con la sugerencia de solicitud de autenticación.

Autentica un usuario

Después de configurar OAuth para un agente, puedes solicitar a los usuarios que accedan con la sugerencia de solicitud de autenticación.

Requisitos previos

Necesitas los siguientes elementos:

• Ruta de acceso a la clave de la cuenta de servicio de tu proyecto de GCP en la máquina de desarrollo

• El agente name (por ejemplo, &brands/12345/agents/67890")

  Si no conoces el name del agente, consulta Enumera todos los agentes de una marca.

• ID de cliente de tu proveedor de OAuth

• Requisitos del desafío de código de tu proveedor de OAuth

• Alcances de tu proveedor de OAuth

Envía la sugerencia de solicitud de autenticación

Para autenticar un usuario,

1. Genera el verificador de código y las strings de desafío de código para la solicitud de OAuth. Consulta a tu proveedor de OAuth para conocer los requisitos y las opciones.
2. Envía un mensaje con la sugerencia de solicitud de autenticación.

cURL

# 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'
    }
  }"
send-message-authentication-request-suggestion.sh

Node.js

/**
 * 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');
send-message-authentication-request-suggestion.js

Python

"""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)
send-message-authentication-request-suggestion.py

1. Cuando el usuario presiona la sugerencia y accede correctamente, recibes un mensaje en el webhook de tu agente. Recupera el código de autorización del campo authenticationResponse.code.

Una vez que recibas el mensaje, puedes intercambiar el código de autorización y el verificador de código por un token de acceso de tu proveedor de OAuth. Puedes acceder a los datos del usuario con el token de acceso.

Para ver una conversación de muestra con autenticación, incluidas muestras de código, consulta Autentica el usuario.