Mit OAuth authentifizieren

Mit OAuth können Agenten die Identität von Nutzern überprüfen und personalisierte Informationen in Unterhaltungen auf sichere Weise bereitstellen. Wenn sich Nutzer bei einem vertrauenswürdigen OAuth-Anbieter anmelden, können Agenten auf Nutzerdaten zugreifen, die helfen, schnell Antworten über die Automatisierung zu geben und Zeit für Live-Agenten zu sparen.

Business Messages unterstützt OAuth 2.0 mit dem Vorschlag für eine Authentifizierungsanfrage ,der Nutzer auffordert, sich bei einem OAuth-Anbieter anzumelden, den Sie für den Agenten konfigurieren. Nachdem sich der Nutzer erfolgreich angemeldet hat, übergibt Business Messages einen Autorisierungscode als Nachricht an den Agenten.

Sobald Sie den Autorisierungscode vom OAuth-Anbieter haben, können Sie ihn in Ihre APIs einbinden und Unterhaltungen unterstützen, für die Informationen zur Nutzeridentität erforderlich sind. Beachten Sie, dass für jeden Dienst, mit dem Sie interagieren, eigene Nutzungsbedingungen gelten.

OAuth für einen Agenten konfigurieren

Wenn Sie den Vorschlag für eine Authentifizierungsanfrage für einen Agenten aktivieren möchten, müssen Sie zuerst OAuth konfigurieren.

Um eine OAuth-Konfiguration anzugeben, senden Sie eine PATCH-Anfrage mit der Business Communications API um das Feld endpointUrl des Agenten zu aktualisieren.

Nachdem Sie die Endpunkt-URL angegeben haben, müssen Sie Weiterleitungs-URIs für Ihren Agenten speichern und die Weiterleitungs-URIs in den Informationen Ihres OAuth-Anbieters aktualisieren.

Vorbereitung

Sie benötigen Folgendes:

• Einen OAuth-Anbieter, der der OAuth 2.0-Spezifikation entspricht
• Pfad zum Dienstkontoschlüssel Ihres GCP-Projekts auf Ihrem Entwicklungscomputer

• Der name des Agenten (z. B. „brands/12345/agents/67890“)

  Wenn Sie den name des Agenten nicht kennen, lesen Sie Alle Agenten für eine Marke auflisten.

• Die Endpunkt-URL, über die sich Nutzer beim OAuth-Anbieter anmelden

Aktualisierungsanfrage senden

Führen Sie den folgenden Befehl aus, um den Agenten zu aktualisieren. Ersetzen Sie die Variablen durch die Werte die Sie unter Vorbereitungermittelt haben.

Hinweis: Die Autorisierungskonfiguration eines Agenten kann nicht mehr aktualisiert werden, nachdem der Agent überprüft wurde. Wenn Sie die Konfiguration für einen überprüften Agenten aktualisieren müssen, wenden Sie sich an uns. Sie müssen sich zuerst an melden mit einem Business Messages-Google-Konto. Informationen zum Registrieren eines Kontos finden Sie unter Bei Business Messages registrieren.

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

Weiterleitungs-URIs aktualisieren

Nachdem OAuth für den Agenten konfiguriert wurde, müssen Sie Ihrem OAuth-Anbieter vier Weiterleitungs-URIs hinzufügen:

• 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&

Sie müssen alle Weiterleitungs-URLs in den Informationen Ihres OAuth-Anbieters angeben.

Der Vorgang zum Aktualisieren von Weiterleitungs-URIs variiert je nach OAuth-Anbieter. Weitere Informationen finden Sie bei Ihrem OAuth-Anbieter.

Nachdem OAuth für Ihren Agenten konfiguriert wurde, können Sie Nutzer mit dem Vorschlag für eine Authentifizierungsanfrage authentifizieren.

Nutzer authentifizieren

Nachdem Sie OAuth für einen Agenten konfiguriert haben, können Sie Nutzer mit dem Vorschlag für eine Authentifizierungsanfrage auffordern, sich anzumelden.

Vorbereitung

Sie benötigen Folgendes:

• Pfad zum Dienstkontoschlüssel Ihres GCP-Projekts auf Ihrem Entwicklungscomputer

• Der name des Agenten (z. B. „brands/12345/agents/67890“)

  Wenn Sie den name des Agenten nicht kennen, lesen Sie Alle Agenten für eine Marke auflisten.

• Client-ID von Ihrem OAuth-Anbieter

• Anforderungen an die Code-Challenge von Ihrem OAuth-Anbieter

• Bereiche von Ihrem OAuth-Anbieter

Vorschlag für eine Authentifizierungsanfrage senden

So authentifizieren Sie einen Nutzer:

1. Generieren Sie die Strings für den Code-Verifier und die Code-Challenge für die OAuth-Anfrage. Informationen zu Anforderungen und Optionen finden Sie bei Ihrem OAuth-Anbieter.
2. Senden Sie eine Nachricht mit dem Vorschlag für eine Authentifizierungsanfrage.

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. Wenn der Nutzer auf den Vorschlag tippt und sich erfolgreich anmeldet, erhalten Sie eine Nachricht im Webhook Ihres Agenten. Rufen Sie den Autorisierungscode aus dem Feld authenticationResponse.code ab.

Sobald Sie die Nachricht erhalten haben, können Sie den Autorisierungscode und den Code-Verifier gegen ein Zugriffstoken von Ihrem OAuth-Anbieter eintauschen. Mit dem Zugriffstoken können Sie auf Nutzerdaten zugreifen.

Ein Beispiel für eine Unterhaltung mit Authentifizierung, einschließlich Codebeispielen, finden Sie unter Nutzer authentifizieren.