Agents mit der RBM Operations API verwalten

Der zentrale RBM-Workflow für Mobilfunkanbieter umfasst das Überprüfen von Informationen zu neuen Agents und das Genehmigen oder Ablehnen der Berechtigung, diese im Netzwerk des Mobilfunkanbieters zu starten und Nachrichten an die Abonnenten zu senden.

Die Code-Snippets auf dieser Seite stammen aus unseren JavaScript und Curl Beispielen.

Alle an einen Mobilfunkanbieter gesendeten Agents auflisten

Der Mobilfunkanbieter kann eine Liste aller Agents abrufen, die von Entwicklern zum Starten im Netzwerk des Mobilfunkanbieters eingereicht wurden.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

// Retrieve all agents targeting the carrier
businessCommunicationsApiHelper.listAgents('brands/-').then((response) => {
  console.log('Current agents are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

Die Marke ist auf „-“ festgelegt, da sie beim Abrufen einer Liste aller Agents nicht erforderlich ist.

Dieser Code gibt eine Liste aller Agents zurück, die zum Starten beim Mobilfunkanbieter eingereicht wurden:

{
  "agents": [
    {
      "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_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": [
          {
            "phoneNumber": {
              "number": "+12223334444"
            },
            "label": "Call support"
          }
        ],
        "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": "NORTH_AMERICA",
        "partner": {
          "partnerId": "unique-identifier-for-my-partner",
          "displayName": "My partner",
          "company": "Public name of the company for my partner"
        }
      }
    },
    {
      "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent",
      "displayName": "My second agent",
      "rcsBusinessMessagingAgent": {
        "description": "Another agent description",
        "logoUri": "https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf",
        "heroUri": "https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP",
        "phoneNumbers": [
          {
            "phoneNumber": {
              "number": "+12228885768"
            },
            "label": "Call support"
          }
        ],
        "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": "CONVERSATIONAL"
        },
        "agentUseCase": "PROMOTIONAL",
        "hostingRegion": "NORTH_AMERICA",
        "partner": {
          "partnerId": "unique-identifier-for-my-partner",
          "displayName": "My partner",
          "company": "Public name of the company for my partner"
        }
      }
    }
  ]
}

Die Ergebnisse können seitenweise abgerufen werden. Weitere Informationen finden Sie in der API-Referenz.

Informationen zur Agent-Verifizierung abrufen

Der Mobilfunkanbieter kann den Status der Markenverifizierung eines Agents 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(agents[0].name).then((response) => {
  }).catch((err) => {
    console.log(err);
  });

cURL

  curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/verification" \
    -H "Content-Type: application/json" \
    -H "User-Agent: curl/business-messaging" \
    -H "`oauth2l header --json serviceAccount.json businesscommunications`"

Der Aufrufer benötigt nicht unbedingt den vollständigen Namen des Agents, einschließlich des Markennamens. Es ist nur die Agent-ID (vor @rbm.goog) erforderlich, wobei der Markenname auf „-“ festgelegt ist.

Dieser Code gibt den Verifizierungsstatus und die Partnerinformationen zurück:

{
  "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"
  }
}

Startstatus und Fragebogen für Agents abrufen

Der Mobilfunkanbieter kann den aktuellen Startstatus eines Agents und den Fragebogen zum Starten für Entwickler abrufen.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.getAgentLaunch(agents[0].name).then((response) => {
  console.log('Launch details are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/launch" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

Dieser Code gibt die Startinformationen zurück:

{
  "name": "brands/8b5c7f80-b025-486b-bc8a-2d0797559711/agents/my-agent-demo/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Mr",
          "email": "johndoe@developer.com"
        }
      ],
      "optinDescription": "Messages are sent to known MSISDNs",
      "triggerDescription": "We respond to any interaction",
      "interactionsDescription": "Simple conversations with a chatbot",
      "optoutDescription": "User sends stop"
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_LAUNCHED",
        "updateTime": "2023-02-20T15:10:36.528669Z"
      }
    }
  }
}

Agent-Definition suchen

Der Mobilfunkanbieter kann die Informationen eines Agents anhand seiner eindeutigen ID (name) abrufen.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.getAgent(agent[0].name).then((response) => {
  console.log('Agent details are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

Dieser Code gibt die Agent-Informationen zurück:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_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": [
      {
        "phoneNumber": {
          "number": "+12223334444"
        },
        "label": "Call support"
      }
    ],
    "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": "NORTH_AMERICA",
    "partner": {
      "partnerId": "unique-identifier-for-my-partner",
      "displayName": "My partner",
      "company": "Public name of the company for my partner"
    }
  }
}

Startstatus von Agents ändern

Ein Mobilfunkanbieter kann den Startstatus eines Agents aktualisieren und einen Kommentar hinzufügen, in dem der Grund für die Statusänderung erläutert wird.

Hinweis: Die Anforderungen für das Feld comment variieren je nach Aktion:

Optional: Startgenehmigungen.
Erforderlich: Ablehnungen, Sperrungen und Anfragen zum Beenden des Starts.

Dieser Kommentar wird dem Entwickler in einer E-Mail gesendet, ist in der Agent-Historie der Admin-Konsole und Business Communications Console sichtbar und in AgentLaunchEvent Webhooks enthalten. Diese Übermittlung gilt für alle Statusaktualisierungen.

Der Status sollte wie folgt geändert werden:

