OAuth ile kimlik doğrulama

OAuth, temsilcilerin kullanıcıların kimliklerini doğrulamasını ve görüşmelerde kişiselleştirilmiş bilgileri güvenli bir şekilde sunmasını sağlar. Kullanıcıların güvenilir bir OAuth sağlayıcısında oturum açmasını sağlayan kullanıcı verileri, otomasyon aracılığıyla hızlı yanıtlar sağlamaya ve müşteri temsilcilerinin zamandan tasarruf etmesine yardımcı olabilecek kullanıcı verilerine erişebilir.

Business Messages, kullanıcılardan temsilci için yapılandırdığınız bir OAuth sağlayıcısında oturum açmalarını isteyen Kimlik doğrulama isteği önerisiyle OAuth 2.0'ı destekler. Kullanıcı başarıyla oturum açtıktan sonra Business Messages, temsilciye mesaj olarak bir yetkilendirme kodu iletir.

OAuth sağlayıcısından yetkilendirme kodu aldıktan sonra bu API'leri ile entegre edebilir ve kullanıcı kimlik bilgileri gerektiren görüşme akışlarını destekleyebilirsiniz. Etkileşimde bulunduğunuz her hizmetin kendi kullanım şartları olduğunu unutmayın.

Bir aracı için OAuth'u yapılandırma

Bir aracı için Kimlik doğrulama isteği önerisini etkinleştirmek üzere önce OAuth'u yapılandırmanız gerekir.

Bir OAuth yapılandırması belirtmek için temsilcinin endpointUrl alanını güncellemek üzere Business Communications API ile bir PATCH isteği gönderirsiniz.

Uç nokta URL'sini belirttikten sonra, temsilciniz için yönlendirme URI'lerini depolamanız ve yönlendirme URI'larını OAuth sağlayıcınızın bilgilerinde güncellemeniz gerekir.

Ön koşullar

Aşağıdaki öğelere ihtiyacınız vardır:

• OAuth 2.0 spesifikasyonuna uyan bir OAuth sağlayıcı
• Geliştirme makinenizdeki GCP projenizin hizmet hesabı anahtarına giden yol

• name adlı temsilci (örneğin, &brands/12345/agents/67890")

  Müşteri temsilcisinin name numarasını bilmiyorsanız Marka için tüm aracıları listeleme bölümüne bakın.

• Kullanıcıların OAuth sağlayıcısında oturum açtığı uç nokta URL'si

Güncelleme isteğini gönderme

Temsilciyi güncellemek için aşağıdaki komutu çalıştırın. Değişkenleri Ön koşullar'da tanımladığınız değerlerle değiştirin.

Not: Temsilci doğrulandıktan sonra temsilcinin yetkilendirme yapılandırmasını güncelleyemezsiniz. Doğrulanmış bir temsilcinin yapılandırmasını güncellemeniz gerekiyorsa bize ulaşın. (Öncelikle bir Business Messages Google Hesabı ile oturum açmanız gerekir. Bir hesaba kaydolmak için İşletme Mesajlarıyla kaydolma bölümünü inceleyin.)

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',
        },
    },
}"

Yönlendirme URI'lerini güncelleyin

OAuth aracı için yapılandırıldığına göre OAuth sağlayıcınıza dört yönlendirme URI'sı eklemeniz gerekir:

• 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&

Tüm yönlendirme URL'lerini OAuth sağlayıcı bilgilerinize eklemeniz gerekir.

Yönlendirme URI'larını güncelleme işlemi OAuth sağlayıcısına göre değişir. Talimatlar için OAuth sağlayıcınıza başvurun.

OAuth artık aracınız için yapılandırıldığına göre, Kimlik doğrulama isteği önerisiyle kullanıcıların kimliğini doğrulayabilirsiniz.

Bir kullanıcının kimliğini doğrulama

Bir aracı için OAuth'u yapılandırdıktan sonra kullanıcılardan Kimlik doğrulama isteği önerisiyle oturum açmasını isteyebilirsiniz.

Ön koşullar

Aşağıdaki öğelere ihtiyacınız vardır:

• Geliştirme makinenizdeki GCP projenizin hizmet hesabı anahtarına giden yol

• name adlı temsilci (örneğin, &brands/12345/agents/67890")

  Müşteri temsilcisinin name numarasını bilmiyorsanız Marka için tüm aracıları listeleme bölümüne bakın.

• OAuth sağlayıcınızdan istemci kimliği

• OAuth sağlayıcınızdan gelen kod sorgulama şartları

• OAuth sağlayıcınızın kapsamları

Kimlik doğrulama isteği önerisi gönderme

Bir kullanıcının kimliğini doğrulamak için

1. OAuth isteği için kod doğrulayıcı ve kod sorgulama dizeleri oluşturun. Gereksinimler ve seçenekler için OAuth sağlayıcınıza bakın.
2. Kimlik doğrulama isteği önerisiyle bir mesaj gönderin.

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

1. Kullanıcı öneriye dokunup başarılı bir şekilde oturum açtığında temsilcinizin webhook'unda bir mesaj alırsınız. Yetkilendirme kodunu authenticationResponse.code alanından alın.

Mesajı aldıktan sonra, yetkilendirme kodunu ve kod doğrulayıcıyı OAuth sağlayıcınızdan bir erişim jetonu için takas edebilirsiniz. Kullanıcı jetonuna erişim jetonuyla erişebilirsiniz.

Kod örnekleri de dahil olmak üzere, kimlik doğrulama içeren örnek bir ileti dizisi için Kullanıcının kimliğini doğrulama başlıklı makaleye bakın.