Protokół OAuth umożliwia agentom weryfikację użytkowników i tożsamości i udostępnianie spersonalizowanych informacji w rozmowach. Gdy użytkownik loguje się jako zaufany dostawca OAuth, agenty mają dostęp do danych użytkowników, co umożliwia szybkie uzyskiwanie odpowiedzi dzięki automatyzacji i oszczędzanie czasu dla agentów na żywo.
Business Messages obsługuje OAuth 2.0 za pomocą sugestii uwierzytelniania, która umożliwia użytkownikom logowanie się w usłudze OAuth skonfigurowanej dla agenta. Gdy użytkownik się zaloguje, aplikacja Business Messages przekazuje kod autoryzacji do agenta jako wiadomość.
Gdy otrzymasz kod autoryzacji od dostawcy OAuth, możesz przeprowadzić integrację z interfejsami API, aby uzyskać dostęp do procesów rozmowy, które wymagają informacji o tożsamości użytkownika. Pamiętaj, że każda usługa, z której korzystasz, ma własne warunki korzystania.
Skonfiguruj OAuth dla agenta
Aby włączyć sugestię żądania uwierzytelniania dla agenta, musisz najpierw skonfigurować OAuth.
Aby określić konfigurację OAuth, wyślij żądanie PATCH za pomocą interfejsu Business Communications API, aby zaktualizować pole endpointUrl
agenta.
Gdy określisz adres URL punktu końcowego, musisz zapisać identyfikatory URI przekierowania dla agenta i zaktualizować identyfikatory URI przekierowania w informacjach o dostawcy OAuth.
Wymagania wstępne
Potrzebujesz tych elementów:
- Dostawca protokołu OAuth zgodny ze specyfikacją OAuth 2.0
- Ścieżka do klucza konta usługi GCP na komputerze programistycznym
Agent
name
(np. &&tt;brands/12345/agents/67890")Jeśli nie znasz agenta
name
, zapoznaj się z sekcją Wyświetlanie wszystkich agentów marki.URL punktu końcowego, w którym użytkownicy logują się w usłudze OAuth
Wysyłanie prośby o aktualizację
Aby zaktualizować agenta, uruchom to polecenie. Zastąp zmienne wartościami określonymi w sekcji Wymagania wstępne.
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', }, }, }"
Aktualizowanie identyfikatorów URI przekierowania
Teraz gdy agent OAuth jest już skonfigurowany, musisz dodać 4 identyfikatory URI przekierowania do dostawcy 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&
W informacjach o dostawcy protokołu OAuth musisz uwzględnić wszystkie przekierowania.
Proces aktualizowania identyfikatorów URI przekierowań różni się w zależności od dostawcy OAuth. Instrukcje znajdziesz od dostawcy OAuth.
Teraz gdy protokół OAuth jest skonfigurowany dla agenta, możesz zweryfikować użytkowników za pomocą sugestii uwierzytelniania.
Uwierzytelnianie użytkownika
Gdy skonfigurujesz protokół OAuth dla agenta, możesz poprosić użytkowników o zalogowanie się przy użyciu sugestii uwierzytelniania.
Wymagania wstępne
Potrzebujesz tych elementów:
- Ścieżka do klucza konta usługi GCP na komputerze programistycznym
Agent
name
(np. &&tt;brands/12345/agents/67890")Jeśli nie znasz agenta
name
, zapoznaj się z sekcją Wyświetlanie wszystkich agentów marki.Identyfikator klienta od dostawcy OAuth
Wymagania dotyczące testu zabezpieczającego od dostawcy technologii OAuth
Zakresy od dostawcy OAuth
Wysyłanie prośby o uwierzytelnienie
Aby uwierzytelnić użytkownika,
- Wygeneruj weryfikator kodu i ciągi kodu dla żądania OAuth. Skontaktuj się z dostawcą protokołu OAuth, aby uzyskać wymagania i opcje.
- Wyślij wiadomość z sugestią uwierzytelnienia.
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)
- Gdy użytkownik kliknie sugestię i zaloguje się, otrzymasz wiadomość w webhooku agenta. Pobierz kod autoryzacji z pola
authenticationResponse.code
.
Gdy otrzymasz wiadomość, możesz wymienić kod autoryzacji i weryfikator kodów na token dostępu u dostawcy OAuth. Za pomocą tokena dostępu możesz uzyskać dostęp do danych użytkownika.
Przykładową rozmowę z uwierzytelnianiem, w tym z przykładowym kodem, znajdziesz w artykule Uwierzytelnianie użytkownika.