LAUNCH_STATE_PENDING in LAUNCH_STATE_LAUNCHED oder LAUNCH_STATE_REJECTED
LAUNCH_STATE_LAUNCHED in LAUNCH_STATE_SUSPENDED
LAUNCH_STATE_SUSPENDED in LAUNCH_STATE_LAUNCHED oder LAUNCH_STATE_UNLAUNCHED

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper
	.updateAgentLaunchState(agentId, 'LAUNCH_STATE_LAUNCHED').then((response) => {
		console.log('Updated launch details are:');
		console.log(JSON.stringify(response.data, null, 2));
	});

cURL

curl -v -X PATCH "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/launch" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`" \
  -d "{
    'rcsBusinessMessaging': {
      'launchDetails': {
        '': {
          'launchState': 'LAUNCH_STATE_LAUNCHED',
        }
      }
    }
  }"

Dieser Code gibt die aktualisierten Startinformationen mit dem geänderten Startstatus zurück:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Contact manager",
          "email": "john.doe@gmail.com"
        }
      ],
      "optinDescription": "Users accepted our terms of service online.",
      "triggerDescription": "We are reaching pre-registered users",
      "interactionsDescription": "This agent sends notifications and processes suggested replies.",
      "optoutDescription": "Reply stop and we stop.",
      "agentAccessInstructions": "This is a simple agent that reaches registered users.",
      "videoUris": [
        "https://www.google.com/a/video"
      ],
      "screenshotUris": [
        "https://www.google.com/a/screenshot"
      ]
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_REJECTED",
        "comment": "We don't have a billing contract in place with you.", // Note: The field is optional only for launch approval; otherwise, required.
        "updateTime": "2023-04-28T15:22:10.221191Z"
      }
    }
  }
}

Agents ein- oder ausblenden

Damit Ihr Arbeitsbereich übersichtlich bleibt, können Sie Agents ausblenden, die in Ihrem Netzwerk nicht mehr verwendet werden. Wenn Sie einen Agent ausblenden, wird er aus den Standardergebnissen der API-Suche entfernt.

Das Ausblenden ist nur eine Änderung der Sichtbarkeit. Es wirkt sich nur auf die Ansicht für Ihren spezifischen Mobilfunkanbieter aus und hat keine Auswirkungen auf den Status des Agents für den Partner oder andere Mobilfunkanbieter. Sie können einen Agent jederzeit wieder einblenden, um seine Sichtbarkeit wiederherzustellen und ihn weiter zu verwalten.

Damit aktive Agents nicht versehentlich ausgeblendet werden, gelten die folgenden Regeln:

Berechtigung: Sie können nur Agents ausblenden, die in Ihrem Netzwerk inaktiv sind: Gesperrt oder Abgelehnt.
Einschränkungen: Sie können einen Agent nicht ausblenden, wenn sein Startstatus in Ihrem Netzwerk Gestartet oder Ausstehend ist. Wenn Sie versuchen, einen solchen Agent auszublenden, wird die Anfrage mit dem Fehler FAILED_PRECONDITION abgelehnt.

Status für Ausblenden aktualisieren

Wenn Sie den Start eines Agents für Ihren Mobilfunkanbieter ein- oder ausblenden möchten, verwenden Sie die Methode setAgentLaunchVisibility für die Startressource. Setzen Sie den booleschen Wert isHidden auf true, um den Agent auszublenden, und auf false, um ihn einzublenden.

Methode: POST /v1/brands/{brandId}/agents/{agentId}/launch:setAgentLaunchVisibility

curl -v -X POST "https://businesscommunications.googleapis.com/v1/brands/$BRAND_ID/agents/$AGENT_ID/launch:setAgentLaunchVisibility" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "$(oauth2l header --json serviceAccount.json businesscommunications)" \
  --data '{
    "name": "brands/$BRAND_ID/agents/$AGENT_ID/launch",
    "isHidden": true
  }'

{
  "name": "brands/8b5c7f80-b025-486b-bc8a-2d0797559711/agents/my-agent-demo/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Mr",
          "email": "johndoe@developer.com"
        }
      ],
      "optinDescription": "Messages are sent to known MSISDNs",
      "triggerDescription": "We respond to any interaction",
      "interactionsDescription": "Simple conversations with a chatbot",
      "optoutDescription": "User sends stop"
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_SUSPENDED",
        "updateTime": "2026-02-20T15:10:36.528669Z",
        "isHidden": true
      }
    }
  }
}

Agents mit Filtern auflisten

Standardmäßig werden Agents, die von Ihrem Mobilfunkanbieter ausgeblendet wurden, von der Methode list ausgeschlossen. Wenn Sie sie in Ihre Ergebnisse einbeziehen möchten, verwenden Sie den Parameter includeHidden.

KI-Agent löschen

Aus Sicherheitsgründen können RBM-Agents nicht mehr gelöscht werden. Wenn Sie Hilfe benötigen, wenden Sie sich an das RCS for Business-Supportteam.

Agents mit der RBM Operations API verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Alle an einen Mobilfunkanbieter gesendeten Agents auflisten

Node.js

cURL

Informationen zur Agent-Verifizierung abrufen

Node.js

cURL

Startstatus und Fragebogen für Agents abrufen

Node.js

cURL

Agent-Definition suchen

Node.js

cURL

Startstatus von Agents ändern

Node.js

cURL

Agents ein- oder ausblenden

Status für Ausblenden aktualisieren

Agents mit Filtern auflisten

KI-Agent löschen

Agents mit der RBM Operations API verwalten