Sau khi nhận được tin nhắn từ người dùng, bạn có thể gửi tin nhắn phản hồi để tiếp tục cuộc trò chuyện. Bạn có thể gửi tin nhắn cho người dùng trong vòng tối đa 30 ngày kể từ khi người dùng gửi tin nhắn gần đây nhất.
Nhân viên hỗ trợ giao tiếp với người dùng bằng cách gửi và nhận tin nhắn. Để gửi tin nhắn cho người dùng, nhân viên hỗ trợ sẽ gửi yêu cầu tin nhắn đến Business Messages.
Để gửi tin nhắn, bạn cần gửi yêu cầu POST HTTP tới API Business Messages bao gồm
- một mã nhận dạng thư duy nhất
- mã nhận dạng cuộc trò chuyện
- nội dung tin nhắn
Khi gửi tin nhắn của bạn đến người dùng, API Business Messages sẽ trả về một 200 OK. Nếu thông báo của bạn thiếu giá trị bắt buộc, thì API sẽ trả về lỗi 400. Nếu thông báo sử dụng thông tin xác thực không hợp lệ, API sẽ trả về lỗi 401.
Hãy sử dụng trang nhật ký Bảng điều khiển dành cho nhà phát triển của Business Communications để khắc phục các vấn đề về việc gửi tin nhắn.
Chiến lược dự phòng
Nếu thiết bị của người dùng không hỗ trợ tin nhắn bạn cố gắng gửi, chẳng hạn như nếu người dùng không hỗ trợ câu trả lời đề xuất, thì API sẽ trả về lỗi 400 (FAILED
PRECONDITION). Tuy nhiên, bạn có thể giải quyết các loại thông báo không được hỗ trợ bằng cách chỉ định văn bản fallback cho mỗi thư bạn gửi. Nếu bạn chỉ định văn bản fallback, API sẽ trả về phản hồi 200 OK, ngay cả khi thiết bị của người dùng không hỗ trợ loại thông báo này.
Nếu người dùng nhận được một thông báo cho biết thiết bị của họ không hỗ trợ nhưng lại chứa văn bản fallback, thì thiết bị sẽ hiện văn bản fallback. Hành vi này cho phép bạn chủ động tiếp tục cuộc trò chuyện mà không làm gián đoạn luồng cuộc trò chuyện hoặc không mất thêm thời gian để xử lý lỗi 400
(FAILED PRECONDITION) và xác định một thông báo thay thế.
Văn bản fallback cho một thông báo cụ thể phải phản ánh chức năng của thông báo đó.
Ví dụ:
- Đối với các tin nhắn có câu trả lời hoặc hành động đề xuất, hãy đưa nội dung tin nhắn vào văn bản
fallbackvà đưa ra hướng dẫn về những lựa chọn mà người dùng có để tiếp tục trò chuyện. - Đối với thẻ thông tin hoặc băng chuyền, hãy đưa tiêu đề và nội dung mô tả vào văn bản
fallback, đồng thời đưa đường liên kết đến hình ảnh hoặc trang web.
Để chèn dấu ngắt dòng trong văn bản fallback, hãy sử dụng \n hoặc \r\n.
Kiểm thử văn bản dự phòng
Trước khi ra mắt một nhân viên hỗ trợ, bạn có thể kiểm tra cách văn bản dự phòng xuất hiện trong
cuộc trò chuyện bằng cách gửi tin nhắn có tham số URL forceFallback được đặt thành
true. Khi bạn buộc văn bản dự phòng, cuộc trò chuyện sẽ bỏ qua nội dung thông điệp chính (văn bản và gợi ý về URL mở trong ví dụ sau) và hiển thị văn bản dự phòng.
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 a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#fallback_strategy
# 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
curl -X POST \
"https://businessmessages.googleapis.com/v1/conversations/__CONVERSATION_ID__/messages?forceFallback=true" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-messages" \
-H "$(oauth2l header --json ./service_account_key.json businessmessages)" \
-d "{
'messageId': '$(uuidgen)',
'text': 'Hello world!',
'fallback': 'Hello, world!\n\nSay \"Hello\" at https://www.growingtreebank.com',
'suggestions': [
{
'action': {
'text': 'Hello',
'postbackData': 'hello-formal',
'openUrlAction': {
'url': 'https://www.growingtreebank.com',
}
},
},
],
'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 a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#fallback_strategy
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 defaulting to the fallback text.
*
* @param {string} conversationId The unique id for this user and agent.
* @param {string} message The message text to send the user.
* @param {string} representativeType A value of BOT or HUMAN.
*/
async function sendMessage(conversationId, message, representativeType) {
const authClient = await initCredentials();
// Create the payload for sending a message
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
forceFallback: true, // Force usage of the fallback text
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
text: message,
fallback: 'This is the fallback text'
},
};
// 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);
});
}
/**
* 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class TestFallbackTestSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a basic text message with fallback text
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setFallback("This is the fallback text")
.setText("MESSAGE_TEXT")
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Force usage of the fallback text
messageRequest.setForceFallback(true);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a text message to the user with a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#fallback_strategy
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 message with fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
fallback='This is the fallback text',
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='This is a sample text')
# Create the message request, force usage of the fallback text
create_request = BusinessmessagesConversationsMessagesCreateRequest(
businessMessagesMessage=message,
forceFallback=True,
parent='conversations/' + conversation_id)
# Send the message
bm_client.BusinessmessagesV1.ConversationsMessagesService(
client=client).Create(request=create_request)
Để biết thông tin chi tiết, hãy xem Message.
Nghị sĩ
Khi nhân viên hỗ trợ gửi tin nhắn, bạn chỉ định một người đại diện: người hoặc
tự động hoá đã soạn tin nhắn. Business Messages hỗ trợ người đại diện HUMAN và
BOT.
Hãy chỉ định đại diện của BOT khi bất kỳ loại quy trình tự động hoá nào soạn tin nhắn, cho dù đó là một phản hồi tự động cho người dùng biết vị trí của họ trong hàng đợi, một tác nhân hiểu ngôn ngữ tự nhiên phức tạp có quyền truy cập động vào thông tin người dùng hay bất kỳ loại tác nhân nào khác. Tin nhắn có người đại diện BOT sẽ xuất hiện cùng với một biểu tượng nhỏ 
, giúp người dùng đặt ra kỳ vọng cho các kiểu tương tác mà họ có thể tương tác.
Chỉ chỉ định người đại diện của HUMAN khi một nhân viên hỗ trợ trực tiếp soạn tin nhắn.
Trước khi bạn gửi bất cứ tin nhắn nào từ người đại diện của HUMAN, hãy gửi một
sự kiện
REPRESENTATIVE_JOINED để cho
người dùng biết rằng họ có thể gửi các tin nhắn dạng tự do hoặc phức tạp hơn. Sau khi bạn gửi tin nhắn cuối cùng từ người đại diện của HUMAN, hãy gửi một sự kiện REPRESENTATIVE_LEFT để một lần nữa đặt lại kỳ vọng của người dùng.
Ví dụ: nếu người dùng bắt đầu cuộc trò chuyện với nhân viên hỗ trợ của bạn và bạn gửi tin nhắn tự động cho biết họ sẽ có nhân viên hỗ trợ trực tiếp trong vòng 2 phút, thì tin nhắn đó sẽ do nhân viên đại diện của BOT gửi. Trước khi nhân viên hỗ trợ trực tiếp tham gia, hãy gửi một sự kiện REPRESENTATIVE_JOINED. Tất cả tin nhắn từ nhân viên hỗ trợ trực tiếp đều phải được gắn nhãn là đến từ người đại diện của HUMAN. Khi nhân viên hỗ trợ trực tiếp thoát khỏi cuộc trò chuyện, hãy gửi một sự kiện REPRESENTATIVE_LEFT. Tất cả các thông báo tiếp theo phải do một người đại diện của BOT gửi, trừ phi có một nhân viên hỗ trợ trực tiếp khác tham gia cuộc trò chuyện.
Hãy xem phần Chuyển giao từ bot sang tác nhân
trực tiếp
để biết cuộc trò chuyện mẫu và mã chuyển đổi giữa BOT và HUMAN
đại diện.
Cho dù người đại diện là BOT hay HUMAN, bạn đều có thể chỉ định tên hiển thị và hình đại diện đại diện. Cả tên hiển thị và hình đại diện đều hiển thị cho người dùng.
Hình đại diện phải có kích thước 1024x1024 px và tối đa 50 KB, đồng thời phải được chỉ định là URL có sẵn công khai. Nếu bạn không cung cấp hình đại diện, biểu trưng của nhân viên hỗ trợ sẽ được dùng làm hình đại diện của người đại diện.
Văn bản
Những thông điệp đơn giản nhất đều được tạo thành từ văn bản. Tin nhắn văn bản phù hợp nhất để truyền đạt thông tin mà không cần hình ảnh, hoạt động tương tác phức tạp hay phản hồi.
Ví dụ:
Mã sau đây sẽ gửi một tin nhắn văn bản đơn giản. Để biết thông tin tham khảo, hãy xem conversations.messages.create.
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.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#text
# 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
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': 'Hello world!',
'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.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#text
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 text message to the Business Messages API.
*
* @param {string} conversationId The unique id for this user and agent.
* @param {string} message The message text to send the user.
* @param {string} representativeType A value of BOT or HUMAN.
*/
async function sendMessage(conversationId, message, representativeType) {
const authClient = await initCredentials();
// Create the payload for sending a message
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
text: message,
},
};
// 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);
});
}
/**
* 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, 'This is a test message', 'BOT');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendTextMessageSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a basic text message
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("MESSAGE_TEXT")
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a text message to the user.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#text
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='This is a sample text')
# 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)
Văn bản đa dạng thức
Tin nhắn văn bản được đặt containsRichText thành true có thể bao gồm
định dạng Markdown cơ bản. Bạn có thể thêm các siêu liên kết hoặc in đậm hay in nghiêng văn bản. Bảng này trình bày một số ví dụ hợp lệ:
| Định dạng | Ký tự | Chữ thường | Văn bản được hiển thị |
|---|---|---|---|
| Đậm | ** |
**Some text** |
Một số văn bản |
| In nghiêng | * |
*Some text* |
Một số văn bản |
| Đường siêu liên kết | []() |
[Click here](https://www.example.com) |
Nhấp vào đây |
| Ngắt dòng | \n
|
Line one\nLine two
|
Dòng 1 Dòng 2 |
Việc định dạng phải tuân theo một số quy tắc bổ sung:
- Tất cả đường liên kết đều phải bắt đầu bằng
https://hoặchttp:// - Các loại định dạng khác nhau có thể được lồng vào nhau nhưng không được chồng chéo nhau.
- Bạn được phép ngắt dòng bằng
\nở bất kỳ vị trí nào trong thư, nhưng ngắt dòng ở cuối thư thì không. - Để thường hiển thị bất kỳ ký tự dành riêng nào (
*,\,[hoặc]), bạn phải thêm một ký tự dấu gạch chéo ngược (\) vào trước các ký tự đó.
Không gửi được thông báo có định dạng không hợp lệ kèm theo thông báo lỗi về Markdown không hợp lệ. Bảng này trình bày một số ví dụ hợp lệ và không hợp lệ khác dựa trên các quy tắc trên:
| Chữ thường | Hiệu lực | Văn bản được hiển thị |
|---|---|---|
[Click here](www.example.com) |
Không hợp lệ. Đường liên kết không bắt đầu bằng http:// hoặc https:// |
Không kết xuất. |
[**Click here**](https://www.example.com) |
Hợp lệ. Được phép lồng. | Nhấp vào đây |
**This is [not** valid](https://www.example.com) |
Không hợp lệ. Không cho phép định dạng chồng chéo. | Không kết xuất. |
** Some bold text ** |
Không hợp lệ. Không được sử dụng khoảng trắng ở cuối bên trong **. |
Không kết xuất. |
Citation below\* |
Hợp lệ. Ký tự * là ký tự thoát. |
Trích dẫn bên dưới* |
Ví dụ:
Mã sau đây sẽ gửi một tin nhắn văn bản đa dạng thức. Để biết thông tin tham khảo, hãy xem conversations.messages.create.
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 rich text to the user with a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich_text
# 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
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)',
'fallback': 'Hello, check out this link https://www.google.com.',
'text': 'Hello, here is some **bold text**, *italicized text*, and a [link](https://www.google.com).',
'containsRichText': 'true',
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
}
}"
Node.js
/**
* This code sends a rich text to the user with a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich_text
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 rich text message using markdown to the Business Messages API.
*
* @param {string} conversationId The unique id for this user and agent.
* @param {string} representativeType A value of BOT or HUMAN.
*/
async function sendMessage(conversationId, message, representativeType) {
const authClient = await initCredentials();
// Create the payload for sending a rich text message
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
containsRichText: true, // Force this message to be processed as rich text
text: 'Hello, here is some **bold text**, *italicized text*, and a [link](https://www.google.com).',
fallback: 'Hello, check out this link https://www.google.com.'
},
};
// 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);
});
}
/**
* 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendRichTextMessageSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a rich text message
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setContainsRichText(true) // Force this message to be processed as rich text
.setText("Hello, here is some **bold text**, *italicized text*, and a [link](https://www.google.com).")
.setFallback("Hello, check out this link https://www.google.com.")
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a rich text to the user with a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich_text
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 rich text message with fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
fallback='Hello, check out this link https://www.google.com.',
containsRichText=True, # Force this message to be processed as rich text
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='Hello, here is some **bold text**, *italicized text*, and a [link](https://www.google.com).')
# 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)
Hình ảnh
Gửi hình ảnh cho người dùng trong tin nhắn.
Bạn có thể gửi thông điệp hình ảnh kèm theo URL đến hình ảnh và hình thu nhỏ của hình ảnh.
Ví dụ:
Mã sau đây sẽ gửi một hình ảnh. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và Image.
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 an image to the user with a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#images
# 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
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)',
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
'fallback': 'Hello, world!\nAn image has been sent with Business Messages.',
'image': {
'contentInfo':{
'altText': 'Image alternative text',
'fileUrl': 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
'forceRefresh': 'false'
}
},
}"
Node.js
/**
* This code sends an image to the user with a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#images
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 an image message to the Business Messages API.
*
* @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 an image message
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Hello, world!\n An image has been sent with Business Messages.',
image: {
contentInfo: {
altText: 'Some alternative text',
fileUrl: 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
forceRefresh: true,
},
},
},
};
// 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import com.google.communications.businessmessages.v1.MediaHeight;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendImageMessageSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create an Image
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setRepresentative(representative)
.setImage(new BusinessMessagesImage()
.setContentInfo(
new BusinessMessagesContentInfo()
.setFileUrl("FILE_URL")
.setAltText("ALT_TEXT")
.setForceRefresh("FORCE_REFRESH")
));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends an image to the user with a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#images
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 BusinessMessagesContentInfo
from businessmessages.businessmessages_v1_messages import BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesImage
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = 'EDIT_HERE'
image_file_url = '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 an image message with fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
fallback='Hello, world!\nAn image has been sent with Business Messages.',
image=BusinessMessagesImage(
contentInfo=BusinessMessagesContentInfo(
altText='Alternative text',
fileUrl=image_file_url,
forceRefresh=True
)
))
# 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)
Câu trả lời đề xuất
Câu trả lời đề xuất sẽ hướng dẫn người dùng qua các cuộc trò chuyện bằng cách đưa ra câu trả lời mà nhân viên hỗ trợ của bạn biết cách phản ứng.
Khi người dùng nhấn vào một câu trả lời đề xuất, nhân viên hỗ trợ sẽ nhận được một tin nhắn chứa văn bản của tin nhắn trả lời và dữ liệu đăng lại.
Câu trả lời đề xuất có tối đa 25 ký tự và một tin nhắn có tối đa 13 đề xuất.
Ví dụ:
Mã sau đây gửi văn bản cùng với 2 câu trả lời đề xuất. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và SuggestedReply.
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 mesage to the user with suggested replies.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#suggested_replies
# 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
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': 'Hello, world!',
'fallback': 'Hello, world!\n\nReply with \"Hello\" or \"Hi!\"',
'suggestions': [
{
'reply': {
'text': 'Hello',
'postbackData': 'hello-formal',
},
},
{
'reply': {
'text': 'Hi!',
'postbackData': 'hello-informal',
},
},
],
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
}"
Node.js
/**
* This code sends a text mesage to the user with suggested replies.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#suggested_replies
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 of "Hello, world!" to the Business Messages API along with two suggested replies.
*
* @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();
// Create a text message with two suggested replies
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Hello, world!\n\nReply with "Hello" or "Hi!"',
text: 'Hello, world!',
suggestions: [
{
reply: {
text: 'Hello',
postbackData: 'hello-formal',
},
},
{
reply: {
text: 'Hello',
postbackData: 'hello-informal',
},
},
],
},
};
// 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);
});
}
/**
* 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendSuggestedReplySnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a text message with two suggested replies
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("Hello, world!")
.setFallback("Hello, world!\n\nReply with \"Hello\" or \"Hi!\"")
.setSuggestions(Arrays.asList(
new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Hello").setPostbackData("hello-formal")
),
new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Hi!").setPostbackData("hello-informal")
))
)
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a text mesage to the user with suggested replies.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#suggested_replies
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestedReply
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 two suggested replies and fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='Hello, world!',
fallback='Hello, world!\n\nReply with \"Hello\" or \"Hi!\"',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Hello',
postbackData='hello-formal')
),
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Hi!',
postbackData='hello-informal')
)
])
# 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)
Hành động đề xuất
Các thao tác đề xuất sẽ hướng dẫn người dùng thực hiện các cuộc trò chuyện bằng cách tận dụng chức năng gốc của thiết bị. Khi người dùng nhấn vào một hành động đề xuất, tác nhân của bạn sẽ nhận được một thông báo chứa văn bản và dữ liệu đăng lại của hành động đó.
Hành động đề xuất có tối đa 25 ký tự và một thông báo có tối đa 13 đề xuất.
Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và SuggestedAction.
Thao tác mở URL
Với thao tác Mở URL, tác nhân của bạn sẽ đề xuất một URL để người dùng mở. Nếu một ứng dụng được đăng ký làm trình xử lý mặc định cho URL, thì ứng dụng đó sẽ mở ra và biểu tượng của thao tác đó sẽ là biểu tượng của ứng dụng. Thao tác mở URL chỉ hỗ trợ các URL có giao thức HTTP và HTTPS, các giao thức khác (chẳng hạn như mailto) không được hỗ trợ.
Mã sau đây sẽ gửi văn bản với thao tác Mở URL. Để biết các tuỳ chọn định dạng và giá trị, hãy xem OpenUrlAction.
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 mesage to the user with a suggestion action toopen a URL
# and a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#open_url_action
# 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
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': 'Hello world!',
'fallback': 'Hello, world!\n\nSay \"Hello\" at https://www.growingtreebank.com',
'suggestions': [
{
'action': {
'text': 'Hello',
'postbackData': 'hello-formal',
'openUrlAction': {
'url': 'https://www.growingtreebank.com',
}
},
},
],
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
}"
Node.js
/**
* This code sends a text mesage to the user with a suggestion action toopen a URL
* and a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#open_url_action
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 with an open URL action to the Business Messages API.
*
* @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 open url action
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Hello, world!\n\nSay \"Hello\" at https://www.growingtreebank.com',
text: 'Hello world!',
suggestions: [
{
action: {
text: 'Hello',
postbackData: 'hello-formal',
openUrlAction: {
url: 'https://www.growingtreebank.com',
},
},
},
],
},
};
// 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendSuggestedActionSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a text message with an open url action
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("Hello world!")
.setFallback("Hello, world!\n\nSay \"Hello\" at https://www.growingtreebank.com")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setAction(new BusinessMessagesSuggestedAction()
.setText("Hello").setPostbackData("hello-formal")
.setOpenUrlAction(
new BusinessMessagesOpenUrlAction().setUrl("https://www.growingtreebank.com"))
))
)
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a text mesage to the user with a suggestion action to open a URL.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#open_url_action
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesOpenUrlAction
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestedAction
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 open url action and fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='Hello, world!',
fallback='Hello, world!\n\nReply with \"Hello\" or \"Hi!\"',
suggestions=[
BusinessMessagesSuggestion(
action=BusinessMessagesSuggestedAction(
text='Hello',
postbackData='hello-formal',
openUrlAction=BusinessMessagesOpenUrlAction(
url='https://www.growingtreebank.com'))
),
])
# 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)
Thao tác quay số
Thao tác quay số đề xuất một số điện thoại để người dùng gọi điện. Khi người dùng nhấn vào khối đề xuất Hành động quay số, ứng dụng quay số mặc định của người dùng sẽ mở ra với số điện thoại đã chỉ định được điền sẵn.
Mã sau đây sẽ gửi văn bản có thao tác quay số. Để biết các tuỳ chọn định dạng và giá trị, hãy xem DialAction.
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 mesage to the user with a suggestion action to dial
# a phone number and a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#dial_action
# 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
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': 'Contact support for help with this issue.',
'fallback': 'Give us a call at +12223334444.',
'suggestions': [
{
'action': {
'text': 'Call support',
'postbackData': 'call-support',
'dialAction': {
'phoneNumber': '+12223334444',
}
},
},
],
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
}"
Node.js
/**
* This code sends a text mesage to the user with a suggestion action to dial
* a phone number and a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#dial_action
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 with a dial suggested action to the Business Messages API.
*
* @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 a dial action
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Give us a call at +12223334444.',
text: 'Contact support for help with this issue.',
suggestions: [
{
action: {
text: 'Call support',
postbackData: 'call-support',
dialAction: {
phoneNumber: '+12223334444',
},
},
},
],
},
};
// 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendDialActionSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a text message with a dial action
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("Contact support for help with this issue.")
.setFallback("Give us a call at +12223334444.")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setAction(new BusinessMessagesSuggestedAction()
.setText("Call support").setPostbackData("call-support")
.setDialAction(
new BusinessMessagesDialAction().setPhoneNumber("+12223334444"))
)))
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""Sends a text mesage to the user with a suggestion action to dial a phone number.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#dial_action
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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesDialAction
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestedAction
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 a dial action and fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
text='Contact support for help with this issue.',
fallback='Give us a call at +12223334444.',
suggestions=[
BusinessMessagesSuggestion(
action=BusinessMessagesSuggestedAction(
text='Call support',
postbackData='call-support',
dialAction=BusinessMessagesDialAction(
phoneNumber='+12223334444'))
),
])
# 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)
Đề xuất yêu cầu xác thực
Đề xuất Yêu cầu xác thực nhắc người dùng đăng nhập vào một ứng dụng tuân thủ OAuth 2.0, truyền mã xác thực để xác nhận dữ liệu tài khoản và cho phép trải nghiệm người dùng tuỳ chỉnh cũng như luồng trò chuyện chi tiết. Hãy xem bài viết Xác thực bằng OAuth.
Ví dụ:
Mã sau sẽ gửi văn bản có đề xuất Yêu cầu xác thực. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và Suggestion.
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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendAuthenticationRequestSuggestionSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a text message with an authentication request
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("Would you like to chat with a live agent?")
.setFallback("Would you like to chat with a live agent?")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setAuthenticationRequest(new BusinessMessagesAuthenticationRequest()
.setOauth(new BusinessMessagesAuthenticationRequestOauth()
.setClientId("CLIENT_ID")
.setCodeChallenge("CODE_CHALLENGE")
.setScopes(Arrays.asList("SCOPE"))
)))
)
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
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)
Đề xuất yêu cầu trực tiếp của nhân viên hỗ trợ
Tính năng đề xuất yêu cầu của nhân viên hỗ trợ trực tiếp cho phép bạn hướng dẫn người dùng tương tác với người đại diện trong các hoạt động tương tác phức tạp hoặc khi hệ thống tự động hoá của bạn không thể xử lý yêu cầu của người dùng.
Người dùng có thể yêu cầu một nhân viên hỗ trợ trực tiếp bất cứ lúc nào trong cuộc trò chuyện trên trình đơn mục bổ sung. Đề xuất này giúp nhân viên hỗ trợ có thể đề xuất các hoạt động tương tác với người đại diện theo phương thức lập trình dựa trên ngữ cảnh của cuộc trò chuyện. Nhân viên hỗ trợ của bạn phải luôn sẵn sàng phản hồi sự kiện được nhân viên hỗ trợ Trực tiếp yêu cầu, ngay cả khi nhân viên hỗ trợ đó không gửi đề xuất yêu cầu của nhân viên hỗ trợ trực tiếp.
Khi người dùng nhấn vào một đề xuất yêu cầu của nhân viên hỗ trợ trực tiếp, thao tác đó sẽ kích hoạt sự kiện của một nhân viên hỗ trợ trực tiếp đã yêu cầu.
Ví dụ:
Mã sau đây sẽ gửi văn bản kèm theo đề xuất yêu cầu của nhân viên hỗ trợ trực tiếp. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và Suggestion.
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 a Live agent request suggestion
# that allows the user to connect with a Live agent.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#live_agent_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
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': 'Would you like to chat with a live agent?',
'fallback': 'Would you like to chat with a live agent?',
'suggestions': [
{
'liveAgentRequest': {},
},
],
'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 a Live agent request suggestion
* that allows the user to connect with a Live agent.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#live_agent_request_suggestion
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 with a live agent request action to the Business Messages API.
*
* @param {string} conversationId The unique id for this user and agent.
*/
async function sendMessage(conversationId) {
const authClient = await initCredentials();
if (authClient) {
// Create the payload for sending a message along with a request for live agent action
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: 'BOT', // Must be sent from a BOT representative
},
fallback: 'Would you like to chat with a live agent?',
text: 'Would you like to chat with a live agent?',
suggestions: [
{
liveAgentRequest: {}
},
],
},
};
// 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);
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendLiveAgentRequestSuggestionSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a text message with a live request action
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setText("Would you like to chat with a live agent?")
.setFallback("Would you like to chat with a live agent?")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setLiveAgentRequest(new BusinessMessagesLiveAgentRequest()))
)
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("BOT")); // Must be sent from a BOT representative
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""Sends a text message to the user with a Live agent request suggestion.
It allows the user to connect with a Live agent.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#live_agent_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 BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesLiveAgentRequest
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
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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)
# Create a text message with a live agent request action and fallback text
# Follow instructions at https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#live_agent_request_suggestion
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative( # Must be sent from a BOT representative
representativeType=BusinessMessagesRepresentative.RepresentativeTypeValueValuesEnum.BOT
),
text='Would you like to chat with a live agent?',
fallback='Would you like to chat with a live agent?',
suggestions=[
BusinessMessagesSuggestion(
liveAgentRequest=BusinessMessagesLiveAgentRequest()
)
])
# 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)
Thẻ thông tin
Khi cần gửi một phần thông tin, nội dung nghe nhìn hoặc đề xuất liên quan, bạn nên gửi một thẻ thông tin chi tiết. Thẻ thông tin cho phép nhân viên hỗ trợ của bạn gửi nhiều đơn vị thông tin trong một tin nhắn.
Thẻ thông tin có thể chứa các mục sau:
- Nội dung nghe nhìn (JPG, JPEG hoặc PNG, tối đa 5 MB)
- Hình thu nhỏ của nội dung nghe nhìn (JPG, JPEG hoặc PNG, tối đa 25 KB)
- Tiêu đề (tối đa 200 ký tự)
- Nội dung mô tả (tối đa 2000 ký tự)
- Danh sách câu trả lời đề xuất và hành động được đề xuất (tối đa 4)
Thẻ thông tin có thể chứa bất kỳ hoặc tất cả các mục được liệt kê, nhưng thẻ phải chứa ít nhất nội dung nghe nhìn hoặc tiêu đề thì mới hợp lệ. Một thẻ thông tin có thể chứa tối đa 4 hành động được đề xuất và câu trả lời đề xuất.
Nhân viên hỗ trợ của bạn có thể gửi nhiều thẻ thông tin cùng nhau trong một băng chuyền về thẻ thông tin.
Ví dụ:
Mã sau đây sẽ gửi một thẻ thông tin có hình ảnh và câu trả lời đề xuất. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và RichCard.
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 rich card to the user with a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-cards
# 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
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)',
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
'fallback': 'Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"',
'richCard': {
'standaloneCard': {
'cardContent': {
'title': 'Hello, world!',
'description': 'Sent with Business Messages.',
'media': {
'height': 'TALL',
'contentInfo':{
'altText': 'Google logo',
'fileUrl': 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
'forceRefresh': 'false'
}
},
'suggestions': [
{
'reply': {
'text': 'Suggestion #1',
'postbackData': 'suggestion_1'
}
},
{
'reply': {
'text': 'Suggestion #2',
'postbackData': 'suggestion_2'
}
}
]
}
}
}
}"
Node.js
/**
* This code sends a rich card to the user with a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-cards
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 rich card message to the Business Messages API.
*
* @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 rich card message with two suggested replies
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"',
richCard: {
standaloneCard: {
cardContent: {
title: 'Hello, world!',
description: 'Sent with Business Messages.',
media: {
height: 'TALL',
contentInfo: {
altText: 'Google logo',
fileUrl: 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
forceRefresh: false,
},
},
suggestions: [
{
reply: {
text: 'Suggestion #1',
postbackData: 'suggestion_1',
},
},
{
reply: {
text: 'Suggestion #2',
postbackData: 'suggestion_2',
},
},
],
},
},
},
},
};
// 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import com.google.communications.businessmessages.v1.MediaHeight;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendRichCardMessageSnippet {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a rich card with two suggested replies
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setFallback("Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"")
.setRichCard(new BusinessMessagesRichCard()
.setStandaloneCard(new BusinessMessagesStandaloneCard()
.setCardContent(
new BusinessMessagesCardContent()
.setTitle("Hello, world!")
.setDescription("Sent with Business Messages.")
.setSuggestions(Arrays.asList(
new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Suggestion #1").setPostbackData("suggestion_1")
),
new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Suggestion #2").setPostbackData("suggestion_2")
))
)
.setMedia(new BusinessMessagesMedia()
.setHeight(MediaHeight.MEDIUM.toString())
.setContentInfo(
new BusinessMessagesContentInfo()
.setAltText("Google logo")
.setFileUrl("https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png")
.setForceRefresh(false)
))
)))
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends a rich card to the user with a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-cards
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 BusinessMessagesCardContent
from businessmessages.businessmessages_v1_messages import BusinessMessagesContentInfo
from businessmessages.businessmessages_v1_messages import BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMedia
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesRichCard
from businessmessages.businessmessages_v1_messages import BusinessMessagesStandaloneCard
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestedReply
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 rich card message with two suggested replies and fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
fallback='Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"',
richCard=BusinessMessagesRichCard(
standaloneCard=BusinessMessagesStandaloneCard(
cardContent=BusinessMessagesCardContent(
title='Hello, world!',
description='Sent with Business Messages.',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Suggestion #1',
postbackData='suggestion_1')
),
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Suggestion #2',
postbackData='suggestion_2')
)
],
media=BusinessMessagesMedia(
height=BusinessMessagesMedia.HeightValueValuesEnum.TALL,
contentInfo=BusinessMessagesContentInfo(
altText='Google logo',
fileUrl='https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
forceRefresh=False
))
))))
# 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)
Băng chuyền thẻ thông tin
Khi bạn cần cho người dùng nhiều lựa chọn, hãy sử dụng băng chuyền thẻ đa dạng thức. Băng chuyền xâu chuỗi nhiều thẻ nhiều định dạng lại với nhau, cho phép người dùng so sánh các mục và tương tác với từng mục.
Băng chuyền có thể chứa tối thiểu 2 và tối đa 10 thẻ thông tin. Thẻ thông tin trong băng chuyền phải tuân thủ các yêu cầu chung về thẻ thông tin về nội dung và chiều cao.
Ví dụ:
Mã sau đây sẽ gửi một băng chuyền thẻ thông tin. Để biết các tuỳ chọn định dạng và giá trị, hãy xem conversations.messages.create và RichCard.
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 to the user a carousel with rich cards and a fallback text.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-card-carousels
# 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
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)',
'representative': {
'avatarImage': 'https://developers.google.com/identity/images/g-logo.png',
'displayName': 'Chatbot',
'representativeType': 'BOT'
},
'fallback': 'Card #1\nThe description for card #1\n\nCard #2\nThe description for card #2\n\nReply with \"Card #1\" or \"Card #2\"',
'richCard': {
'carouselCard': {
'cardWidth': 'MEDIUM',
'cardContents': [
{
'title': 'Card #1',
'description': 'The description for card #1',
'suggestions': [
{
'reply': {
'text': 'Card #1',
'postbackData': 'card_1'
}
}
],
'media': {
'height': 'MEDIUM',
'contentInfo': {
'fileUrl': 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
'forceRefresh': 'false',
}
}
},
{
'title': 'Card #2',
'description': 'The description for card #2',
'suggestions': [
{
'reply': {
'text': 'Card #2',
'postbackData': 'card_2'
}
}
],
'media': {
'height': 'MEDIUM',
'contentInfo': {
'fileUrl': 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
'forceRefresh': 'false',
}
}
}
]
}
}
}"
Node.js
/**
* This code sends to the user a carousel with rich cards and a fallback text.
* Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-card-carousels
*
* This code is based on the https://github.com/google-business-communications/nodejs-businessmessages Node.js
* Business Messages client library.
*/
/**
* Edit the values below:
*/
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';
const CONVERSATION_ID = '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 carousel card message to the Business Messages API.
*
* @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 carousel message
// with two cards and a suggested reply for each card
const apiParams = {
auth: authClient,
parent: 'conversations/' + conversationId,
resource: {
messageId: uuidv4(),
representative: {
representativeType: representativeType,
},
fallback: 'Card #1\nThe description for card #1\n\nCard #2\nThe description for card #2\n\nReply with \"Card #1\" or \"Card #2\"',
richCard: {
carouselCard: {
cardWidth: 'MEDIUM',
cardContents: [
{
title: 'Card #1',
description: 'The description for card #1',
suggestions: [
{
reply: {
text: 'Card #1',
postbackData: 'card_1'
}
}
],
media: {
height: 'MEDIUM',
contentInfo: {
fileUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
forceRefresh: 'false',
}
}
},
{
title: 'Card #2',
description: 'The description for card #2',
suggestions: [
{
reply: {
text: 'Card #2',
postbackData: 'card_2'
}
}
],
media: {
height: 'MEDIUM',
contentInfo: {
fileUrl: 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
forceRefresh: 'false',
}
}
}
]
}
}
},
};
// 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');
Java
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
import com.google.api.client.http.HttpBackOffUnsuccessfulResponseHandler;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.util.ExponentialBackOff;
import com.google.api.services.businessmessages.v1.Businessmessages;
import com.google.api.services.businessmessages.v1.model.*;
import com.google.communications.businessmessages.v1.MediaHeight;
import java.io.FileInputStream;
import java.util.Arrays;
import java.util.UUID;
class SendRichCardCarouselMessage {
/**
* Initializes credentials used by the Business Messages API.
*/
private static Businessmessages.Builder getBusinessMessagesBuilder() {
Businessmessages.Builder builder = null;
try {
GoogleCredential credential = GoogleCredential
.fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));
credential = credential.createScoped(Arrays.asList(
"https://www.googleapis.com/auth/businessmessages"));
credential.refreshToken();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();
// Create instance of the Business Messages API
builder = new Businessmessages
.Builder(httpTransport, jsonFactory, null)
.setApplicationName("Sample Application");
// Set the API credentials and endpoint
builder.setHttpRequestInitializer(credential);
} catch (Exception e) {
e.printStackTrace();
}
return builder;
}
public static void main(String args[]) {
try {
String conversationId = "CONVERSATION_ID";
// Create client library reference
Businessmessages.Builder builder = getBusinessMessagesBuilder();
// Create a rich card with two suggested replies
BusinessMessagesMessage message = new BusinessMessagesMessage()
.setMessageId(UUID.randomUUID().toString())
.setFallback("Hello, world!\nSent with Business Messages\n\nReply with \"Suggestion #1\" or \"Suggestion #2\"")
.setRichCard(new BusinessMessagesRichCard()
.setCarouselCard(new BusinessMessagesCarouselCard().setCardWidth("MEDIUM")
.setCardContents(Arrays.asList(
new BusinessMessagesCardContent()
.setTitle("Card #1")
.setDescription("The description for card #1")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Card #1").setPostbackData("card_1")
)))
.setMedia(new BusinessMessagesMedia()
.setHeight(MediaHeight.MEDIUM.toString())
.setContentInfo(new BusinessMessagesContentInfo()
.setFileUrl("https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg"))),
new BusinessMessagesCardContent()
.setTitle("Card #2")
.setDescription("The description for card #2")
.setSuggestions(Arrays.asList(new BusinessMessagesSuggestion()
.setReply(new BusinessMessagesSuggestedReply()
.setText("Card #2").setPostbackData("card_2")
)))
.setMedia(new BusinessMessagesMedia()
.setHeight(MediaHeight.MEDIUM.toString())
.setContentInfo(new BusinessMessagesContentInfo()
.setFileUrl("https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg")))
)
)))
.setRepresentative(new BusinessMessagesRepresentative()
.setRepresentativeType("TYPE"));
// Create message request
Businessmessages.Conversations.Messages.Create messageRequest
= builder.build().conversations().messages()
.create("conversations/" + conversationId, message);
// Setup retries with exponential backoff
HttpRequest httpRequest =
((AbstractGoogleClientRequest) messageRequest).buildHttpRequest();
httpRequest.setUnsuccessfulResponseHandler(new
HttpBackOffUnsuccessfulResponseHandler(
new ExponentialBackOff()));
// Execute request
httpRequest.execute();
} catch (Exception e) {
e.printStackTrace();
}
}
}
Python
"""This code sends to the user a carousel with rich cards and a fallback text.
Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/message/send?hl=en#rich-card-carousels
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 BusinessMessagesCardContent
from businessmessages.businessmessages_v1_messages import BusinessMessagesCarouselCard
from businessmessages.businessmessages_v1_messages import BusinessMessagesContentInfo
from businessmessages.businessmessages_v1_messages import BusinessmessagesConversationsMessagesCreateRequest
from businessmessages.businessmessages_v1_messages import BusinessMessagesMedia
from businessmessages.businessmessages_v1_messages import BusinessMessagesMessage
from businessmessages.businessmessages_v1_messages import BusinessMessagesRepresentative
from businessmessages.businessmessages_v1_messages import BusinessMessagesRichCard
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestedReply
from businessmessages.businessmessages_v1_messages import BusinessMessagesSuggestion
from oauth2client.service_account import ServiceAccountCredentials
# Edit the values below:
path_to_service_account_key = './service_account_key.json'
conversation_id = '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 carousel message with two cards and a suggested reply for each card
# and fallback text
message = BusinessMessagesMessage(
messageId=str(uuid.uuid4().int),
representative=BusinessMessagesRepresentative(
representativeType=representative_type
),
fallback='Card #1\nThe description for card #1\n\nCard #2\nThe description for card #2\n\nReply with \"Card #1\" or \"Card #2\"',
richCard=BusinessMessagesRichCard(
carouselCard=BusinessMessagesCarouselCard(
cardWidth=BusinessMessagesCarouselCard.CardWidthValueValuesEnum.MEDIUM,
cardContents=[
BusinessMessagesCardContent(
title='Card #1',
description='The description for card #1',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Card #1',
postbackData='card_1')
)
],
media=BusinessMessagesMedia(
height=BusinessMessagesMedia.HeightValueValuesEnum.MEDIUM,
contentInfo=BusinessMessagesContentInfo(
fileUrl='https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
forceRefresh=False))),
BusinessMessagesCardContent(
title='Card #2',
description='The description for card #2',
suggestions=[
BusinessMessagesSuggestion(
reply=BusinessMessagesSuggestedReply(
text='Card #2',
postbackData='card_2')
)
],
media=BusinessMessagesMedia(
height=BusinessMessagesMedia.HeightValueValuesEnum.MEDIUM,
contentInfo=BusinessMessagesContentInfo(
fileUrl='https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
forceRefresh=False)))
])))
# 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)