Mit OAuth können Agents die Identitäten zu erkennen und personalisierte Informationen in Gesprächen sicher aufzubewahren. Nutzer müssen sich in einem vertrauenswürdigen OAuth-Anbieters können Agents auf Nutzerdaten zugreifen, um schnell durch Automatisierung zu beantworten und Zeit für Kundenservicemitarbeiter zu sparen.
Business Messages unterstützt OAuth 2.0 mit der Authentifizierungsanfrage Vorschlag, Nutzer werden aufgefordert, sich bei einem OAuth-Anbieter anzumelden, den Sie für den Agent konfiguriert haben. Nachdem sich der Nutzer erfolgreich angemeldet hat, gibt Business Messages eine Autorisierung weiter. Code als Nachricht an den Kundenservicemitarbeiter zurücksenden.
Sobald Sie den Autorisierungscode vom OAuth-Anbieter haben, können Sie können in ihre APIs integriert werden und ermöglichen es, Gesprächsabläufe zu unterstützen, bei denen Identitätsdaten. Beachten Sie, dass jeder Dienst, mit dem Sie interagieren, eigenen Nutzungsbedingungen.
OAuth für einen Agent konfigurieren
Um den Vorschlag für die Authentifizierungsanfrage für einen Agent zu aktivieren, müssen Sie bevor Sie 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 Ihre und aktualisieren Sie die Weiterleitungs-URIs in den Informationen Ihres OAuth-Anbieters.
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
Den Agent
name
, z. B. „brands/12345/agents/67890“Wenn Sie den
name
des Agents nicht kennen, lesen Sie Alle Agents für einen brand [Marke].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. Variablen durch Werte ersetzen die Sie unter Voraussetzungen identifiziert 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 OAuth für den Agent konfiguriert wurde, müssen Sie vier Weiterleitungs-URIs hinzufügen an Ihren OAuth-Anbieter:
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 Ihren OAuth-Anbieterinformationen angeben.
Das Verfahren zum Aktualisieren von Weiterleitungs-URIs variiert je nach OAuth-Anbieter. Weitere Informationen finden Sie in der OAuth-Anbieter.
Nachdem OAuth für den Agent konfiguriert wurde, können Sie sich authentifizieren, um sich zu authentifizieren. Nutzer durch die Authentifizierungsanfrage Vorschlag
Nutzer authentifizieren
Nachdem Sie OAuth für einen Agent konfiguriert haben, können Sie Nutzer auffordern, sich mit dem Authentifizierungsanfrage Vorschlag angezeigt.
Vorbereitung
Sie benötigen Folgendes:
- Pfad zum Dienstkontoschlüssel Ihres GCP-Projekts auf Ihrem Entwicklungscomputer
Den Agent
name
, z. B. „brands/12345/agents/67890“Wenn Sie den
name
des Agents nicht kennen, lesen Sie Alle Agents für einen brand [Marke].Client-ID von deinem OAuth-Anbieter
Anforderungen an die Code-Challenge Ihres OAuth-Anbieters
Bereiche von Ihrem OAuth-Anbieter
Vorschlag für Authentifizierungsanfrage senden
Um einen Nutzer zu authentifizieren,
- Generieren Sie die Codeprüfungs- und Code-Abfragestrings für die OAuth-Anfrage. Informationen zu den Anforderungen und Optionen erhalten Sie von Ihrem OAuth-Anbieter.
- Sende 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 erfolgreich anmeldet,
empfangen
an den Webhook Ihres Agents gesendet. Rufen Sie den Autorisierungscode auf der
authenticationResponse.code
.
Sobald Sie die Nachricht erhalten haben, können Sie den Autorisierungscode und ‐code austauschen Prüfer für ein Zugriffstoken von Ihrem OAuth-Anbieter. Sie können auf Nutzerdaten zugreifen durch das Zugriffstoken.
Ein Beispiel für eine Unterhaltung mit Authentifizierung sowie Codebeispiele finden Sie unter Authentifizieren Sie die Nutzer.