Alle Agents gehören zu einer Marke (Unternehmen, Organisation oder Gruppe). Bevor ein Agent erstellt werden kann, muss eine zugehörige Marke erstellt werden. Marken sind rein organisatorisch und helfen Ihnen, ähnliche Agents zu gruppieren.
Die Code-Snippets auf dieser Seite stammen aus den Java-Beispielen und den Node.js-Beispielen.
Agent erstellen und definieren
Agent erstellen
Wenn Sie einen RBM-Agent erstellen möchten, müssen Sie seine grundlegenden Informationen definieren.
Weitere Informationen finden Sie unter 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);
Dieser Code gibt die neuen Agent-Informationen und eine eindeutige Kennung zurück, die dem Agent zugewiesen ist:
{
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'
}
}
Agent-Definition nachschlagen
Sie können einen Agent abrufen, indem Sie seine eindeutige Kennung (name
) angeben. Weitere Informationen finden Sie unter 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);
Dieser Code gibt die Informationen zum Kundenservicemitarbeiter zurück:
{
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'
}
}
Überprüfung und Einführung
Bestätigungsinformationen einreichen
Für die Aktivierung des Agents ist eine Markenüberprüfung erforderlich. Sie müssen vor dem Senden eines Aktivierungsantrags Bestätigungsinformationen einreichen. Sie müssen nicht auf die Markengenehmigung warten, bevor Sie den Startantrag stellen. Die Markengenehmigung erfolgt im Rahmen des Genehmigungsprozesses für den Start.
Weitere Informationen finden Sie unter 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);
Dieser Code gibt die Bestätigungsinformationen zurück:
{
"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/"
}
}
Informationen zur Agent-Verifizierung aufrufen
Sie können den Status der Markenüberprüfung eines Kundenservicemitarbeiters abrufen. Weitere Informationen finden Sie unter 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);
Mit diesem Code werden der Bestätigungsstatus und Partnerinformationen zurückgegeben:
{
"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"
}
}
Agent zur Aktivierung einreichen
Sie können einen Agenten für die Einführung bei einem oder mehreren Mobilfunkanbietern einreichen. Einige Produkteinführungen werden von Google verwaltet, andere direkt von Mobilfunkanbietern. Für die vom Mobilfunkanbieter verwalteten Veröffentlichungen gelten möglicherweise zusätzliche Anforderungen. Weitere Informationen finden Sie unter Von Google verwaltete und von Mobilfunkanbietern verwaltete Markteinführungen.
Bevor Sie einen Agent zum ersten Mal aktivieren können, müssen Sie Bestätigungsinformationen einreichen. So können Google und/oder Mobilfunkanbieter bei Ihrem Markenansprechpartner bestätigen, dass Sie berechtigt sind, den Agenten in seinem Namen zu verwalten. Weitere Informationen zur Markenüberprüfung
Sobald Sie die Bestätigungsinformationen eingereicht und die Voraussetzungen für die Einführung erfüllt haben, können Sie eine Einführungsanfrage senden.
Sie können einen Agenten für die Einführung bei einem oder mehreren Mobilfunkanbietern einreichen. Der ausgefüllte Fragebogen für die Einführung muss als Teil des Antrags auf Einführung eingereicht werden. Weitere Informationen finden Sie unter 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);
Dieser Code gibt die Informationen zum Starten des Agents zurück:
{
"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
ist veraltet und wird demnächst entfernt.
Agent in einer oder mehreren Regionen einführen
Wenn Sie einen Agent in einer oder mehreren Regionen einführen möchten, in denen er noch nicht eingeführt wurde, rufen Sie die Methode requestLaunch
mit einem Objekt auf, das eine Karte mit nur Schlüsseln für alle Regionen enthält, in denen der Agent eingeführt werden soll. Durch die Verwendung einer leeren Karte kann die interne API-Konsistenz in den Objekten, die zwischen API-Aufrufen verwendet werden, aufrechterhalten werden.
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': {} } } }"
Wenn Sie einen Agent in einer oder mehreren Regionen starten möchten (wenn der Agent bereits gestartet wurde), rufen Sie die Methode requestLaunch mit einem Objekt auf, das eine Zuordnung von nur Schlüsseln von allen Regionen enthält, in denen der Agent bereits gestartet wurde und allen Regionen, in denen der Agent gestartet werden soll. Durch die Verwendung einer leeren Karte kann die interne API-Konsistenz der zwischen API-Aufrufen verwendeten Objekte aufrechterhalten werden.
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': {} } } }"
Wenn ein Agent die Methode requestLaunch
aufruft, aber nicht alle Regionen, in denen der Agent bereits eingeführt wurde, als Schlüssel angibt, wird ein 400 - Bad Request
-Fehler ausgegeben.
Aktivierungsstatus eines Agents nachschlagen
Sie können den aktuellen Einführungsstatus eines Agents abrufen. Weitere Informationen finden Sie unter 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)"
Wenn ein Start vom Mobilfunkanbieter abgelehnt wird, kann ein Partner den Start beim Mobilfunkanbieter noch einmal beantragen (die Anfrage hat den Status UNSPECIFIED
und das Backend den Status REJECTED
).
Dieser Code gibt die Informationen und den Aktivierungsstatus für jeden Zielanbieter zurück:
{
"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
wurde eingestellt und wird demnächst entfernt.
Einem Agenten-Launch zusätzliche Mobilfunkanbieter hinzufügen
Nachdem Sie die aktuellen Informationen zur Einführung Ihres Agents mit dem API-Aufruf brands.agents.getLaunch
abgerufen haben, können Sie weitere Zielanbieter hinzufügen, um die Reichweite Ihres Agents zu erhöhen. Weitere Informationen finden Sie unter 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); });
Dieser Code gibt die aktualisierten Informationen zum Start zurück:
{
"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"
}
}
Nach der Markteinführung und Wartung
Alle für eine Marke erstellten Agents auflisten
Der Entwickler kann eine Liste aller Agents abrufen, die er für eine Marke erstellt hat.
Weitere Informationen finden Sie unter 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())); }
Dieser Code gibt eine Liste aller Agents zurück, die der Marke gehören:
{
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]
}
]
}
Agent zurückziehen
Wenn Sie die Einführung eines Agents in einer bestimmten Region zurückziehen möchten, rufen Sie die Methode updateLaunch
auf, geben Sie die Zielregion in der Karte des Aufrufs an und legen Sie launchState
auf LAUNCH_STATE_UNLAUNCHED
fest.
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' } } } }"
Agent löschen
Aus Sicherheitsgründen können RBM-Agents nicht mehr gelöscht werden. Wenden Sie sich an den RBM-Support, um Unterstützung zu erhalten.