S'authentifier avec OAuth

OAuth permet aux agents de valider les identités des utilisateurs et de fournir des informations personnalisées dans les conversations de manière sécurisée. En demandant aux utilisateurs de se connecter à un fournisseur OAuth de confiance, les agents peuvent accéder aux données utilisateur. Cela leur permet d'obtenir des réponses rapides grâce à l'automatisation et de faire gagner du temps aux agents en direct.

Business Messages est compatible avec OAuth 2.0 avec la suggestion de requête d'authentification, qui invite les utilisateurs à se connecter à un fournisseur OAuth que vous configurez pour l'agent. Une fois que l'utilisateur s'est connecté avec succès, Business Messages transmet un code d'autorisation à l'agent en tant que message.

Une fois que vous disposez du code d'autorisation du fournisseur OAuth, vous pouvez intégrer ses API et gérer les flux de conversation qui nécessitent des informations sur l'identité de l'utilisateur. N'oubliez pas que chaque service avec lequel vous interagissez possède ses propres conditions d'utilisation.

Configurer OAuth pour un agent

Pour activer la suggestion de requête d'authentification pour un agent, vous devez d'abord configurer OAuth.

Pour spécifier une configuration OAuth, envoyez une requête PATCH à l'aide de l'API Business Communications afin de mettre à jour le champ endpointUrl de l'agent.

Après avoir spécifié l'URL du point de terminaison, vous devez stocker les URI de redirection de votre agent et mettre à jour les URI de redirection dans les informations de votre fournisseur OAuth.

Conditions préalables

Vous avez besoin des éléments suivants:

• Un fournisseur OAuth respectant la spécification OAuth 2.0
• Chemin d'accès à la clé de compte de service de votre projet GCP sur votre machine de développement

• Agent name (par exemple, "brands/12345/agents/67890"")

  Si vous ne connaissez pas le name de l'agent, consultez Répertorier tous les agents d'une marque.

• URL du point de terminaison à laquelle les utilisateurs se connectent au fournisseur OAuth

Envoyer la demande de mise à jour

Pour mettre à jour l'agent, exécutez la commande suivante. Remplacez les variables par les valeurs que vous avez identifiées dans Conditions préalables.

Remarque:Une fois l'agent validé, vous ne pouvez pas mettre à jour sa configuration d'autorisation. Si vous devez mettre à jour la configuration d'un agent validé, contactez-nous. (Vous devez d'abord vous connecter avec un compte Google Business Messages. Pour ouvrir un compte, consultez S'inscrire à 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',
        },
    },
}"

Mettre à jour les URI de redirection

Maintenant que OAuth est configuré pour l'agent, vous devez ajouter quatre URI de redirection à votre fournisseur 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&

Vous devez inclure toutes les URL de redirection dans les informations sur votre fournisseur OAuth.

La procédure de mise à jour des URI de redirection varie selon le fournisseur OAuth. Consultez votre fournisseur OAuth pour obtenir des instructions.

Maintenant qu'OAuth est configuré pour votre agent, vous pouvez authentifier les utilisateurs à l'aide de la suggestion de requête d'authentification.

Authentifier un utilisateur

Après avoir configuré OAuth pour un agent, vous pouvez inviter les utilisateurs à se connecter à l'aide de la suggestion de requête d'authentification.

Conditions préalables

Vous avez besoin des éléments suivants:

• Chemin d'accès à la clé de compte de service de votre projet GCP sur votre machine de développement

• Agent name (par exemple, "brands/12345/agents/67890"")

  Si vous ne connaissez pas le name de l'agent, consultez Répertorier tous les agents d'une marque.

• ID client de votre fournisseur OAuth

• Exigences concernant l'authentification via le code de votre fournisseur OAuth

• Champs d'application de votre fournisseur OAuth

Envoyer la suggestion de demande d'authentification

Pour authentifier un utilisateur :

1. Générez l'outil de vérification du code et les chaînes d'authentification à la ligne pour la requête OAuth. Contactez votre fournisseur OAuth pour connaître les exigences et les options.
2. Envoyez un message contenant la suggestion de demande d'authentification.

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. Lorsque l'utilisateur appuie sur la suggestion et se connecte correctement, vous recevez un message au webhook de votre agent. Récupérez le code d'autorisation dans le champ authenticationResponse.code.

Une fois le message reçu, vous pouvez échanger le code d'autorisation et l'outil de vérification du code contre un jeton d'accès provenant de votre fournisseur OAuth. Vous pouvez accéder aux données utilisateur avec le jeton d'accès.

Pour obtenir un exemple de conversation avec authentification, y compris des exemples de code, consultez Authentifier l'utilisateur.