Gérer les agents avec l'API RBM Operations

Le workflow RBM de base pour les opérateurs inclut l'examen des informations sur les nouveaux agents, ainsi que l'approbation ou le refus de leur autorisation de lancement sur le réseau de l'opérateur et d'envoi de messages à leurs abonnés.

Les extraits de code de cette page proviennent de nos exemples JavaScript et Curl.

Lister tous les agents envoyés à un opérateur

L'opérateur peut obtenir la liste de tous les agents que les développeurs ont soumis pour le lancement sur son réseau.

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`"

La marque est définie sur -, car elle n'est pas requise lors de la récupération d'une liste de tous les agents.

Ce code renvoie la liste de tous les agents envoyés pour le lancement chez l'opérateur :

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

Les résultats peuvent être récupérés une page à la fois. Pour en savoir plus, consultez la documentation de référence de l'API.

Obtenir les informations de validation de l'agent

Le transporteur peut obtenir l'état de la validation de la marque d'un agent. Pour en savoir plus, consultez 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`"

L'appelant n'a pas nécessairement besoin du nom complet de l'agent, y compris le nom de la marque. Seul l'ID de l'agent (avant @rbm.goog) est obligatoire, avec le nom de la marque défini sur -.

Ce code renvoie l'état de validation et les informations sur le partenaire :

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

Obtenir l'état du lancement de l'agent et le questionnaire

L'opérateur peut obtenir l'état de lancement actuel d'un agent et le questionnaire de lancement du développeur.

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`"

L'appelant n'a pas nécessairement besoin du nom complet de l'agent, y compris le nom de la marque. Seul l'ID de l'agent (avant @rbm.goog) est obligatoire, avec le nom de la marque défini sur -.

Ce code renvoie les informations de lancement :

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

Rechercher une définition d'agent

L'opérateur peut récupérer les informations d'un agent à l'aide de son identifiant unique (name).

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`"

L'appelant n'a pas forcément besoin du nom complet de l'agent, y compris le nom de la marque. Seul l'ID de l'agent (avant @rbm.goog) est obligatoire, avec le nom de la marque défini sur -.

Ce code renvoie les informations sur l'agent :

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

Modifier l'état du lancement de l'agent

Un opérateur peut modifier l'état de lancement d'un agent et inclure un commentaire expliquant le motif du changement d'état.

Remarque : Les exigences concernant le champ comment varient selon l'action :

Facultatif : Approbations de lancement.
Obligatoire : demandes de refus, de suspension et d'annulation du lancement.

Ce commentaire est envoyé au développeur par e-mail. Il est visible dans l'historique de l'agent des consoles Administration et Communications d'entreprise, et inclus dans les notifications AgentLaunchEvent webhook. Cette méthode de diffusion s'applique à toutes les mises à jour de l'état.

L'état doit être modifié comme suit :

LAUNCH_STATE_PENDING à LAUNCH_STATE_LAUNCHED ou LAUNCH_STATE_REJECTED
De LAUNCH_STATE_LAUNCHED à LAUNCH_STATE_SUSPENDED
LAUNCH_STATE_SUSPENDED à LAUNCH_STATE_LAUNCHED ou LAUNCH_STATE_UNLAUNCHED

L'appelant n'a pas forcément besoin du nom complet de l'agent, y compris le nom de la marque. Seul l'ID de l'agent (avant @rbm.goog) est obligatoire, avec le nom de la marque défini sur -.

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',
        }
      }
    }
  }"

Ce code renvoie les informations de lancement mises à jour avec l'état de lancement modifié :

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

Masquer ou afficher des agents

Pour que votre espace de travail reste propre et organisé, vous pouvez masquer les agents qui ne sont plus utilisés sur votre réseau. Masquer un agent le supprime des résultats de découverte de l'API par défaut.

Le masquage ne modifie que la visibilité. Elle n'affecte que la vue pour votre opérateur spécifique et n'a aucune incidence sur l'état de l'agent pour le partenaire ou les autres opérateurs. Vous pouvez rendre un agent de nouveau visible à tout moment pour continuer à le gérer.

Pour s'assurer que les agents actifs ne sont pas supprimés accidentellement de la vue, les règles suivantes s'appliquent :

Éligibilité : vous ne pouvez masquer que les agents dont l'état est inactif sur votre réseau (Suspendu ou Refusé).
Restrictions : Vous ne pouvez pas masquer un agent si son état de lancement sur votre réseau est Lancé ou En attente. Si vous tentez de masquer un tel agent, la requête sera rejetée et une erreur FAILED_PRECONDITION s'affichera.

Modifier l'état de masquage

Pour masquer ou afficher le lancement d'un agent pour votre opérateur, utilisez la méthode setAgentLaunchVisibility sur la ressource de lancement. Pour masquer, définissez le booléen isHidden sur true et, pour afficher, définissez-le sur false.

Méthode : 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
      }
    }
  }
}

Lister les agents avec des filtres

Par défaut, la méthode list exclut les agents masqués par votre opérateur. Pour les inclure dans vos résultats, utilisez le paramètre includeHidden.

Supprimer un agent

Pour des raisons de sécurité, il n'est plus possible de supprimer les agents RBM. Pour obtenir de l'aide, contactez l'équipe d'assistance RCS for Business.

Gérer les agents avec l'API RBM Operations Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Lister tous les agents envoyés à un opérateur

Node.js

cURL

Obtenir les informations de validation de l'agent

Node.js

cURL

Obtenir l'état du lancement de l'agent et le questionnaire

Node.js

cURL

Rechercher une définition d'agent

Node.js

cURL

Modifier l'état du lancement de l'agent

Node.js

cURL

Masquer ou afficher des agents

Modifier l'état de masquage

Lister les agents avec des filtres

Supprimer un agent

Gérer les agents avec l'API RBM Operations