Gmail - Botpress

Open in Hubv The Gmail integration allows your bot to chat with users via your Gmail address.

Once you’ve successfully configured the Gmail integration, the email address you provided will begin responding to all incoming emails as your bot. Please be aware of this behaviour before configuring the integration.

Setup

Basic configuration
Manual configuration

You will need:

A published bot
A Google account

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the Gmail integration, then select Install Integration.

In the Configuration menu, select Authorize Gmail.

Follow the instructions to connect Botpress to your Google account.

When using basic configuration, a Botpress-managed Gmail application will be used to connect to your Gmail account. However, actions taken by the bot will be attributed to the user who authorized the connection rather than the application.For this reason, we don’t recommend using personal Gmail accounts for this integration. You should set up a service account and use that account to authorize the connection.

For more advanced use cases, you can manually configure the integration.

You will need:

Step 1. Create a Google Cloud Platform project

Select Select a project dropdown in the top navigation. Then, select New Project.

Follow the on-screen instructions to create the new project.

Step 2. Enable the Gmail API

In Google Cloud Console, navigate to the APIs & Services section.

Select Library from the left sidebar.

Search for Gmail API and select the result.

Select Enable to enable the Gmail API for your project.

In Google Cloud Console, navigate to the APIs & Services section.

Select OAuth consent screen in the left sidebar.

Select Get Started and fill out the App Information section. Then, select Next.

Under Audience, select External.

Fill in the other required sections, then select Create.

Navigate to the Data Access tab, then select Add or remove scopes.

Under Manually add scopes, enter the following:

https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://mail.google.com/
https://www.googleapis.com/auth/gmail.send

Select Add to table, then Update.

Select Save at the bottom of the screen.

Navigate to the Audience tab. Under Test users, select + Add users.

Add an email address for testing the app, then select Save.

Step 4. Create OAuth credentials

In Google Cloud Console, navigate to the APIs & Services section.

Select Credentials in the left sidebar.

Select Create credentials, then OAuth client ID.

Select Web application as the application type.

Enter a name for the OAuth client ID.

Under Authorized redirect URIs, enter https://botpress.com.

Select Add URI, then Create.

Copy the Client ID and Client secret for use in the next steps.

The client ID is the string that ends with .apps.googleusercontent.com.

Step 5. Create a service account

In Google Cloud Console, navigate to the IAM & Admin section.

Select Service accounts in the left sidebar.

Select Create service account.

Enter a name for the service account. Then, select Done.

You don’t need to grant any roles to the service account, as it will only be used to sign webhook events.

Copy the service account email address for use in the next steps.

The service account email address is the string that ends with .gserviceaccount.com.

Step 6. Create a Pub/Sub topic

In Google Cloud Console, search for and navigate to the Pub/Sub section.

Select Topics in the left sidebar.

Select Create topic.

Enter a name for the topic in the Topic ID field.

Uncheck the Add default subscription checkbox. Leave the other options unchanged.

Select Create to create the topic.

Copy the Topic name for use in the next steps.

The topic name is the string that starts with projects/.

Step 7. Grant publish rights on the Pub/Sub topic

In Google Cloud Console, search for and navigate to the Pub/Sub section.

Select Topics in the left sidebar.

From the topic list, find the topic you created earlier. Then, select the triple-dot ⋮ button on the right.

Select View permissions from the dropdown menu.

Select Add principal.

Under Add principals, enter [email protected].

This service account is managed by Google and is used to push events to Pub/Sub.

Under Assign roles, select Pub/Sub Publisher.

Select Save to grant publish rights to the service account.

Step 8. Generate a shared secret

Generate an alphanumeric string to use as a shared secret for signing Pub/Sub push events. We recommend using a string with at least 32 characters.

You can use an online password generator to create a secure string.

Copy this string for use in the next steps.

Step 9. Create a Pub/Sub subscription

In Google Cloud Console, search for and navigate to the Pub/Sub section.

Select Subscriptions in the left sidebar.

Select Create subscription.

Enter a name for the subscription in the Subscription ID field.

Select the topic you created earlier from the topic dropdown.

Under Delivery type, select Push.

Enter your integration’s Botpress-provided webhook URL in the Endpoint URL field. To this URL, add ?shared_secret=, followed by the shared secret you generated earlier.

For example, if:

Your integration’s webhook URL is: https://webhook.botpress.cloud/57fcfb04-51fd-4381-909a-10e6ae53d310
Your shared secret is Ut5hzrxs7uV87mzCAKL3ztrzesWWBiNa

You would enter:https://webhook.botpress.cloud/57fcfb04-51fd-4381-909a-10e6ae53d310?shared_secret=Ut5hzrxs7uV87mzCAKL3ztrzesWWBiNain the Endpoint URL field.

Check the Enable authentication checkbox.

Select the service account email address you created earlier in the Service account field.

Enter the shared secret you generated earlier in the Audience field.

Although this field is marked optional in Google Console, it’s required for the integration to work properly.

Under Expiration period, select Never expire.

Under Acknowledgement deadline, enter 60 seconds.

Under Retry policy, select Retry after exponential backoff delay. Set the minimum backoff to 60 seconds and the maximum backoff to 600 seconds.

Select Create to create the subscription.

Step 10. Authorize the OAuth application

