Все агенты принадлежат к бренду (компании, организации или группе). Прежде чем создать агента, необходимо создать владеющий им бренд. Бренды носят исключительно организационный характер и помогают объединять связанных агентов в группы.
Приведенные на этой странице фрагменты кода взяты из примеров на Java и Node.js.
Создание и определение агентов
Создать агента
Для создания агента RBM необходимо определить его основные данные .
Для получения более подробной информации см. brands.agents.create .
cURL
curl -v -X POST "https://businesscommunications.googleapis.com/v1/$BRAND_ID/agents" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/business-messaging" \ -H "`oauth2l header --json rbm-developer-service-account-credentials.json businesscommunications`" \ -d "{ 'displayName': 'My test agent', 'rcsBusinessMessagingAgent': { 'description': 'My agent description', 'logoUri': 'https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf', 'heroUri': 'https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP', 'phoneNumbers': [ { 'phoneNumber': { 'number': '+44800088088' }, 'label': 'My number' } ], 'emails': [ { 'address': 'support@demo.test', 'label': 'My email' } ], 'websites': [ { 'uri': 'https://a.demo.test/', 'label': 'My site' } ], 'privacy': { 'uri': 'https://a.demo.test/privacy', 'label': 'My privacy policy' }, 'termsConditions': { 'uri': 'https://a.demo.test/terms', 'label': 'My terms' }, 'color': '#FFFFFF', 'billingConfig': { 'billingCategory': 'CONVERSATIONAL' }, 'agentUseCase': 'TRANSACTIONAL', 'hostingRegion': 'EUROPE' } }"
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: 'NON_CONVERSATIONAL' }, 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);
Этот код возвращает информацию о новом агенте и уникальный идентификатор, присвоенный агенту:
{
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: 'NON_CONVERSATIONAL' },
agentUseCase: 'MULTI_USE',
hostingRegion: 'EUROPE'
}
}
Найдите определение агента.
Получить информацию об агенте можно, указав его уникальный идентификатор ( name ). Дополнительные сведения см. в разделе 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);
Этот код возвращает информацию об агенте:
{
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: 'NON_CONVERSATIONAL' },
agentUseCase: 'MULTI_USE',
hostingRegion: 'EUROPE'
}
}
Проверка и запуск
Предоставьте подтверждающую информацию.
Для запуска агента требуется подтверждение бренда . Необходимо предоставить подтверждающую информацию до подачи заявки на запуск. Обратите внимание, что вам не нужно ждать одобрения бренда перед подачей заявки на запуск; одобрение бренда происходит в рамках процесса утверждения запуска.
Для получения более подробной информации см. 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);
Этот код возвращает информацию для проверки:
{
"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/"
}
}
Проверьте контактные данные агента для подтверждения личности.
Вы можете получить информацию о статусе подтверждения бренда агента. Для получения более подробной информации см. 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);
Этот код возвращает статус проверки и информацию о партнере:
{
"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"
}
}
Отправьте агента для запуска
Вы можете отправить заявку на запуск агента у одного или нескольких операторов связи. Некоторые запуски управляются Google, а другие — непосредственно операторами связи. Запуски, управляемые операторами связи, могут иметь дополнительные требования. Дополнительную информацию см. в разделе «Запуски, управляемые Google, против запусков, управляемых операторами связи» .
Прежде чем впервые запустить агента, вам необходимо предоставить информацию для верификации . Это позволит Google, операторам связи или обоим подтвердить у вашего представителя бренда, что вы уполномочены управлять агентом от их имени. Подробности см. в разделе «Верификация бренда» .
После того, как вы предоставите подтверждающую информацию и выполните все необходимые условия для запуска , вы сможете отправить запрос на запуск.
Вы можете подать заявку на запуск агента у одного или нескольких операторов связи. Заполненная анкета для запуска должна быть предоставлена в рамках заявки на запуск. Для получения более подробной информации см. brands.agents.requestLaunch .
cURL
curl -v -X POST "https://businesscommunications.googleapis.com/v1/$AGENT_ID:requestLaunch" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/business-messaging" \ -H "`oauth2l header --json rbm-developer-service-account-credentials.json businesscommunications`" \ -d "{ 'agentLaunch': { 'rcsBusinessMessaging': { 'questionnaire': { 'contacts': [ { 'name': 'John Doe', 'title': 'Product Owner', 'email': 'support@demo.test' } ], 'optinDescription': 'Thanks for your request.', 'triggerDescription': 'Promotional messages will be triggered in a timely manner.', 'interactionsDescription': 'Promotional messages are one way.', 'optoutDescription': 'Sorry to see you go.', 'agentAccessInstructions': 'Thanks for your request.', 'videoUris': [ 'https://d2q4iodazzzt8b.cloudfront.net/MicrosoftTeamsvideo2_1758533835.mp4' ], 'screenshotUris': [ 'https://rm.virbm.com/Il9ChvVEhS1na5mr/ee9bc94b468a40688fb7fc71cb1c069c.png' ] }, 'launchDetails': { '/v1/regions/$CARRIER_ID': {} } } } }"
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);
Этот код возвращает информацию о запуске агента:
{
"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"
}
}
Обратите внимание, что launchRegion устарела и в ближайшее время будет удалена.
Запустите агента в одном или нескольких регионах.
Чтобы запустить агента в одном или нескольких регионах, если агент ранее не запускался, вызовите метод requestLaunch с объектом, содержащим карту, содержащую только ключи для всех регионов, в которые вы хотите запустить агента. Использование пустой карты позволяет поддерживать внутреннюю согласованность API в объектах, используемых между вызовами 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': {} } } }"
Чтобы запустить агента в одном или нескольких регионах (если агент уже запускался ранее), вызовите метод requestLaunch с объектом, содержащим карту, в которой указаны только ключи всех регионов, в которых агент уже запущен, и всех регионов, в которые агент хочет запуститься. Использование пустой карты позволяет поддерживать внутреннюю согласованность API в объектах, используемых между вызовами 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': {} } } }"
Если агент вызывает метод requestLaunch , но не включает в качестве ключей все регионы, где агент уже запущен, генерируется ошибка 400 - Bad Request .
Узнайте статус запуска агента.
Вы можете получить текущий статус запуска агента. Для получения более подробной информации см. 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);
Если запуск отклонен оператором связи, партнер может повторно запросить запуск у этого же оператора (запрос имеет состояние UNSPECIFIED , а бэкэнд — состояние REJECTED ).
Этот код возвращает информацию о запуске и статус запуска для каждого целевого оператора связи:
{
"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"
}
}
Обратите внимание, что launchRegion устарела и в ближайшее время будет удалена.
Добавьте дополнительных перевозчиков в список запуска агента.
После получения актуальной информации о запуске вашего агента с помощью вызова API brands.agents.getLaunch вы можете добавить больше целевых операторов связи, чтобы расширить охват вашего агента. Для получения более подробной информации см. 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); });
Этот код возвращает обновленную информацию о запуске:
{
"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"
}
}
После запуска и техническое обслуживание
Перечислите всех агентов, созданных для данного бренда.
Разработчик может получить список всех агентов, созданных им для определенного бренда. Для получения более подробной информации см. 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())); }
Этот код возвращает список всех агентов, принадлежащих бренду:
{
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]
}
]
}
Отменить запуск агента
Чтобы отменить запуск агента из определенного региона, вызовите метод updateLaunch , укажите целевой регион на карте вызова и установите launchState в значение 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' } } } }"
Удалить агента
В целях безопасности агенты RBM больше не могут быть удалены. Обратитесь в службу поддержки RBM за помощью.