Create your first agent

This guide walks you through creating an agent. 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

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 and 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 obtain this webhook. If you already have web infrastructure to leverage for receiving messages, you can create a new webhook on that web service, similar to the Echo Bot sample. See Receive messages 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,

  1. Open the Google Cloud Console Project Selector.
  2. Click Create Project and enter a name for your new project.
  3. Click Create.

Deploy the Echo Bot sample

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

  2. 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/resources/bm-agent-service-account-credentials.json
    

    Java

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

    Python

    ./bm-python-echo-bot/resources/bm-agent-service-account-credentials.json
    
  3. In a terminal, navigate to the sample's root directory.

  4. 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.

    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.

    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.

  5. 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/".

    For example, it might be something like "https://PROJECT_ID.appspot.com/callback/".

  5. Note your clientToken value. You need it to verify that messages you receive are coming from Google.

  6. Configure your webhook to accept a POST request with the specified clientToken parameter and send a 200 OK response with the plain text value of the secret parameter as the response body.

    For example, if your webhook receives a POST request with the following body content

    {
      "clientToken":"SJENCPGJESMGUFPY",
      "secret":"0123456789"
    }
    

    your webhook should confirm the clientToken value and, if clientToken is correct, return a 200 OK response with 0123456789 as the response body.

  7. 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.

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.