Create your first agent

Prerequisites

Create your agent

This guide walks you through how to create an agent using a sample application. The sample provides a quick way to explore the functionality of an agent and it can serve as a starting point for your agent development. If you want to modify an existing application to include an agent, the sample offers a good model for your application logic.

In this quickstart, you'll do the following:

  • Register as a partner
  • Create a brand and an agent
  • Optionally, explore features in a conversation with the Business Messages Helper Bot
  • Set up your agent to send and receive messages

To create an agent without using the sample, see Create your agent.

Register as a partner

  1. Open the Business Communications Developer Console.
  2. Under Business Messages, click Create partner account.

  3. Enter your partner information:

    Field Value
    Your name Your full name
    Partner name Your organization's name
    Partner website Your organization's website
    Region The region you want to host the Business Messages service

  4. Review and accept the Business Messages Terms of Service.

  5. Click Create.

You are now registered as a Business Messages partner. A new Google Cloud project has been created for you with the Business Messages and Business Communications APIs enabled. You don’t have access to this project and it won’t interfere with any of your existing Google Cloud projects.

You now have access to the Business Messages and Business Communications APIs.

Create a service account

  1. On the Business Communications Developer Console home page, click Partner account settings.
  2. In the left navigation, click Service account.

  3. Click Create key, then click Create.

    Your browser downloads the service account key. Store it in a secure location. You'll need this key later to deploy a web application and access the Business Messages and Business Communications APIs in the future.

Create a brand and an agent

An agent is a conversational representation of a brand—the conversational entity that users interact with. You create a brand to represent the business and create an agent so that consumers can conversationally connect with it.

  1. Open the Business Communications Developer Console and sign in with your Business Messages Google account.
  2. Click Create agent.
  3. For Agent type, select Business Messages.
  4. Enter values for Brand name and Agent name.
  5. Do one of the following:
    • To experience a conversation with your agent where you can explore the available features, select Enable Business Messages Helper Bot.
    • To customize your agent and prepare it for message handling, deselect Enable the Business Messages Helper Bot.
  6. Click Create agent.

If you enabled the Business Messages Helper Bot, you can start a conversation immediately. Otherwise, proceed to set up your agent for message handling.

Explore features with the Business Messages Helper Bot

The Business Messages Helper Bot lets you quickly start a conversation with your agent so you can experience what the platform has to offer. Enabling the Helper Bot is optional but highly recommended when creating your first agent.

The Helper Bot allows you to

  • Explore rich features
  • Learn how to implement features
  • Find resources for agent setup

When the Helper Bot is enabled, it sends and receives messages for your agent; no webhook is required. You need to disable the Helper Bot before you can set a webhook or enable Dialogflow to handle user messages.

Start a conversation with the Helper Bot

Once you enable the Business Messages Helper Bot, you can start a conversation. A dialog opens immediately after agent creation to help you get started.

To interact with the Helper Bot, take the following steps from this dialog:

  1. Access the agent's test URLs. There are a few ways you can do this:

    • Click the Android button or iOS button. Then scan the QR code with the corresponding mobile device and click Launch. Alternatively, click Copy Android URL or Copy iOS URL to copy the agent's test URL.
    • Click Send to send the URLs to your email address.

  2. Open the URL in your mobile device. (iOS devices require the Google Maps app.)

Disable the Helper Bot

Before you can customize your agent and prepare it for launch, you need to disable the Business Messages Helper Bot.

To disable the Helper Bot,

  1. Open the Business Communications Developer Console.
  2. Select your agent.
  3. In the left navigation, click Integrations.
  4. For Helper Bot, click Disable.

When the Helper Bot is disabled, it no longer sends and receives messages for your agent. Now you can set up your agent to handle the messaging flow.

Set up your agent for message handling

In this guide, you'll deploy an Echo Bot to Google Cloud Platform (GCP) with a webhook designed to process user messages.

The Echo Bot is a sample application that echoes messages back to the user. It allows you to experiment with rich features, such as suggested actions and rich cards, in a conversation with your agent. You can also use the Echo Bot as a starting point for developing your agent.

You'll complete the following steps:

  • Deploy the Echo Bot sample to GCP
  • Configure the webhook URL for your Business Messages partner account
  • Provide basic information about your agent

At the end of this guide, your agent will be ready to send and receive messages.

Deploy the web application to GCP

Business Messages forwards messages from users to a webhook in your infrastructure. In this guide, you'll deploy the Echo Bot sample source code to a pre-configured webhook. If you already have web infrastructure to leverage for receiving messages, you can create a new webhook on that web service, but you'll need to configure the logic yourself. See Set your partner-level webhook for details.

