Mit OAuth können Agents Nutzeridentitäten bestätigen und auf sichere Weise personalisierte Informationen in Unterhaltungen bereitstellen. Wenn sich Nutzer bei einem vertrauenswürdigen OAuth-Anbieter anmelden, können Agents auf Nutzerdaten zugreifen, um durch Automatisierung schnelle Antworten zu geben und den Kundenservicemitarbeitern Zeit zu sparen.
Business Messages unterstützt OAuth 2.0 mit dem Vorschlag für die Authentifizierung. Dadurch werden Nutzer aufgefordert, sich bei einem für den Agent konfigurierten OAuth-Anbieter anzumelden. Nachdem sich der Nutzer angemeldet hat, gibt Business Messages einen Autorisierungscode als Nachricht an den Agent zurück.
Sobald Sie den Autorisierungscode vom OAuth-Anbieter haben, können Sie diesen in seine APIs einbinden und Gesprächsabläufe unterstützen, für die Informationen zur Nutzeridentität erforderlich sind. Beachten Sie, dass jeder Dienst, mit dem Sie interagieren, eigene Nutzungsbedingungen hat.
OAuth für einen Agent konfigurieren
Zum Vorschlagen der Authentifizierungsanfrage für einen Agent müssen Sie zuerst OAuth konfigurieren.
Um eine OAuth-Konfiguration anzugeben, stellen Sie eine PATCH-Anfrage mit der Business Communications API, um das Feld endpointUrl des Agents zu aktualisieren.
Nachdem Sie die Endpunkt-URL angegeben haben, müssen Sie Weiterleitungs-URIs für Ihren Agent speichern und die Weiterleitungs-URIs in den Informationen Ihres OAuth-Anbieters aktualisieren.
Voraussetzungen
Sie benötigen Folgendes:
- Ein OAuth-Anbieter, der der OAuth 2.0-Spezifikation entspricht
- Pfad zum Dienstkontoschlüssel Ihres GCP-Projekts auf Ihrem Entwicklungscomputer
Der Agent
name(z. B. "brands/12345/agents/67890")Wenn Sie das
namedes Agents nicht kennen, lesen Sie Alle Agents für eine Marke auflisten.Die Endpunkt-URL, unter der sich Nutzer beim OAuth-Anbieter anmelden
Aktualisierungsanfrage senden
Führen Sie den folgenden Befehl aus, um den Agent zu aktualisieren. Ersetzen Sie Variablen durch Werte, die Sie unter Voraussetzungen angegeben haben.
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 Sie OAuth für den Agent konfiguriert haben, müssen Sie Ihrem OAuth-Anbieter vier Weiterleitungs-URIs hinzufügen:
https://business.google.com/callbackhttps://business.google.com/callback?https://business.google.com/message?az-intent-type=1https://business.google.com/message?az-intent-type=1&
Sie müssen alle Weiterleitungs-URLs in den Informationen Ihres OAuth-Anbieters angeben.
Die Vorgehensweise zum Aktualisieren von Weiterleitungs-URIs variiert je nach OAuth-Anbieter. Eine Anleitung dazu erhalten Sie von Ihrem OAuth-Anbieter.
Nachdem Sie OAuth für Ihren Agent konfiguriert haben, können Sie mit dem Vorschlag für die Authentifizierung Nutzer authentifizieren.
Nutzer authentifizieren
Nachdem Sie OAuth für einen Agent konfiguriert haben, können Sie Nutzer auffordern, sich mit dem Vorschlag für die Authentifizierungsanfrage anzumelden.
Voraussetzungen
Sie benötigen Folgendes:
- Pfad zum Dienstkontoschlüssel Ihres GCP-Projekts auf Ihrem Entwicklungscomputer
Der Agent
name(z. B. "brands/12345/agents/67890")Wenn Sie das
namedes Agents nicht kennen, lesen Sie Alle Agents für eine Marke auflisten.Client-ID von Ihrem OAuth-Anbieter
Anforderungen für die Code-Bestätigung von Ihrem OAuth-Anbieter
Bereiche von Ihrem OAuth-Anbieter
Authentifizierungsanfrage senden
So authentifizieren Sie einen Nutzer:
- Generieren Sie den Code- und Code-Herausforderungs-Strings für die OAuth-Anfrage. Informationen zu den Anforderungen und Optionen finden Sie bei Ihrem OAuth-Anbieter.
- Senden Sie eine Nachricht mit dem Vorschlag zur 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'
}
}"
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');
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)
- Wenn der Nutzer auf den Vorschlag tippt und sich anmeldet, erhältst du eine Nachrichtim Webhook deines Agents. Rufen Sie den Autorisierungscode aus dem Feld
authenticationResponse.codeab.
Nachdem Sie die Nachricht erhalten haben, können Sie den Autorisierungscode und die Codeüberprüfung gegen ein Zugriffstoken von Ihrem OAuth-Anbieter austauschen. Sie können mit dem Zugriffstoken auf Nutzerdaten zugreifen.
Ein Beispiel für eine Unterhaltung mit Authentifizierung, einschließlich Codebeispielen, finden Sie unter Nutzer authentifizieren.