Tất cả các tác nhân đều thuộc về một thương hiệu (doanh nghiệp, tổ chức hoặc nhóm). Trước khi tạo một nhân viên hỗ trợ, bạn cần tạo một thương hiệu sở hữu. Thương hiệu chỉ mang tính tổ chức để giúp bạn nhóm các nhân viên hỗ trợ có liên quan lại với nhau
Đoạn mã trên trang này được lấy từ các mẫu Java và các mẫu Node.js.
Tạo và xác định nhân viên hỗ trợ
Tạo một nhân viên hỗ trợ
Để tạo một nhân viên hỗ trợ RBM, bạn cần xác định thông tin cơ bản của nhân viên đó.
Để biết thêm thông tin, hãy xem brands.agents.create
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); const newAgentDetails = { displayName: 'My new agent', name: brandId + '/agents/', rcsBusinessMessagingAgent: { description: 'This is the agent description that will be displayed in the Agent info tab in Messages', logoUri: 'https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf', heroUri: 'https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP', phoneNumbers: [ { phoneNumber: { number: '+12223334444' }, label: 'Call support' } ], // It's recommended to provide at least one contact method (phone or email) because // this is required for launch. For any phone, email, or website provided, a corresponding label // must also be included. privacy: { "uri": 'https://policies.google.com/privacy', "label": 'Our privacy policy' }, termsConditions: { "uri": 'https://policies.google.com/terms', "label": 'Our Terms and Conditions' }, color: '#0B78D0', billingConfig: { billingCategory: 'BASIC_MESSAGE' }, agentUseCase: 'TRANSACTIONAL', hostingRegion: 'EUROPE' } }; businessCommunicationsApiHelper.createAgent(brandId, newAgentDetails).then((response) => { }).catch((err) => { console.log(err); });
Java
Brand brand = api.getBrand(brandId); logger.info("Brand to operate on: " + brand); String displayName = flags.getOrDefault("agent_name", "Test RBM Agent: " + now.getSecond()); String suffix = flags.getOrDefault("agent_data_suffix", "API"); RcsBusinessMessagingAgent agentData = AgentFactory.createRbmAgent(suffix); Agent agent = api.createRbmAgent(brand, displayName, agentData); logger.info("RBM agent has been created: " + agent);
Mã này trả về thông tin về nhân viên hỗ trợ mới và một giá trị nhận dạng duy nhất được chỉ định cho nhân viên hỗ trợ:
{
name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_dxuewtvy_agent',
displayName: 'My new agent',
rcsBusinessMessagingAgent: {
description: 'This is the agent description that will be displayed in the Agent info tab in Messages',
logoUri: 'https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf',
heroUri: 'https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP',
phoneNumbers: [ [Object] ],
privacy: {
uri: 'https://policies.google.com/privacy',
label: 'Our privacy policy'
},
termsConditions: {
uri: 'https://policies.google.com/terms',
label: 'Our Terms and Conditions'
},
color: '#0B78D0',
billingConfig: { billingCategory: 'BASIC_MESSAGE' },
agentUseCase: 'MULTI_USE',
hostingRegion: 'EUROPE'
}
}
Tra cứu định nghĩa về nhân viên hỗ trợ
Bạn có thể truy xuất một tác nhân bằng cách chỉ định giá trị nhận dạng riêng biệt (name
). Để biết thêm thông tin chi tiết, hãy xem brands.agents.list
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); // Retrieve details of the first agent (if one has already been created) businessCommunicationsApiHelper.getAgent(agent.name).then((response) => { }).catch((err) => { console.log(err); });
Java
Agent agent = api.getAgent(flags.get("agent_id")); logger.info("Agent: " + agent);
Mã này trả về thông tin về tác nhân:
{
name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_dxuewtvy_agent',
displayName: 'My new agent',
rcsBusinessMessagingAgent: {
description: 'This is the agent description that will be displayed in the Agent info tab in Messages',
logoUri: 'https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf',
heroUri: 'https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP',
phoneNumbers: [ [Object] ],
privacy: {
uri: 'https://policies.google.com/privacy',
label: 'Our privacy policy'
},
termsConditions: {
uri: 'https://policies.google.com/terms',
label: 'Our Terms and Conditions'
},
color: '#0B78D0',
billingConfig: { billingCategory: 'BASIC_MESSAGE' },
agentUseCase: 'MULTI_USE',
hostingRegion: 'EUROPE'
}
}
Xác minh và triển khai
Gửi thông tin xác minh
Bạn bắt buộc phải xác minh thương hiệu để ra mắt nhân viên hỗ trợ. Bạn phải gửi thông tin xác minh trước khi gửi yêu cầu ra mắt. Xin lưu ý rằng bạn không cần phải đợi phê duyệt thương hiệu trước khi đưa ra yêu cầu phát hành; việc phê duyệt thương hiệu diễn ra trong quy trình phê duyệt phát hành.
Để biết thêm thông tin, hãy xem brands.agents.requestVerification
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); let agentVerificationContact = { partnerName: 'Alice', partnerEmailAddress: 'alice@thepartner.com', brandContactName: 'Bob', brandContactEmailAddress: 'bob@thebrand.com', brandWebsiteUrl: 'https://thebrand.com/' }; businessCommunicationsApiHelper.verifyAgent(agent.name, agentVerificationContact).then((response) => { }).catch((err) => { console.log(err); });
Java
AgentVerificationContact contact = AgentFactory.createRbmAgentVerification(); AgentVerification verification = api.requestAgentVerification(agent.getName(), contact); logger.info("Verification requested: " + verification);
Mã này trả về thông tin xác minh:
{
"name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent",
"verificationState": "VERIFICATION_STATE_UNVERIFIED",
"agentVerificationContact": {
"partnerName": "Alice",
"partnerEmailAddress": "alice@thepartner.com",
"brandContactName": "Bob",
"brandContactEmailAddress": "bob@thebrand.com",
"brandWebsiteUrl": "https://thebrand.com/"
}
}
Tra cứu thông tin xác minh của nhân viên hỗ trợ
Bạn có thể truy xuất trạng thái xác minh thương hiệu của một nhân viên hỗ trợ. Để biết thêm thông tin, hãy xem brands.agents.getVerification
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); businessCommunicationsApiHelper.getAgentVerification(agent.name).then((response) => { }).catch((err) => { console.log(err); });
Java
AgentVerification verification = api.getAgentVerification(agent.getName()); logger.info("RBM agent verification: " + verification);
Mã này trả về trạng thái xác minh và thông tin đối tác:
{
"name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent/verification",
"verificationState": "VERIFICATION_STATE_UNVERIFIED",
"agentVerificationContact": {
"partnerName": "John Doe",
"partnerEmailAddress": "john.doe@gmail.com",
"brandContactName": "Bob",
"brandContactEmailAddress": "bob@brand.com",
"brandWebsiteUrl": "https://www.brand.com"
}
}
Gửi nhân viên hỗ trợ để ra mắt
Bạn có thể gửi một nhân viên hỗ trợ để ra mắt trên một hoặc nhiều hãng vận chuyển. Một số đợt ra mắt do Google quản lý và một số đợt khác do nhà mạng quản lý trực tiếp. Các bản phát hành do hãng vận chuyển quản lý có thể có thêm các yêu cầu khác. Hãy xem bài viết Bản phát hành do Google quản lý so với bản phát hành do nhà mạng quản lý để biết thêm thông tin.
Trước khi có thể ra mắt nhân viên hỗ trợ lần đầu tiên, bạn cần gửi thông tin xác minh. Thao tác này cho phép Google, nhà mạng hoặc cả hai xác minh với người liên hệ của thương hiệu rằng bạn được uỷ quyền quản lý tác nhân thay cho họ. Hãy xem bài viết xác minh thương hiệu để biết thông tin chi tiết.
Sau khi gửi thông tin xác minh và hoàn tất các điều kiện tiên quyết để ra mắt, bạn có thể gửi yêu cầu ra mắt.
Bạn có thể gửi một nhân viên hỗ trợ để ra mắt trên một hoặc nhiều hãng vận chuyển. Bạn phải cung cấp bảng câu hỏi ra mắt đã hoàn tất trong yêu cầu ra mắt. Để biết thêm thông tin, hãy xem brands.agents.requestLaunch
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); let agentLaunch = { questionnaire: { contacts: [ { name: 'James Bond', title: 'Mr 0 0 7', email: 'someone@somewhere.com' } ], optinDescription: 'Users accepted our terms of service online.', triggerDescription: 'We are reaching preregistered users', interactionsDescription: 'This agent does not do much.', optoutDescription: 'Reply stop and we stop.', agentAccessInstructions: 'This is a a simple agent that reaches registered users.', videoUris: [ 'https://www.google.com/a/video' ], screenshotUris: [ 'https://www.google.com/a/screenshot' ] }, launchDetails: {} }; businessCommunicationsApiHelper.launchAgent(agent.name, agentLaunch).then((response) => { }).catch((err) => { console.log(err); });
Java
Optional<Questionnaire> q = Optional.of(AgentFactory.createRbmQuestionnaire()); AgentLaunch launch = api.requestRbmAgentLaunch(agent.getName(), regionIds, q); logger.info("RBM agent updated launch: " + launch);
Mã này trả về thông tin khởi chạy tác nhân:
{
"name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
"rcsBusinessMessaging": {
"questionnaire": {
"contacts": [
{
"name": "James Bond",
"title": "Mr O O 7",
"email": "someone@somewhere.com"
}
],
"optinDescription": "Users accepted our terms of service online.",
"triggerDescription": "We are reaching preregistered users",
"interactionsDescription": "This agent does not do much.",
"optoutDescription": "Reply stop and we stop.",
"agentAccessInstructions": "This is a a simple agent that reaches registered users.",
"videoUris": [
"https://www.google.com/a/video"
],
"screenshotUris": [
"https://www.google.com/a/screenshot"
]
},
"launchDetails": {
"/v1/regions/some-carrier": {
"launchState": "LAUNCH_STATE_PENDING",
"updateTime": "2023-02-24T15:02:13.903554Z"
}
},
"launchRegion": "NORTH_AMERICA"
}
}
Xin lưu ý rằng launchRegion
không được dùng nữa và sẽ sớm bị loại bỏ.
Ra mắt một nhân viên hỗ trợ cho một hoặc nhiều khu vực
Để chạy một tác nhân ở một hoặc nhiều khu vực, khi tác nhân chưa chạy trước đó, hãy gọi phương thức requestLaunch
bằng một đối tượng chứa bản đồ chỉ có các khoá cho tất cả các khu vực mà bạn muốn tác nhân chạy. Việc sử dụng một bản đồ trống cho phép duy trì tính nhất quán của API nội bộ trong các đối tượng được dùng giữa các lệnh gọi API.
curl -X POST \ "https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID:requestLaunch" \ -H "Content-Type: application/json" \ -H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \ -d "{ 'name': 'brands/BRAND_ID/agents/AGENT_ID/launch', 'rcsBusinessMessaging': { 'questionnaire': { 'contacts': [ { 'name': 'Contact person 000', 'title': 'Contact manager 000', 'email': 'user@domain.com000' } ], 'optinDescription': 'Opt-in description 0', 'triggerDescription': 'Trigger description 0', 'optoutDescription': 'Opt-out description 0', 'agentAccessInstructions': 'Agent instructions 0', 'videoUris': [ 'https://www.youtube.com/watch?v=NN75im_us4k' ], 'screenshotUris': [ 'https://www.youtube.com/watch?v=NN75im_us4k' ] }, 'launchDetails': { '/v1/regions/fi-rcs': {} } } }"
Để chạy một nhân viên hỗ trợ ở một hoặc nhiều khu vực (khi nhân viên hỗ trợ đã chạy trước đó), hãy gọi phương thức requestLaunch bằng một đối tượng chứa bản đồ chỉ các khoá của tất cả các khu vực mà nhân viên hỗ trợ đã chạy và tất cả các khu vực mà nhân viên hỗ trợ muốn chạy. Việc sử dụng một bản đồ trống giúp duy trì tính nhất quán của API nội bộ trong các đối tượng được dùng giữa các lệnh gọi API.
curl -X POST \ "https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID:requestLaunch" \ -H "Content-Type: application/json" \ -H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \ -d "{ 'name': 'brands/BRAND_ID/agents/AGENT_ID/launch', 'rcsBusinessMessaging': { 'launchDetails': { '/v1/regions/fi-rcs': {}, '/v1/regions/vodafone-idea-india': {} } } }"
Nếu một tác nhân gọi phương thức requestLaunch
nhưng không bao gồm tất cả các khu vực mà tác nhân đã được khởi chạy dưới dạng khoá, thì lỗi 400 - Bad Request
sẽ được gửi.
Tra cứu trạng thái ra mắt của nhân viên hỗ trợ
Bạn có thể truy xuất trạng thái khởi chạy hiện tại của một tác nhân. Để biết thêm thông tin, hãy xem brands.agents.getLaunch
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); businessCommunicationsApiHelper.getAgentLaunch(agent.name).then((response) => { }).catch((err) => { console.log(err); });
Java
AgentLaunch launch = api.getAgentLaunch(agent.getName()); logger.info("RBM agent launch: " + launch);
cURL
curl \ "https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID/launch" \ -H "Content-Type: application/json" \ -H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)"
Nếu hãng vận chuyển từ chối việc phát hành, thì đối tác có thể yêu cầu hãng vận chuyển phát hành lại (yêu cầu có trạng thái UNSPECIFIED
và hệ thống phụ trợ có trạng thái REJECTED
).
Mã này trả về thông tin ra mắt và trạng thái ra mắt của từng nhà mạng mục tiêu:
{
"name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
"rcsBusinessMessaging": {
"questionnaire": {
"contacts": [
{
"name": "James Bond",
"title": "Mr O O 7",
"email": "someone@somewhere.com"
}
],
"optinDescription": "Users accepted our terms of service online.",
"triggerDescription": "We are reaching preregistered users",
"interactionsDescription": "This agent does not do much.",
"optoutDescription": "Reply stop and we stop.",
"agentAccessInstructions": "This is a a simple agent that reaches registered users.",
"videoUris": [
"https://www.google.com/a/video"
],
"screenshotUris": [
"https://www.google.com/a/screenshot"
]
},
"launchDetails": {
"/v1/regions/some-carrier": {
"launchState": "LAUNCH_STATE_PENDING",
"updateTime": "2023-02-24T15:02:13.903554Z"
}
},
"launchRegion": "NORTH_AMERICA"
}
}
Xin lưu ý rằng launchRegion
không được dùng nữa và sẽ sớm bị xoá.
Thêm các hãng vận chuyển khác vào lần ra mắt của một đại lý
Sau khi truy xuất thông tin triển khai hiện tại cho hãng vận chuyển bằng lệnh gọi API brands.agents.getLaunch
, bạn có thể thêm nhiều hãng vận chuyển mục tiêu hơn để mở rộng phạm vi tiếp cận của hãng vận chuyển. Để biết thêm thông tin, hãy xem brands.agents.updateLaunch
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);'); // To launch an agent to further carriers, we need to first obtain the existing // launch information and extend it with the new carrier(s). businessCommunicationsApiHelper.getAgentLaunch(agent.name).then((response) => { let existingLaunch = response.data.rcsBusinessMessaging; // Now we add the new carrier to the existing launch existingLaunch.launchDetails[config.launchCarrier2] = null; // And we submit the launch again businessCommunicationsApiHelper.launchAgent(agent.name, existingLaunch).then((response) => { console.log('Launch details are:'); console.log(JSON.stringify(response.data, null, 2)); }).catch((err) => { console.log(err); }); }).catch((err) => { console.log(err); });
Mã này trả về thông tin khởi chạy đã cập nhật:
{
"name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
"rcsBusinessMessaging": {
"questionnaire": {
"contacts": [
{
"name": "James Bond",
"title": "Mr O O 7",
"email": "someone@somewhere.com"
}
],
"optinDescription": "Users accepted our terms of service online.",
"triggerDescription": "We are reaching preregistered users",
"interactionsDescription": "This agent does not do much.",
"optoutDescription": "Reply stop and we stop.",
"agentAccessInstructions": "This is a a simple agent that reaches registered users.",
"videoUris": [
"https://www.google.com/a/video"
],
"screenshotUris": [
"https://www.google.com/a/screenshot"
]
},
"launchDetails": {
"/v1/regions/some-carrier": {
"launchState": "LAUNCH_STATE_PENDING",
"updateTime": "2023-02-24T15:02:13.903554Z"
},
"/v1/regions/another-carrier": {
"launchState": "LAUNCH_STATE_PENDING",
"updateTime": "2023-02-24T15:04:50.456552Z"
}
},
"launchRegion": "NORTH_AMERICA"
}
}
Sau khi phát hành và bảo trì
Liệt kê tất cả nhân viên hỗ trợ được tạo cho một thương hiệu
Nhà phát triển có thể truy xuất danh sách tất cả các tác nhân mà họ đã tạo cho một thương hiệu.
Để biết thêm thông tin, hãy xem brands.agents.list
.
Node.js
const businessCommunicationsApiHelper = require('@google/rbm-businesscommunications'); const privateKey = require('../../resources/businesscommunications-service-account-credentials.json'); businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey); businessCommunicationsApiHelper.listAgents(brand.name).then((response) => { console.log('Current agents are:'); console.log(response.data); datastore.saveJsonData('agents', response.data.agents); }).catch((err) => { console.log(err); });
Java
Brand brand = api.getBrand(brandId); logger.info("Brand: " + brand); ListAgentsResponse response = api.listAllAgents(brand); List<Agent> agents = response.getAgents().stream() .sorted(Comparator.comparing(Agent::getName)).collect(Collectors.toList()); logger.info(String.format("Found %d agents", response.getAgents().size())); for (Agent agent : agents) { logger.info(String.format("Agent [%s]: '%s'", agent.getName(), agent.getDisplayName())); }
Mã này trả về danh sách tất cả các nhân viên thuộc quyền sở hữu của thương hiệu:
{
agents: [
{
name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent',
displayName: 'My new agent',
rcsBusinessMessagingAgent: [Object]
},
{
name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent',
displayName: 'My second agent',
rcsBusinessMessagingAgent: [Object]
},
{
name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_helof85o_agent',
displayName: 'My third agent',
rcsBusinessMessagingAgent: [Object]
}
]
}
Huỷ ra mắt trợ lý ảo
Để huỷ ra mắt một tác nhân ở một khu vực cụ thể, hãy gọi phương thức updateLaunch
, chỉ định khu vực mục tiêu trong bản đồ của lệnh gọi và đặt launchState
thành LAUNCH_STATE_UNLAUNCHED
.
curl -X PATCH \ "https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID" \ -H "Content-Type: application/json" \ -H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)"\ -d "{ 'rcsBusinessMessaging': { 'launchDetails': { '/v1/regions/fi-rcs': { 'launchState': 'LAUNCH_STATE_UNLAUNCHED' }, '/v1/regions/vodafone-idea-india': { 'launchState': 'LAUNCH_STATE_UNLAUNCHED' } } } }"
Xoá nhân viên hỗ trợ
Vì lý do bảo mật, bạn không thể xoá nhân viên hỗ trợ RBM nữa. Hãy liên hệ với Nhóm hỗ trợ RBM để được trợ giúp.