# Google Sheets

### What is Google Sheets Integration?

Google Sheets integration enables BotPenguin AI Agents to automatically record and reference structured data—such as leads, responses, and attribute-level information—directly from live conversations. This streamlines data operations, supports automation workflows, and enhances AI agent intelligence through real-time sync capabilities.

***

### Benefits of Google Sheets Integration

* ⚡ Enables real-time data sync between chat interactions and Google Sheets.
* 📊 Supports structured lead tracking without manual data entry.
* 🤖 Enhances agent intelligence by using stored data in responses.
* 🔁 Reusable configuration for multiple bots and use cases.
* 🧩 Allows metadata mapping for dynamic and custom attributes.

***

### How to Use Google Sheets Integration

#### **A. Connect Google Sheets to a Bot**

1. Navigate to any bot (preferably a Website bot for speed).
2. Go to **“Third Party Apps Integration”** in the left navigation.
3. Locate **“Google Sheets”** from the list or search bar.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FRW0g6auFIY4VCtH9FryO%2Fimage.png?alt=media&#x26;token=d2b7deb7-1613-4782-87c0-58f31bdd44b6" alt=""><figcaption></figcaption></figure>

4. Click **“Connect”**, review the use cases and documentation if visible.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FHP6oJLjoVJ0kmLoD5tF3%2Fimage.png?alt=media&#x26;token=c5066820-6aaf-40ee-8624-745e6320d6f9" alt=""><figcaption></figcaption></figure>

5. Click **“Connect”** again and sign in using your Google account.
6. Grant all required Google permissions to authorize BotPenguin.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FgsOOjWMoeGwdSGyYclcZ%2Fimage.png?alt=media&#x26;token=cbc0d647-1d9d-4b0f-9b48-c67fbfa64740" alt=""><figcaption></figcaption></figure>

7. Once connected, click **“Test Lead”** to generate a demo sheet.\
   This validates access and creates a reference spreadsheet.

***

#### **B. Configure Google Sheets in Integrations**

1. Go to the left-hand menu and click **“More”**.
2. Select **“Integrations”**.
3. From the integrations list, locate **Google Sheets** and click **“Connect”**.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FGX14Txe69XSANHhFuIFU%2Fimage.png?alt=media&#x26;token=1568e790-637b-4860-af71-565fdde7153f" alt=""><figcaption></figcaption></figure>

4. Choose an existing configuration or click **“Add New Configuration”**.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FJvjB7nE0lKFgNWng0TgX%2Fimage.png?alt=media&#x26;token=aeb197d5-9e36-4b01-b5d8-b10429e10c63" alt=""><figcaption></figcaption></figure>

5. Authorize once again via Google OAuth if prompted.
6. When complete, the configuration will be available for use across agents.

***

#### **C. Prepare Metadata for AI Agent**

1. Go to the AI Agent where Google Sheets will be used or click **“Create Agent”** for a new one.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2F8ZgHZZtelfkQWtPLGm4s%2Fimage.png?alt=media&#x26;token=fe09e299-c6d0-4785-9838-2dcf9b6a517a" alt=""><figcaption></figcaption></figure>

2. Access the **Agent Personality & Settings** tab, "**Meta Data**" sub-tab.
3. Click on  **“Manage Attributes”** to open Custom Attributes.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2Fr5c2jEzAIoTWWIsyeFTW%2Fimage.png?alt=media&#x26;token=f88fba70-dbdf-4d3f-8b80-40ae830f4baa" alt=""><figcaption></figcaption></figure>

4. Create mandatory attributes such as:
   1. Title
   2. Phone Number
   3. Email Address
   4. Any additional custom fields

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FaesThIqqApQda8Y6H49j%2Fimage.png?alt=media&#x26;token=241bf23c-f1a1-47e9-8f94-c37ee6f32b90" alt=""><figcaption></figcaption></figure>

5. Ensure each attribute toggle is turned **ON** to keep it visible.
6. Return to the metadata panel and enable **“Extract Metadata”** for each attribute.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2Fgm4REeWrUsXO1Zp4OcCi%2Fimage.png?alt=media&#x26;token=022bdb1f-564a-479e-9ff8-cedfccb499c3" alt=""><figcaption></figcaption></figure>

***

#### **D. Add Google Sheets Tool Inside Prompt**

1. Open the **Prompt** screen (Core Instructions or Conversation Flow).
2. Type a **backslash ( \ )** to open the tool selector.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FxP8H79sLkhd7zfvsxIVJ%2Fimage.png?alt=media&#x26;token=8d62c804-9183-4d31-8c7c-2038eae4694d" alt=""><figcaption></figcaption></figure>

3. Search for or scroll to **Google Sheets** and select it.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FdX6Xkml9UEZ4x6w07ots%2Fimage.png?alt=media&#x26;token=478e3b62-abfb-49c6-a365-3ed32de5e8ec" alt=""><figcaption></figcaption></figure>

4. Choose the credential from the dropdown and click **Update & Next**.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2FpmY1TKTBaaYXlUnnMkfp%2Fimage.png?alt=media&#x26;token=c5dc8f0d-5abb-44ee-90d6-f46a808906fd" alt=""><figcaption></figcaption></figure>

**Configure Tool Settings**

1. Select the spreadsheet created earlier (from testing step).
2. Select the active sheet — default is **Sheet 1**.

<figure><img src="https://1745791824-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAPDb8cKQtGlIAfgHjcsQ%2Fuploads%2F8AaDuidQ92qluWQYojPj%2Fimage.png?alt=media&#x26;token=0a1d9206-9d13-4c00-8fc7-c421a7cd6335" alt=""><figcaption></figcaption></figure>

3. Map metadata to Sheet columns: (3rd Party App Variables -> Map with Attributes)
   1. Title → Title Field
   2. Email → Email Attribute
   3. Phone → Phone Attribute
4. Optional actions:
   1. Add/remove mappings
   2. Add fallback values
   3. Make fields mandatory
5. Click **Update & Next** to finalize the mapping.

***

#### **5. Test and Finalize Integration**

1. Test the connection by entering mock values for mapped fields.
2. Click **“Test Data”** to validate interaction and sheet entry.
3. Once confirmed, click **Finish** to activate the integration.

🎉 Congratulations, you have successfully completed this section! You're one step closer to mastering BotPenguin.

***

### FAQs

<details>

<summary>Do I need to integrate Google Sheets separately for every agent?</summary>

No. Once configured globally under Integrations, you can reuse the same credentials across multiple agents by selecting them during mapping.

</details>

<details>

<summary>Why am I not seeing metadata variables during mapping?</summary>

Metadata fields must be created under **Manage Attributes**, enabled, and configured to **Extract Metadata** before they appear during tool mapping.

</details>

<details>

<summary>What happens if a user skips a required field?</summary>

If the field is mandatory and marked as required, the bot will prompt the user again.\
If fallback values are configured, those will be stored instead.

</details>

<details>

<summary>Can I write to multiple worksheets within the same file?</summary>

Yes. During mapping, you can choose any sheet inside the spreadsheet. Multiple tools can reference different sheets if required.

</details>

<details>

<summary>Is it possible to update existing records instead of creating new rows?</summary>

At this time, the integration supports **append mode only**. Update mode is planned for a future release.

</details>

<details>

<summary>Why is my sheet not created after clicking Test Lead?</summary>

Ensure Google OAuth permissions were fully granted and no pop-ups were blocked during authentication.

</details>

***

If you still have questions for our team, write to us at [**support@botpenguin.com**](mailto:support@botpenguin.com). We’ll get back to you within 48 hours.