سنوقف ميزة "الرسائل التجارية من Google" نهائيًا في 31 يوليو 2024. يمكنك الاطّلاع على مزيد من المعلومات هنا.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

المصادقة باستخدام OAuth

يسمح بروتوكول OAuth للوكلاء بالتحقّق من هويات المستخدمين وتقديم معلومات مخصّصة في المحادثات بطريقة آمنة. ومن خلال مطالبة المستخدمين بتسجيل الدخول إلى موفّر OAuth موثوق به، يمكن للوكلاء الوصول إلى بيانات المستخدمين التي يمكن أن تساعد في تقديم إجابات سريعة من خلال التشغيل الآلي وتوفير وقت الوكلاء المباشرين.

تتيح "رسائل الأنشطة التجارية" استخدام OAuth 2.0 مع اقتراح طلب المصادقة، الذي يطلب من المستخدمين تسجيل الدخول إلى موفّر OAuth الذي تم إعداده للوكيل. بعد أن يسجّل المستخدم الدخول بنجاح، ترسل "الرسائل التجارية" رمز تفويض إلى الوكيل كرسالة.

بعد الحصول على رمز التفويض من موفّر OAuth، يمكنك الدمج مع واجهات برمجة التطبيقات الخاصة به وإتاحة مسارات المحادثات التي تتطلّب معلومات هوية المستخدم. يُرجى العِلم أنّ كل خدمة تتفاعل معها لها بنود استخدام خاصة بها.

ضبط بروتوكول OAuth لأحد العملاء

لتفعيل اقتراح طلب المصادقة لأحد الوكلاء، عليك أولاً ضبط OAuth.

لتحديد إعدادات OAuth، عليك إرسال طلب PATCH باستخدام Business Communications API لتعديل الحقل endpointUrl الخاص بالوكيل.

بعد تحديد عنوان URL لنقطة النهاية، عليك تخزين معرّفات الموارد الموحّدة لإعادة التوجيه الخاصة بالوكيل وتعديل معرّفات الموارد الموحّدة لإعادة التوجيه في معلومات مقدّم خدمة OAuth.

المتطلبات الأساسية

ستحتاج إلى العناصر التالية:

موفّر خدمة OAuth يتّبع مواصفات OAuth 2.0
مسار مفتاح حساب الخدمة لمشروعك على Google Cloud Platform (GCP) على جهاز التطوير
الوكيل name (على سبيل المثال، "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 (GCP) على جهاز التطوير
الوكيل name (على سبيل المثال، "brands/12345/agents/67890")

إذا كنت لا تعرف name الوكيل، يمكنك الاطّلاع على إدراج جميع الوكلاء لعلامة تجارية.
معرّف العميل من موفّر OAuth
متطلبات تحدّي الرمز من مقدّم خدمة OAuth
النطاقات من موفّر OAuth

إرسال اقتراح طلب المصادقة

اقتراح طلب المصادقة

لمصادقة مستخدم، اتّبِع الخطوات التالية:

أنشئ السلسلتَين code_verifier وcode_challenge لطلب 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'
    }
  }"send-message-authentication-request-suggestion.sh

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');send-message-authentication-request-suggestion.js

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)send-message-authentication-request-suggestion.py

عندما ينقر المستخدم على الاقتراح ويسجّل الدخول بنجاح، ستتلقّى رسالة في الويب هوك الخاص بالوكيل. استرجِع رمز التفويض من الحقل authenticationResponse.code.

بعد تلقّي الرسالة، يمكنك استبدال رمز التفويض ورمز التحقّق برمز دخول من مقدّم خدمة OAuth، ويمكنك الوصول إلى بيانات المستخدم باستخدام رمز الدخول.

للاطّلاع على محادثة نموذجية تتضمّن مصادقة، بما في ذلك نماذج الرموز، يُرجى الاطّلاع على مصادقة المستخدم.

المصادقة باستخدام OAuth تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

ضبط بروتوكول OAuth لأحد العملاء

المتطلبات الأساسية

إرسال طلب التعديل

تعديل معرّفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه

مصادقة مستخدم

المتطلبات الأساسية

إرسال اقتراح طلب المصادقة

cURL

Node.js

Python

المصادقة باستخدام OAuth