We will be winding down Google Business Messages on July 31, 2024. Read more here.

Launch an agent

Page Summary

Agents can be managed through the Business Communications Developer Console or API.
Before launching an agent, ensure it meets the pre-launch checklist criteria including verification, privacy policy, messaging availability, and greeting.
Infrastructure readiness, such as complete message, event, and survey handling, is required before launch.
Conversation readiness, ensuring live agents or automation are available, is also crucial before launching.
Agents are launched on configured entry points and regions through the Developer Console, becoming available to users within a few hours after approval.

After you verify an agent for a brand that you manage, build out your message-routing capabilities, and determine that your infrastructure is ready to interact with users, it's time to launch.

To make an agent available to users, you launch the agent on various entry points. Entry points control where users can begin conversations with the agent.

You can only launch an agent on entry points that you configured before you verified the agent. To edit allowed entry points after agent verification, contact us. (You must first sign in with a Business Messages Google account. To register for an account, see Register with Business Messages.)

Pre-launch checklist

Before you launch your agent, use the following checklist to catch any issues that might appear during the launch process.

Agent configuration
Agent verification Required. Verification that the agent's information is accurate and that the agent can represent the associated brand. See Verify agents and locations.
Privacy policy Required. A publicly available URL starting with "https://". See Create an agent.
Messaging availability Required. The days and times that human representatives are available to respond to users. If a human interaction type isn't specified for your agent, it can't launch on Google-managed entry points (except for the Google Ads entry point). See Set messaging availability.
Greeting Required. The welcome message and optional conversation starters that guide users through known user journeys. See Begin the conversation.
Offline message Recommended. A message that displays when a user starts a conversation outside of an agent's operating hours. See Begin the conversation.

Infrastructure readiness
Message handling is complete Required. Your webhook and agent infrastructure are ready to receive, send, and track messages.
Event handling is complete Required. Your webhook and agent infrastructure are ready to send and receive events.
Survey handling is complete Required. Your webhook and agent infrastructure are ready to send surveys and receive results.

Conversation readiness
Live agents are available Required. Live agents are ready to respond to user messages as soon as the agent launches.
Automation is complete and available Recommended. Any automation you've developed or integrated with is complete and ready to handle user messages as soon as the agent launches.

Prerequisites

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

A verified agent
The agent's name

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

Note: Agent names and IDs must be URL-encoded. For example, if an agent name or ID includes "/", change "/" to "%2F".
EntryPoint values for the entry points you want to launch your agent on
The regions where you want to launch NON_LOCAL entry points, as CLDR region codes

Note: To launch in all regions specified for your agent, use 001 for the World region code.
Path to your GCP project's service account key on your development machine

Launch an agent

When you launch an agent, Business Messages performs checks for necessary approvals, emails you once the agent is approved for launch, and begins the launch process. Once the launch process begins, the agent is available to users within a few hours.

You should be ready to respond to user messages before you launch an agent.

To launch an agent, run the following command. Replace variables with values identified in Prerequisites.

cURL

# This code requests a launch of a Business Messages agent.
# Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/launch/agents?method=api#launch-agent

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

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__:requestLaunch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "agentLaunch": {
    "businessMessages": {
      "launchDetails": {
        "NON_LOCAL": {
          "entryPoint": "NON_LOCAL",
          "regionCodes": ["US"]
        }
      }
    }
  }
}'create-agent-launch.sh

Node.js

/**
 * This code snippet requests the launch of an agent.
 * Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/launch/agents?method=api#launch-agent
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businesscommunications Node.js
 * Business Communications client library.
 */

/**
 * Edit the values below:
 */
const BRAND_ID = 'EDIT_HERE';
const AGENT_ID = 'EDIT_HERE';
const ENTRY_POINT = 'EDIT_HERE';
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
const bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