On Gmail, log in to the Google account you want to use with the Gmail integration.

Once logged in, go to the following URL in your browser:

https://accounts.google.com/o/oauth2/auth?response_type=code&scope=https://mail.google.com/%20https://www.googleapis.com/auth/gmail.send&access_type=offline&prompt=consent&redirect_uri=https://botpress.com&client_id=YOUR_CLIENT_ID

Replace YOUR_CLIENT_ID with your OAuth Client ID from Step 4. For example, if your OAuth client ID is abcd, the URL should end with &client_id=abcd.

Follow the on-screen instructions to authorize the OAuth application with your personal Gmail account.

After completing the authorization, you will be redirected to botpress.com. Don’t close this page.

Copy the authorization code from the URL in your browser’s address bar. The authorization code is the string that appears after code= and before &scope= in the URL.

If you have difficulty finding the authorization code in the URL, you can use online tools like https://semalt.tools/en/url-parser or https://parseurlonline.com.

If you update any scopes, you need to generate a new authorization code and add it to the integration’s configuration in Botpress Studio. The previous authorization code won’t have the correct scope permissions.

You can now safely close this page.

Step 11. Configure the integration in Botpress

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the Gmail integration, then select Install Integration.

In the Configuration menu, select Configure manually with your own GCP App.

Fill in the required fields with all the information you saved from the previous steps.

The authorization code is only valid for a short period of time. If the code has expired, you will need to repeat the steps outlined in Step 10.

Select Save Configuration. If no error message is displayed, the integration was successfully configured.

Using the integration

Once you’ve successfully configured the integration, the email address you provided will begin responding to all incoming messages as your bot. If this is your desired behaviour, no additional setup is required. You can also use the integration’s Cards to interact with your Gmail inbox. This allows you to manage threads, drafts, attachments, and other data associated with your inbox.

Limitations

Costs

Botpress shall not be held responsible for any costs you may incur on the Google Cloud Platform while using the Gmail integration, should you choose to use the manual configuration mode. Ensure that you are aware of the costs associated with using the Gmail API and the Google Cloud Platform before using the manual configuration mode.

API limits

Standard Gmail API limitations apply to the Gmail integration in Botpress. These limitations include rate limits, message size restrictions, and other constraints imposed by the Gmail and Google Cloud platforms. Ensure that your bot adheres to these limitations to maintain optimal performance and reliability.More details are available in the Gmail API documentation.

Cards

Here’s a reference for all Cards available with the integration:

Change Message Labels

output

object

This Card has no output.

Create Draft

Create Label

Delete Draft

output

object

This Card has no output.

Delete Label

output

object

This Card has no output.

Delete Message

output

object

This Card has no output.

Get Draft

Get Label

Get Message Attachment

output

object

Show child attributes

attachment

object

required

Show child attributes

size

number | null

data

string | null

attachmentId

string | null

Get Message Attachment From Mail

output

object

Show child attributes

attachment

object

required

Show child attributes

size

number | null

data

string | null

attachmentId

string | null

Get Thread

List Drafts

input

object

This Card has no input fields.

List Labels

input

object

This Card has no input fields.

List Threads

input

object

This Card has no input fields.

Send Draft

Trash Message

output

object

This Card has no output.

Trash Thread

output

object

This Card has no output.

Untrash Message

output

object

This Card has no output.

Untrash Thread

output

object

This Card has no output.

Get started

ADK

Studio

Integrations

Webchat

Desk

​Setup

​Step 1. Create a Google Cloud Platform project

​Step 2. Enable the Gmail API

​Step 3. Configure the OAuth consent screen

​Step 4. Create OAuth credentials

​Step 5. Create a service account

​Step 6. Create a Pub/Sub topic

​Step 7. Grant publish rights on the Pub/Sub topic

​Step 8. Generate a shared secret

​Step 9. Create a Pub/Sub subscription

​Step 10. Authorize the OAuth application

​Step 11. Configure the integration in Botpress

​Using the integration

​Limitations

​Cards

​Change Message Labels

​Create Draft

​Create Label

​Delete Draft

​Delete Label

​Delete Message

​Get Draft

​Get Label

​Get Message Attachment

​Get Message Attachment From Mail

​Get Thread

​List Drafts

​List Labels

​List Threads

​Send Draft

​Trash Message

​Trash Thread

​Untrash Message

​Untrash Thread

​Update Draft

​Update Label

Setup

Step 1. Create a Google Cloud Platform project

Step 2. Enable the Gmail API

Step 3. Configure the OAuth consent screen

Step 4. Create OAuth credentials

Step 5. Create a service account

Step 6. Create a Pub/Sub topic

Step 7. Grant publish rights on the Pub/Sub topic

Step 8. Generate a shared secret

Step 9. Create a Pub/Sub subscription

Step 10. Authorize the OAuth application

Step 11. Configure the integration in Botpress

Using the integration

Limitations

Cards

Change Message Labels

Create Draft

Create Label

Delete Draft

Delete Label

Delete Message

Get Draft

Get Label

Get Message Attachment

Get Message Attachment From Mail

Get Thread

List Drafts

List Labels

List Threads

Send Draft

Trash Message

Trash Thread

Untrash Message

Untrash Thread

Update Draft

Update Label