The core RBM workflow for carriers includes reviewing information about new
agents and approving or denying them permission to launch on the carrier's
network and message their subscribers.

Code snippets on this page are taken from our
[Javascript](https://github.com/rcs-business-messaging/rbm-api-examples/tree/master/nodejs/rbm-ops-api)
and [Curl](https://github.com/rcs-business-messaging/rbm-api-examples/tree/master/curl/rbm-ops-api)
samples.

## List all agents submitted to a carrier

The carrier can obtain a list of all the agents that developers have submitted
for launch on the carrier's network.

### Node.js

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

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

The brand is set to `-` since it's not required when retrieving a list of all
agents.

This code returns a list of all the agents submitted for launch at the carrier:

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

Results can be retrieved one page at a time. See the
[API reference](https://developers.google.com/business-communications/rcs-business-messaging/reference/business-communications/rest/v1/brands.agents/list)
for details.

## Get agent verification info

The carrier can obtain the status of an agent's brand verification. For more
details, see
[`brands.agents.getVerification`](https://developers.google.com/business-communications/rcs-business-messaging/reference/business-communications/rest/v1/brands.agents/getVerification).

### Node.js

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

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

The caller does not necessarily need the full agent name, including brand name.
Only the agent ID (before `@rbm.goog`) is required, with the brand name set to
`-`.

This code returns the verification status and partner info:

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

## Get agent launch status and questionnaire

The carrier can obtain the current launch status of an agent and the developer
launch questionnaire.

### Node.js

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

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

The caller does not necessarily need the full agent name, including brand name.
Only the agent ID (before `@rbm.goog`) is required, with the brand name set to
`-`.

This code returns the launch information:

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

## Look up an agent definition

The carrier can retrieve an agent's information using its unique identifier
(`name`).

### Node.js

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

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

The caller doesn't necessarily need the full agent name, including brand name.
Only the agent ID (before `@rbm.goog`) is required, with the brand name set to
`-`.

This code returns the agent information:

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

## Change agent launch status

A carrier can update an agent's launch status and include a comment explaining
the reason for the status change.

> [!IMPORTANT]
> **Note** : Requirements for the `comment` field vary by action:
>
> - **Optional**: Launch approvals.
> - **Required**: Rejections, suspensions, and unlaunch requests.
>
> **Audit trail** : You can optionally include the `acting_party`
> query parameter to specify the email address or identifier of the person
> performing the action. This ensures that the **User ID** field in history
> logs correctly identifies the individual rather than defaulting to "API Call".
>
> This comment is sent to the developer in an email, visible in
> **Agent history** of both the [Administration](https://business-communications.cloud.google.com/console/partner-console/carrier-agents) and
> [RCS for Business](https://business-communications.cloud.google.com/console)
> consoles, and included in
> [`AgentLaunchEvent`](https://developers.google.com/business-communications/rcs-business-messaging/reference/rest/v1/AgentLaunchEvent#LaunchState)
> [webhook](https://developers.google.com/business-communications/rcs-business-messaging/guides/integrate/webhooks)
> notifications. This delivery applies to all status updates.

The status should be changed as follows:

- `LAUNCH_STATE_PENDING` to `LAUNCH_STATE_LAUNCHED` or `LAUNCH_STATE_REJECTED`
- `LAUNCH_STATE_LAUNCHED` to `LAUNCH_STATE_SUSPENDED`
- `LAUNCH_STATE_SUSPENDED` to `LAUNCH_STATE_LAUNCHED` or `LAUNCH_STATE_UNLAUNCHED`

The caller doesn't necessarily need the full agent name, including brand name.
Only the agent ID (before `@rbm.goog`) is required, with the brand name set to
`-`.

### Node.js

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

```console
curl -v -X PATCH "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/launch?acting_party=user@example.com" \
  -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',
        }
      }
    }
  }"
```

This code returns the updated launch information with the launch status changed:

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

## Hide or unhide agents

To maintain a clean and organized workspace, you can hide agents that are no
longer in use on your network. Hiding an agent removes it from default API
discovery results.

Hiding is a visibility-only change. It only affects the view for your specific
carrier and does not impact the agent's status for the partner or other
carriers. You can unhide an agent at any time to restore its visibility and
continue management.

> [!NOTE]
> **Note:** To hide your agent using the [Administration Console](https://developers.google.com/business-communications/rcs-business-messaging/carriers/console/manage), refer to [Hide or unhide an agent](https://developers.google.com/business-communications/rcs-business-messaging/carriers/console/manage#hide-agent).

To make sure that active agents are not accidentally removed from view, the
following rules apply:

- **Eligibility** : You can only hide agents that are in an inactive state on your network: **Suspended** or **Rejected**.
- **Restrictions** : You cannot hide an agent if its launch status on your network is **Launched** or **Pending** . If you attempt to hide such an agent, the request will be rejected with a `FAILED_PRECONDITION` error.

### Update hide status

To hide or unhide an agent launch for your carrier, use the
`setAgentLaunchVisibility` method on the launch resource. To hide, set the
`isHidden` boolean to `true` and to unhide set it to `false`.

Method:
`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
          }
        }
      }
    }

### List agents with filters

By default, the `list` method excludes agents hidden by your carrier. To include
them in your results, use the `includeHidden` parameter.

## Delete an agent

For security reasons, RBM agents can no longer be deleted. For assistance,
[contact the RCS for Business support team](https://developers.google.com/business-communications/rcs-business-messaging/support/overview/contact).