Gestisci gli agenti con l'API RBM Operations

Il flusso di lavoro RBM principale per gli operatori include la revisione delle informazioni sui nuovi agenti e l'approvazione o il rifiuto dell'autorizzazione per il lancio sulla rete dell'operatore e l'invio di messaggi ai loro abbonati.

Gli snippet di codice in questa pagina sono tratti dai nostri esempi JavaScript e Curl.

Elenca tutti gli agenti inviati a un operatore

L'operatore può ottenere un elenco di tutti gli agenti che gli sviluppatori hanno inviato per il lancio sulla rete dell'operatore.

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

Il brand è impostato su - perché non è obbligatorio quando si recupera un elenco di tutti gli agenti.

Questo codice restituisce un elenco di tutti gli agenti inviati per il lancio presso l'operatore:

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

I risultati possono essere recuperati una pagina alla volta. Per informazioni dettagliate, consulta il Riferimento API.

Recuperare le informazioni di verifica dell'agente

Il corriere può ottenere lo stato della verifica del brand di un agente. Per maggiori dettagli, vedi 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`"

Il chiamante non ha necessariamente bisogno del nome completo dell'agente, incluso il nome del brand. È richiesto solo l'ID agente (prima di @rbm.goog), con il nome del brand impostato su -.

Questo codice restituisce lo stato di verifica e le informazioni del partner:

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

Visualizzare lo stato del lancio dell'agente e il questionario

L'operatore può ottenere lo stato di lancio attuale di un agente e il questionario di lancio dello sviluppatore.

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

Il chiamante non ha necessariamente bisogno del nome completo dell'agente, incluso il nome del brand. È richiesto solo l'ID agente (prima di @rbm.goog), con il nome del brand impostato su -.

Questo codice restituisce le informazioni di lancio:

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

Cercare la definizione di un agente

L'operatore può recuperare le informazioni di un agente utilizzando il suo identificatore univoco (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`"

La persona che chiama non ha necessariamente bisogno del nome completo dell'agente, incluso il nome del brand. È richiesto solo l'ID agente (prima di @rbm.goog), con il nome del brand impostato su -.

Questo codice restituisce le informazioni dell'agente:

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

Modificare lo stato del lancio dell'agente

Un operatore può aggiornare lo stato di lancio di un agente e includere un commento che spieghi il motivo della modifica dello stato.

Nota: i requisiti per il campo comment variano in base all'azione:

(Facoltativo): avvia le approvazioni.
Obbligatorio: rifiuti, sospensioni e richieste di annullamento della pubblicazione.

Questo commento viene inviato allo sviluppatore in un'email, visibile nella cronologia degli agenti delle console Amministrazione e Business Communications, ed è incluso nelle notifiche AgentLaunchEvent webhook. Questa pubblicazione si applica a tutti gli aggiornamenti di stato.

Lo stato deve essere modificato come segue:

Da LAUNCH_STATE_PENDING a LAUNCH_STATE_LAUNCHED o LAUNCH_STATE_REJECTED
Da LAUNCH_STATE_LAUNCHED a LAUNCH_STATE_SUSPENDED
Da LAUNCH_STATE_SUSPENDED a LAUNCH_STATE_LAUNCHED o 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',
        }
      }
    }
  }"

Questo codice restituisce le informazioni di lancio aggiornate con lo stato di lancio modificato:

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

Nascondere o mostrare gli agenti

Per mantenere uno spazio di lavoro pulito e organizzato, puoi nascondere gli agenti che non sono più in uso sulla tua rete. Se nascondi un agente, questo viene rimosso dai risultati di rilevamento dell'API predefinita.

L'occultamento è una modifica della sola visibilità. Influisce solo sulla visualizzazione per il tuo operatore specifico e non sullo stato dell'agente per il partner o altri operatori. Puoi rendere di nuovo visibile un agente in qualsiasi momento per ripristinarne la visibilità e continuare la gestione.

Per assicurarsi che gli agenti attivi non vengano rimossi accidentalmente dalla visualizzazione, si applicano le seguenti regole:

Idoneità: puoi nascondere solo gli agenti in stato non attivo sulla tua rete: Sospeso o Rifiutato.
Limitazioni: non puoi nascondere un agente se il suo stato di lancio sulla tua rete è Avviato o In attesa. Se tenti di nascondere un agente di questo tipo, la richiesta verrà rifiutata con un errore FAILED_PRECONDITION.

Aggiorna stato nascondi

Per nascondere o mostrare l'avvio di un agente per il tuo operatore, utilizza il metodo setAgentLaunchVisibility sulla risorsa di avvio. Per nasconderlo, imposta il valore booleano isHidden su true e per mostrarlo di nuovo impostalo su false.

Metodo: 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
      }
    }
  }
}

Elenca gli agenti con i filtri

Per impostazione predefinita, il metodo list esclude gli agenti nascosti dal tuo operatore. Per includerli nei risultati, utilizza il parametro includeHidden.

Eliminare un agente

Per motivi di sicurezza, gli agenti RBM non possono più essere eliminati. Per ricevere assistenza, contatta il team di assistenza RCS for Business.

Gestisci gli agenti con l'API RBM Operations Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Elenca tutti gli agenti inviati a un operatore

Node.js

cURL

Recuperare le informazioni di verifica dell'agente

Node.js

cURL

Visualizzare lo stato del lancio dell'agente e il questionario

Node.js

cURL

Cercare la definizione di un agente

Node.js

cURL

Modificare lo stato del lancio dell'agente

Node.js

cURL

Nascondere o mostrare gli agenti

Aggiorna stato nascondi

Elenca gli agenti con i filtri

Eliminare un agente

Gestisci gli agenti con l'API RBM Operations