Create a Cloud environment

You need a cloud environment to deploy the Echo Bot sample.

To create a GCP project as a cloud environment, follow these steps:

  1. Open the Google Cloud Console Project Selector.

    If you have never created a Google Cloud project, you’ll need to Accept the Terms and Services.

  2. Click Create Project.

  3. Enter a name and location for your new project

    • Your project ID is automatically generated and appears below your project name.
    • In the Location field, click Browse to display potential locations for your project. If you can’t find your Google Workspace organization, then you aren’t signed in to a Google Workspace account. You can create a project without an organization, but some features are limited. See Benefits of the organization resource for more information.

  4. Click Create.

  5. Click Menu.

  6. Click Billing.

  7. Click Link a Billing Account.

  8. Create a new billing account or add an existing billing account to the project. See Google Cloud Free Program Features to understand payment options.

Deploy the Echo Bot sample

  1. Install the gcloud CLI. You’ll use this to deploy the sample code to Google Cloud.

  2. Download and extract the Echo Bot sample (Node.js, Java, Python).

  3. Copy the JSON credentials file you downloaded in Create a service account into the sample's resources folder and rename the credentials to "bm-agent-service-account-credentials.json". The path to this credentials file depends on the sample you downloaded.

    Node.js

    ./bm-nodejs-echo-bot/full_sample/resources/bm-agent-service-account-credentials.json

    Java

    ./bm-java-echo-bot/full_sample/src/main/resources/bm-agent-service-account-credentials.json

    Python

    ./bm-python-echo-bot/full_sample/resources/bm-agent-service-account-credentials.json

  4. In a terminal, navigate to the sample's full_sample directory.

  5. Run the following commands in a terminal to deploy the sample:

    Node.js

    gcloud config set project PROJECT_ID
gcloud app create
gcloud app deploy

    PROJECT_ID is the project ID for the project you created in Create a Cloud environment. The Project ID is listed on the project dashboard in Google Cloud.

    Java

    gcloud config set project PROJECT_ID
gcloud app create
mvn appengine:deploy

    PROJECT_ID is the project ID for the project you created in Create a Cloud environment. The Project ID is listed on the project dashboard in Google Cloud.

    Python

    gcloud config set project PROJECT_ID
gcloud app create
gcloud app deploy

    PROJECT_ID is the project ID for the project you created in Create a Cloud environment. The Project ID is listed on the project dashboard in Google Cloud.

  6. Note the URL of the deployed application in the output of the last command. This is the base of your webhook URL:

    Deployed service [default] to [https://PROJECT_ID.appspot.com]

Set your webhook

Now that the Echo Bot is deployed, you need to specify a webhook URL (that you operate) to start receiving messages.

  1. Open the Account settings in the Business Communications Developer Console.
  2. Make sure the correct partner account is selected.
  3. For Business Messages webhook URL, click Configure.

  4. For Webhook endpoint URL, enter your application's URL + "/callback".

    Your endpoint will follow the format: "https://PROJECT_ID.appspot.com/callback".

    This endpoint is predefined in the application logic of the sample you deployed to GCP.

  5. In the Developer Console, click Verify.

    When Business Messages verifies your webhook, the dialog closes.

To configure your webhook with the Business Communications API, see Example: Update webhook URL.

You can use the Business Messages test framework to test whether your webhook responds successfully to Business Messages payloads.

Enter agent information

Provide some basic information to complete your agent setup.

  1. Open the Business Communications Developer Console.
  2. In the left navigation, click Agent information.

  3. Update the values however you like, or use the following suggestions:

    Field Value
    Welcome message Welcome to the Echo Bot conversation!
    Privacy policy https://policies.google.com/privacy

  4. Click Save.

Start the conversation

To interact with the Echo Bot, follow these steps:

  1. Open the Business Communications Developer Console.
  2. In the left navigation, click Agent information.
  3. Under Agent test URLs, click the Android button or iOS button.

  4. Scan the QR code with the corresponding mobile device, or click Copy Android URL or Copy iOS URL to copy the agent's test URL.

    You can also click Send to send the URLs to your email address.

  5. Open the URL in your mobile device. (iOS devices require the Google Maps app.)

Your agent's welcome message greets you. At this point, you can interact with the Echo Bot. It echoes the messages you send back to you. Additionally, you can invoke rich features by sending specific strings: “carousel”, “card”, “chips”.

Next steps

Now that you've created your first agent, learn more about Business Messages and what else you can do on the platform.