async function main() {
  const authClient = await initCredentials();

  const agentName = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID;

  if (authClient) {
    const agentLaunch = {
        agentLaunch: {
          businessMessages: {
            launchDetails: {
              [ENTRY_POINT]: {
                'entryPoint': ENTRY_POINT,
                'regionCodes': ['US', 'CA'],
              }
            }
          },
        }
      };

    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName,
      resource: agentLaunch,
    };

    bcApi.brands.agents.requestLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
 async function initCredentials() {
  // Configure a JWT auth client
  const authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

main();create-agent-launch.js

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import com.google.common.collect.ImmutableMap;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID";

      BusinessCommunications.Brands.Agents.RequestLaunch request
          = builder.build().brands().agents().requestLaunch(agentName, new RequestAgentLaunchRequest()
              .setAgentLaunch(new AgentLaunch()
                    .setBusinessMessages(new BusinessMessagesLaunch()
                        .setLaunchDetails(
                            ImmutableMap.of("ENTRY_POINT",
                                new BusinessMessagesEntryPointLaunch()
                                    .setEntryPoint("ENTRY_POINT")
                                    .setRegionCodes(Arrays.asList("REGION_CODE")))))));

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

"""This code requests a launch of a Business Messages agent.

Read more: https://developers.google.com/business-communications/business-messages/guides/how-to/launch/agents?method=api#launch-agent

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import BusinesscommunicationsV1
from businesscommunications.businesscommunications_v1_messages import (
    AgentLaunch,
    BusinesscommunicationsBrandsAgentsRequestLaunchRequest,
    BusinessMessagesEntryPointLaunch,
    BusinessMessagesLaunch,
    RequestAgentLaunchRequest
)

# Edit the values below:
BRAND_ID = 'EDIT_HERE'
AGENT_ID = 'EDIT_HERE'
SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = './service_account_key.json'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID

launch_request = agents_service.RequestLaunch(
        BusinesscommunicationsBrandsAgentsRequestLaunchRequest(
            name=agent_name,
            requestAgentLaunchRequest=RequestAgentLaunchRequest(
                agentLaunch=AgentLaunch(
                    businessMessages=BusinessMessagesLaunch(
                        launchDetails=BusinessMessagesLaunch.LaunchDetailsValue(
                            additionalProperties=[BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='NON_LOCAL',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.NON_LOCAL,
                                        regionCodes=['US']
                                        )
                                )]
                            )
                    )
                )
            )
        )
    )

print(launch_request)create-agent-launch.py

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

Examples: Launch based on entry point group

All entry points

cURL

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/12345/agents/67890:requestLaunch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json /path/to/service/account/key.json businesscommunications)" \
-d "{
  'agentLaunch': {
    'businessMessages': {
      'launchDetails': {
        'NON_LOCAL': {
          'entryPoint': 'NON_LOCAL',
          'regionCodes': ['001'],
        },
        'LOCATION': {
          'entryPoint': 'LOCATION',
        },
      },
    },
  },
}"

Node.js

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
let bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require('PATH_TO_SERVICE_ACCOUNT_KEY');

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
async function initCredentials() {
  // Configure a JWT auth client
  let authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

async function main() {
  let authClient = await initCredentials();

  let agentName = 'brands/BRAND_ID/agents/AGENT_ID';

  if (authClient) {
    const agentLaunch = {
        agentLaunch: {
          businessMessages: {
            launchDetails: {
              'NON_LOCAL': {
                'entryPoint': 'NON_LOCAL',
                'regionCodes': ['001'],
              },
              'LOCATION': {
                'entryPoint': 'LOCATION',
              }
            }
          },
        }
      };

    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName,
      resource: agentLaunch,
    };

    bcApi.brands.agents.requestLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

main();

This code is based on the Node.js Business Communications client library.

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import com.google.common.collect.ImmutableMap;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID";

      BusinessCommunications.Brands.Agents.RequestLaunch request
          = builder.build().brands().agents().requestLaunch(agentName, new RequestAgentLaunchRequest()
              .setAgentLaunch(new AgentLaunch()
                    .setBusinessMessages(new BusinessMessagesLaunch()
                        .setLaunchDetails(
                            ImmutableMap.of("NON_LOCAL",
                                new BusinessMessagesEntryPointLaunch()
                                    .setEntryPoint("NON_LOCAL")
                                    .setRegionCodes(Arrays.asList("001")), "LOCATION",
                                new BusinessMessagesEntryPointLaunch()
                                    .setEntryPoint("LOCATION"))))));

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import (
    BusinesscommunicationsV1
)
from businesscommunications.businesscommunications_v1_messages import (
    AgentLaunch,
    BusinesscommunicationsBrandsAgentsRequestLaunchRequest,
    BusinessMessagesEntryPointLaunch,
    BusinessMessagesLaunch,
    RequestAgentLaunchRequest
)

SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = 'PATH_TO_SERVICE_ACCOUNT_KEY'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/BRAND_ID/agents/AGENT_ID'

launch_request = agents_service.RequestLaunch(
        BusinesscommunicationsBrandsAgentsRequestLaunchRequest(
            name=agent_name,
            requestAgentLaunchRequest=RequestAgentLaunchRequest(
                agentLaunch=AgentLaunch(
                    businessMessages=BusinessMessagesLaunch(
                        launchDetails=BusinessMessagesLaunch.LaunchDetailsValue(
                            additionalProperties=[BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='NON_LOCAL',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.NON_LOCAL,
                                        regionCodes=['001']
                                        )
                                ),
                                BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='LOCATION',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.LOCATION
                                        )
                                )]
                            )
                    )
                )
            )
        )
    )

print(launch_request)

This code is based on the Python Business Communications client library.

NON_LOCAL only

cURL

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/12345/agents/67890:requestLaunch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json /path/to/service/account/key.json businesscommunications)" \
-d "{
  'agentLaunch': {
    'businessMessages': {
      'launchDetails': {
        'NON_LOCAL': {
          'entryPoint': 'NON_LOCAL',
          'regionCodes': ['001'],
        },
      },
    },
  },
}"

Node.js

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
let bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require('PATH_TO_SERVICE_ACCOUNT_KEY');

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
async function initCredentials() {
  // Configure a JWT auth client
  let authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

async function main() {
  let authClient = await initCredentials();

  let agentName = 'brands/BRAND_ID/agents/AGENT_ID';

  if (authClient) {
    const agentLaunch = {
        agentLaunch: {
          businessMessages: {
            launchDetails: {
              'NON_LOCAL': {
                'entryPoint': 'NON_LOCAL',
                'regionCodes': ['001'],
              }
            }
          },
        }
      };

    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName,
      resource: agentLaunch,
    };

    bcApi.brands.agents.requestLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

main();

This code is based on the Node.js Business Communications client library.

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import com.google.common.collect.ImmutableMap;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID";

      BusinessCommunications.Brands.Agents.RequestLaunch request
          = builder.build().brands().agents().requestLaunch(agentName, new RequestAgentLaunchRequest()
              .setAgentLaunch(new AgentLaunch()
                    .setBusinessMessages(new BusinessMessagesLaunch()
                        .setLaunchDetails(
                            ImmutableMap.of("NON_LOCAL",
                                new BusinessMessagesEntryPointLaunch()
                                    .setEntryPoint("NON_LOCAL")
                                    .setRegionCodes(Arrays.asList("001")))))));

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import (
    BusinesscommunicationsV1
)
from businesscommunications.businesscommunications_v1_messages import (
    AgentLaunch,
    BusinesscommunicationsBrandsAgentsRequestLaunchRequest,
    BusinessMessagesEntryPointLaunch,
    BusinessMessagesLaunch,
    RequestAgentLaunchRequest
)

SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = 'PATH_TO_SERVICE_ACCOUNT_KEY'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/BRAND_ID/agents/AGENT_ID'

launch_request = agents_service.RequestLaunch(
        BusinesscommunicationsBrandsAgentsRequestLaunchRequest(
            name=agent_name,
            requestAgentLaunchRequest=RequestAgentLaunchRequest(
                agentLaunch=AgentLaunch(
                    businessMessages=BusinessMessagesLaunch(
                        launchDetails=BusinessMessagesLaunch.LaunchDetailsValue(
                            additionalProperties=[BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='NON_LOCAL',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.NON_LOCAL,
                                        regionCodes=['001']
                                        )
                                )]
                            )
                    )
                )
            )
        )
    )

print(launch_request)

This code is based on the Python Business Communications client library.

LOCATION only

cURL

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/12345/agents/67890:requestLaunch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json /path/to/service/account/key.json businesscommunications)" \
-d "{
  'agentLaunch': {
    'businessMessages': {
      'launchDetails': {
        'LOCATION': {
          'entryPoint': 'LOCATION',
        },
      },
    },
  },
}"

Node.js

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
let bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require('PATH_TO_SERVICE_ACCOUNT_KEY');

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
async function initCredentials() {
  // Configure a JWT auth client
  let authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

async function main() {
  let authClient = await initCredentials();

  let agentName = 'brands/BRAND_ID/agents/AGENT_ID';

  if (authClient) {
    const agentLaunch = {
        agentLaunch: {
          businessMessages: {
            launchDetails: {
              'LOCATION': {
                'entryPoint': 'LOCATION'
              }
            }
          },
        }
      };

    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName,
      resource: agentLaunch,
    };

    bcApi.brands.agents.requestLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

main();

This code is based on the Node.js Business Communications client library.

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import com.google.common.collect.ImmutableMap;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID";

      BusinessCommunications.Brands.Agents.RequestLaunch request
          = builder.build().brands().agents().requestLaunch(agentName, new RequestAgentLaunchRequest()
              .setAgentLaunch(new AgentLaunch()
                    .setBusinessMessages(new BusinessMessagesLaunch()
                        .setLaunchDetails(
                            ImmutableMap.of("LOCATION",
                                new BusinessMessagesEntryPointLaunch()
                                    .setEntryPoint("LOCATION"))))));

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import (
    BusinesscommunicationsV1
)
from businesscommunications.businesscommunications_v1_messages import (
    AgentLaunch,
    BusinesscommunicationsBrandsAgentsRequestLaunchRequest,
    BusinessMessagesEntryPointLaunch,
    BusinessMessagesLaunch,
    RequestAgentLaunchRequest
)

SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = 'PATH_TO_SERVICE_ACCOUNT_KEY'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/BRAND_ID/agents/AGENT_ID'

launch_request = agents_service.RequestLaunch(
        BusinesscommunicationsBrandsAgentsRequestLaunchRequest(
            name=agent_name,
            requestAgentLaunchRequest=RequestAgentLaunchRequest(
                agentLaunch=AgentLaunch(
                    businessMessages=BusinessMessagesLaunch(
                        launchDetails=BusinessMessagesLaunch.LaunchDetailsValue(
                            additionalProperties=[BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='LOCATION',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.LOCATION
                                        )
                                )]
                            )
                    )
                )
            )
        )
    )

print(launch_request)

This code is based on the Python Business Communications client library.

Get an agent's launch state

After you make an agent launch request, you can check the agent's launch state.

To get an agent's launch state, run the following command. Replace variables with values identified in Prerequisites.

cURL

# This code gets the agent launch state.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.locations/getLaunch

# 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__/launch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)"get-agent-launch-state.sh

Node.js

/**
 * This code snippet gets an agent launch state.
 * Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.locations/getLaunch
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businesscommunications Node.js
 * Business Communications client library.
 */

/**
 * Edit the values below:
 */
const BRAND_ID = 'EDIT_HERE';
const AGENT_ID = 'EDIT_HERE';
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
const bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

async function main() {
  const authClient = await initCredentials();

  const agentName = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID;

  if (authClient) {
    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName + '/launch',
    };

    bcApi.brands.agents.getLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
 async function initCredentials() {
  // Configure a JWT auth client
  const authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

main();get-agent-launch-state.js

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID/launch";

      BusinessCommunications.Brands.Agents.GetLaunch request
          = builder.build().brands().agents().getLaunch(agentName);

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

"""This code gets the agent launch state.

Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.locations/getLaunch

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import BusinesscommunicationsV1
from businesscommunications.businesscommunications_v1_messages import (
    BusinesscommunicationsBrandsAgentsGetLaunchRequest
)

# Edit the values below:
BRAND_ID = 'EDIT_HERE'
AGENT_ID = 'EDIT_HERE'
SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = './service_account_key.json'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID + '/launch'

launch_state = agents_service.GetLaunch(
        BusinesscommunicationsBrandsAgentsGetLaunchRequest(
            name=agent_name
        )
    )

print(launch_state)get-agent-launch-state.py

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

Unlaunch an agent

If you need to cancel an agent launch or unlaunch a live agent, you can mark an agent entry point as unlaunched. If the agent was in a pending launch state, this cancels the agent launch for that entry point. If the agent was launched, this removes the agent from the specified entry points and regions.

When you unlaunch an agent, conversations persist on user devices, but users can't send messages to the agent.

To unlaunch all regions specified for your agent, use 001 for the World region code. Otherwise, only specify codes for the regions you want to unlaunch.

To unlaunch an agent, run the following command. Replace variables with values identified in Prerequisites.

cURL

# This code updates the launch state of a Business Messages agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/updateLaunch

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

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__/launch" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "businessMessages": {
    "launchDetails": {
      "__ENTRY_POINT__": {
        "entryPoint": "__ENTRY_POINT__",
        "regionCodes": ["US", "CA"],
        "launchState": "LAUNCH_STATE_UNLAUNCHED"
      }
    }
  }
}'update-agent-launch-state.sh

