Updates: Check the release notes for new features and product updates.

Create agents to manage brands

An agent is a conversational representation of a brand (and all the infrastructure that powers the representation) that users interact with on their devices.

As a registered partner you can create Verified SMS agents, which let you use the Verified SMS API and define the branding information displayed in conversations with users. When you store message hashes with Verified SMS, you call the API and associate the message with a particular agent.

For example, to send verified messages on behalf of the brand Growing Tree Bank, you create a Growing Tree Bank agent with Verified SMS. You use your partner credentials to authenticate API calls with Verified SMS and store message hashes as Growing Tree Bank, and the agent displays Growing Tree Bank's branding information in conversations with users.

A verified SMS with branding information

If you manage multiple brands, create an agent for each brand with Verified SMS.

Localization

Verified SMS agents can have sender IDs in multiple countries, but agents' branding information, including agent name and description, isn't localized.

To have localized branding information for your agent, create an agent for each language you send messages in. Localize the agent display name and description, but specify the same non-localized brand name for each agent. If you have unique sender IDs per language, make sure to associate them with the correct localized agents.

By default, Verified SMS contacts a brand to perform branding verification each time you create an agent. If you anticipate creating multiple localized agents and would prefer Google to contact the brand once for bulk branding verification, contact us.

Create an agent

To create an agent, you need to gather and submit information about the brand and how you want the agent to appear to users.

Prerequisites

Before you can create an agent, you need to gather the some information:

  • Brand name
  • Brand website
  • Agent name, as you want it to appear in conversations with users (maximum 100 characters)
  • Agent logo (224x224 px, maximum 30 KB, JPEG or PNG) as a publicly available URL

    In conversations, logos display as 224 px diameter circles. Make sure that your logo displays well as a circle.

  • List of unique, non-shared sender IDs (short, long, and alphanumeric codes) and the ISO 3166 Alpha-2 country codes for the countries that each sender ID operates in

Create the agent

Once you've gathered your information, it's time to create your agent. Replace the highlighted variables with the values you identified in Prerequisites.

  1. Create the brand that the agent represents. If the brand already exists, get the brand's name and skip to the next step.

    In a terminal, run the following command:

    
    # This code creates a brand.
    # Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands/create
    
    # Make sure a service account key file exists at ./service_account_key.json
    
    curl -X POST "https://businesscommunications.googleapis.com/v1/brands" \
    -H "Content-Type: application/json" \
    -H "User-Agent: curl/business-communications" \
    -H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
    -d '{
      "displayName": "My first brand curl"
    }'
    

    Store the name value that the API returns. You'll need it to make updates or create agents.

    To update or look up brands, see brands.

  2. Create the agent. Replace BRAND_ID with the part of the brand's name value that follows "brands/". For example, if name is "brands/12345", the brand ID is "12345". For each sender ID and country code pair, add a new entry under senders.

    In a terminal, run the following command:

    curl -X POST "https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents" \
    -H "Content-Type: application/json" \
    -H "User-Agent: curl/business-communications" \
    -H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
    -d "{
        'displayName': 'AGENT_DISPLAY_NAME',
        'verifiedSmsAgent': {
            'logoUrl': 'LOGO_URL',
            'description': 'AGENT_DESCRIPTION',
            'senders': [
              {
                'senderId': 'SENDER_ID',
                'countryCode': 'COUNTRY_CODE',
              },
              {
                'senderId': 'SENDER_ID',
                'countryCode': 'COUNTRY_CODE',
              },
              {
                'senderId': 'SENDER_ID',
                'countryCode': 'COUNTRY_CODE',
              },
            ],
        },
    }"
    

    For formatting and value options, see brands.agents.

Get agent information

To get information about an agent, such as an agent's sender IDs, you can get the information from the Business Communications API as long as you have the agent's name value.

Get info for a single agent

To get agent information, run the following command. Replace BRAND_ID and AGENT_ID with the unique values from the agent's name.


# This code gets the agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/get

# Replace the __BRAND_ID__ and __AGENT_ID__
# Make sure a service account key file exists at ./service_account_key.json

curl -X GET \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)"

List all agents for a brand

If you don't know the agent's name, you can get information for all agents associated with a brand by omitting the AGENT_ID value from a GET request URL.


# This code lists all agents from a brand.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/list

# Replace the __BRAND_ID__
# Make sure a service account key file exists at ./service_account_key.json

curl -X GET \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)"

Update agent information

To update an agent, you perform a PATCH request with the Business Communications API. When you make the API call, you include the names of the fields you're editing as values for the "updateMask" URL parameter.

For example, if you update the displayName and senders fields, the "updateMask" URL parameter is "updateMask=displayName,verifiedSmsAgent.senders".

After you launch an agent, you can only update the senders field. If you need to update other fields after you launch your agent, contact us.

Update the agent

To update agent information, run the following command. Replace BRAND_ID and AGENT_ID with the unique values from the agent's name, and replace UPDATED_FIELDS with the field names you update.

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID?updateMask=UPDATED_FIELDS" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
    'FIELD_NAME': 'FIELD_VALUE',
}"

For formatting and value options, see brands.agents.patch.

If you don't know an agent's name, see List all agents for a brand.

Example: Update display name

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID?updateMask=displayName" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
    'displayName': 'Growing Tree Bank',
}"

Example: Update sender IDs

If you add, update, or delete any sender ID associated with the agent, you must include the whole sender ID list in the update. If you don't include all valid sender IDs, messages sent from those IDs may not be verified on users' devices.

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/12345/agents/67890?updateMask=verifiedSmsAgent.senders" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json /path/to/service/account/key businesscommunications)" \
-d "{
    'verifiedSmsAgent': {
        'senders': [
          {
            'senderId': '111222',
            'countryCode': 'US',
          },
          {
            'senderId': '111222',
            'countryCode': 'CA',
          },
          {
            'senderId': '+12223334444',
            'countryCode': 'US',
          },
          {
            'senderId': 'VM-PAY',
            'countryCode': 'IN',
          },
        ],
    },
}"

Delete an agent

When you delete an agent, you perform a DELETE request with the Business Communications API. Delete requests fail if you've attempted to verify the agent one or more times. To delete an agent that you've verified or attempted to verify, contact us.

To delete an agent, run the following command. Replace BRAND_ID and AGENT_ID with the unique values from the agent's name.


# This code deletes an agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/delete

# Replace the __BRAND_ID__ and __AGENT_ID__
# Make sure a service account key file exists at ./service_account_key.json

curl -X DELETE "https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)"

For formatting and value options, see brands.agents.delete.

Delete a brand

When you delete a brand, you perform a DELETE request with the Business Communications API. Delete requests fail if you have one or more agents or locations associated with the brand, even if those agents belong to a different product.

To delete a brand, run the following command. Replace BRAND_ID with the unique value from the brand's name.


# This code deletes a brand.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands/delete

# Replace the __BRAND_ID__
# Make sure a service account key file exists at ./service_account_key.json

curl -X DELETE "https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)"

For formatting and value options, see brands.delete.

Next steps

Before you begin storing message hashes with Verified SMS,

Once you've done that, you're ready to send a verified message.