يتيح OAuth للوكلاء التحقُّق من هويات المستخدمين وتقديم معلومات مُخصّصة في المحادثات بطريقة آمنة. من خلال مطالبة المستخدمين بتسجيل الدخول إلى موفّر OAuth موثوق، يمكن للوكلاء الوصول إلى بيانات المستخدم التي يمكنها المساعدة في تقديم إجابات سريعة من خلال أساليب مبرمَجة وتوفير الوقت للوكلاء المباشرين.
يتيح تطبيق "الرسائل التجارية" بروتوكول OAuth 2.0 مع اقتراح طلب المصادقة، الذي يطلب من المستخدمين تسجيل الدخول إلى موفّر بروتوكول OAuth الذي تضبطه للوكيل. بعد أن يسجِّل المستخدم دخوله بنجاح، يُرسل تطبيق "الرسائل التجارية" رمز تفويض إلى الوكيل كرسالة مرة أخرى.
بعد الحصول على رمز التفويض من موفّر خدمة OAuth، يمكنك الدمج مع واجهات برمجة التطبيقات الخاصة به ودعم تدفقات المحادثات التي تتطلب معلومات هوية المستخدم. كل خدمة تتفاعل معها لها بنود استخدام خاصة بها.
إعداد OAuth لوكيل
لتفعيل اقتراح طلب المصادقة لأحد الوكلاء، يجب إعداد OAuth أولاً.
لتحديد إعداد OAuth، عليك إجراء طلب PATCH
باستخدام واجهة برمجة تطبيقات
اتصالات الأنشطة التجارية
لتحديث الحقل endpointUrl
للوكيل.
بعد تحديد عنوان URL لنقطة النهاية، يجب تخزين معرِّفات الموارد المنتظمة (URI) الخاصة بوكيلك وتعديل معرِّفات الموارد المنتظمة (URI) في معلومات موفّر خدمة OAuth.
المتطلبات الأساسية
ستحتاج إلى ما يلي:
- موفِّر بروتوكول OAuth الذي يتبع مواصفات OAuth 2.0
- المسار إلى مفتاح حساب خدمة Google Cloud Platform الخاص بك على جهاز التطوير
الوكيل
name
(مثلاً، "brand;brands/12345/agents/67890")إذا كنت لا تعرف الوكيل
name
، يمكنك الاطّلاع على إدراج كل الوكلاء لعلامة تجارية.عنوان URL لنقطة النهاية حيث يسجّل المستخدمون الدخول إلى موفّر OAuth
إرسال طلب التعديل
لتحديث الوكيل، شغِّل الأمر التالي. استبدِل المتغيّرات بالقيم التي حدّدتها في المتطلبات الأساسية.
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', }, }, }"
تعديل معرفات الموارد المنتظمة (URI) لإعادة التوجيه
الآن وبعد أن تم إعداد OAuth للوكيل، عليك إضافة أربعة معرّفات URI لإعادة التوجيه إلى موفّر 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&
يجب تضمين جميع عناوين URL لإعادة التوجيه في معلومات موفّر OAuth.
تختلف عملية تعديل معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه حسب موفِّر OAuth. راجع موفِّر OAuth للحصول على التعليمات.
الآن وبعد إعداد بروتوكول OAuth للوكيل، يمكنك مصادقة المستخدمين باستخدام اقتراح طلب المصادقة.
مصادقة مستخدم
بعد ضبط OAuth لوكيل، يمكنك مطالبة المستخدمين بتسجيل الدخول باستخدام اقتراح طلب المصادقة.
المتطلبات الأساسية
ستحتاج إلى ما يلي:
- المسار إلى مفتاح حساب خدمة Google Cloud Platform الخاص بك على جهاز التطوير
الوكيل
name
(مثلاً، "brand;brands/12345/agents/67890")إذا كنت لا تعرف الوكيل
name
، يمكنك الاطّلاع على إدراج كل الوكلاء لعلامة تجارية.معرِّف العميل من موفّر خدمة OAuth
متطلبات اختبار الرمز من مزوّد OAuth
نطاقات من مزوّد OAuth
إرسال اقتراح طلب المصادقة
لمصادقة مستخدم،
- يمكنك إنشاء أداة التحقُّق من الرموز وسلاسل اختبار الرمز لطلب OAuth. ارجع إلى موفِّر OAuth لمعرفة المتطلبات والخيارات.
- يمكنك إرسال رسالة مع اقتراح طلب المصادقة.
عنوان 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)
- عندما ينقر المستخدم على الاقتراح وتسجيل الدخول بنجاح، ستتلقّى
رسالة
على الرد التلقائي على الويب الخاص بوكيلك. يمكنك استرداد رمز التفويض من الحقل
authenticationResponse.code
.
بعد تلقّي الرسالة، يمكنك استبدال رمز التفويض ورمز التحقق من الرمز المميّز للوصول من موفّر OAuth. يمكنك الوصول إلى بيانات المستخدم من خلال رمز الدخول.
للاطّلاع على نموذج محادثة باستخدام المصادقة، بما في ذلك نماذج الرموز، يُرجى الاطّلاع على مصادقة المستخدم.