OAuth memungkinkan agen memverifikasi identitas pengguna dan memberikan informasi yang dipersonalisasi dalam percakapan dengan cara yang aman. Dengan meminta pengguna login ke penyedia OAuth tepercaya, agen dapat mengakses data pengguna yang dapat membantu memberikan jawaban cepat melalui otomatisasi dan menghemat waktu untuk agen langsung.
Business Messages mendukung OAuth 2.0 dengan saran permintaan Autentikasi, yang meminta pengguna untuk login ke penyedia OAuth yang Anda konfigurasikan untuk agen. Setelah pengguna berhasil login, Business Messages akan meneruskan kembali kode otorisasi ke agen sebagai pesan.
Setelah mendapatkan kode otorisasi dari penyedia OAuth, Anda dapat berintegrasi dengan API mereka dan mendukung alur percakapan yang memerlukan informasi identitas pengguna. Perlu diingat bahwa setiap layanan yang berinteraksi dengan Anda memiliki persyaratan penggunaan sendiri.
Mengonfigurasi OAuth untuk agen
Untuk mengaktifkan saran permintaan Authentication untuk agen, Anda harus mengonfigurasi OAuth terlebih dahulu.
Untuk menentukan konfigurasi OAuth, Anda membuat permintaan PATCH dengan Business Communications API untuk memperbarui kolom endpointUrl
agen.
Setelah menentukan URL endpoint, Anda perlu menyimpan URI pengalihan untuk agen dan memperbarui URI pengalihan di informasi penyedia OAuth Anda.
Prasyarat
Anda memerlukan item berikut:
- Penyedia OAuth yang mengikuti spesifikasi OAuth 2.0
- Jalur kunci akun layanan project GCP Anda di mesin pengembangan
Agen
name
(misalnya, "brands/12345/agents/67890")Jika Anda tidak mengetahui
name
agen, lihat Mencantumkan semua agen untuk merek.URL endpoint tempat pengguna login ke penyedia OAuth
Mengirim permintaan update
Untuk memperbarui agen, jalankan perintah berikut. Ganti variabel dengan nilai yang Anda identifikasi di Prasyarat.
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', }, }, }"
Mengupdate URI pengalihan
Setelah OAuth dikonfigurasi untuk agen, Anda perlu menambahkan empat URI pengalihan ke penyedia OAuth Anda:
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&
Anda harus menyertakan semua URL alihan dalam informasi penyedia OAuth Anda.
Proses untuk memperbarui URI pengalihan bervariasi menurut penyedia OAuth. Lihat penyedia OAuth Anda untuk mendapatkan petunjuk.
Setelah OAuth dikonfigurasi untuk agen Anda, Anda dapat mengautentikasi pengguna dengan saran permintaan Authentication.
Mengautentikasi pengguna
Setelah mengonfigurasi OAuth untuk agen, Anda dapat meminta pengguna untuk login dengan saran permintaan Authentication.
Prasyarat
Anda memerlukan item berikut:
- Jalur kunci akun layanan project GCP Anda di mesin pengembangan
Agen
name
(misalnya, "brands/12345/agents/67890")Jika Anda tidak mengetahui
name
agen, lihat Mencantumkan semua agen untuk merek.Client ID dari penyedia OAuth Anda
Persyaratan verifikasi kode dari penyedia OAuth Anda
Cakupan dari penyedia OAuth Anda
Mengirim saran permintaan autentikasi
Untuk mengautentikasi pengguna,
- Membuat pemverifikasi kode dan string verifikasi kode untuk permintaan OAuth. Hubungi penyedia OAuth Anda untuk mengetahui persyaratan dan opsi.
- Kirim pesan dengan saran permintaan Authentication.
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)
- Saat pengguna mengetuk saran dan berhasil login, Anda
menerima
pesan di webhook agen Anda. Ambil kode otorisasi dari kolom
authenticationResponse.code
.
Setelah menerima pesan, Anda dapat menukar kode otorisasi dan pemverifikasi kode untuk token akses dari penyedia OAuth Anda. Anda dapat mengakses data pengguna dengan token akses.
Untuk contoh percakapan dengan autentikasi, termasuk contoh kode, lihat Mengautentikasi pengguna.