Node.js

/**
 * This code snippet updates the launch state of an agent.
 * Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/updateLaunch
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businesscommunications Node.js
 * Business Communications client library.
 */

/**
 * Edit the values below:
 */
const BRAND_ID = 'EDIT_HERE';
const AGENT_ID = 'EDIT_HERE';
const ENTRYPOINT = 'NON_LOCAL';
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
const bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

async function main() {
  const authClient = await initCredentials();

  const agentName = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID;

  if (authClient) {
    const agentLaunchUpdate = {
        businessMessages: {
          launchDetails: {
            [ENTRYPOINT]: {
              'entryPoint': ENTRYPOINT,
              'regionCodes': ['US', 'CA'],
              'launchState': 'LAUNCH_STATE_UNLAUNCHED',
            }
          }
        },
      };

    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName + '/launch',
      resource: agentLaunchUpdate
    };

    bcApi.brands.agents.updateLaunch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
 async function initCredentials() {
  // Configure a JWT auth client
  const authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

main();update-agent-launch-state.js

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.Agent;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID/launch";

      BusinessCommunications.Brands.Agents.UpdateLaunch request
          = builder.build().brands().agents().updateLaunch(agentName,
              new AgentLaunch().setBusinessMessages(
                  new BusinessMessagesLaunch().setLaunchDetails(
                      ImmutableMap.of("ENTRY_POINT",
                          new BusinessMessagesEntryPointLaunch()
                              .setEntryPoint("ENTRY_POINT")
                              .setRegionCodes(Arrays.asList("REGION_CODE"))
                              .setLaunchState("LAUNCH_STATE_UNLAUNCHED")))));

      System.out.println(request.execute().toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

This code is based on the Java Business Communications client library.

Python

"""This code updates the launch state of a Business Messages agent.

Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/updateLaunch

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import BusinesscommunicationsV1
from businesscommunications.businesscommunications_v1_messages import (
    AgentLaunch,
    BusinesscommunicationsBrandsAgentsUpdateLaunchRequest,
    BusinessMessagesEntryPointLaunch,
    BusinessMessagesLaunch,
    RequestAgentLaunchRequest
)

# Edit the values below:
BRAND_ID = 'EDIT_HERE'
AGENT_ID = 'EDIT_HERE'
SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = './service_account_key.json'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID + '/launch'

update_request = agents_service.UpdateLaunch(
        BusinesscommunicationsBrandsAgentsUpdateLaunchRequest(
            name=agent_name,
            agentLaunch=AgentLaunch(
                    businessMessages=BusinessMessagesLaunch(
                        launchDetails=BusinessMessagesLaunch.LaunchDetailsValue(
                            additionalProperties=[BusinessMessagesLaunch.LaunchDetailsValue.AdditionalProperty(
                                    key='NON_LOCAL',
                                    value=BusinessMessagesEntryPointLaunch(
                                        entryPoint=BusinessMessagesEntryPointLaunch.EntryPointValueValuesEnum.NON_LOCAL,
                                        regionCodes=['US'],
                                        launchState=BusinessMessagesEntryPointLaunch.LaunchStateValueValuesEnum.LAUNCH_STATE_UNLAUNCHED,
                                        )
                                )]
                            )
                    )
                )
        )
    )

print(update_request)update-agent-launch-state.py

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

Next steps

Now that your agent is launched, users can start conversations on the agent's configured entry points. Identify and review the metrics you can use to measure your agent's success.

To enable location-specific entry points, launch the locations associated with your agent.

Launch an agent Stay organized with collections Save and categorize content based on your preferences.

Page Summary

Pre-launch checklist

Prerequisites

Launch an agent

cURL

Node.js

Java

Python

Examples: Launch based on entry point group

All entry points

cURL

Node.js

Java

Python

NON_LOCAL only

cURL

Node.js

Java

Python

LOCATION only

cURL

Node.js

Java

Python

Get an agent's launch state

cURL

Node.js

Java

Python

Unlaunch an agent

cURL

Node.js

Java

Python

Next steps

Launch an agent