> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/settings/third-party-apps/google-sheets.md).

# Google Sheets

This section contains essential information and usage guidelines for integrating and using Google Sheets within BotPenguin AI Agents.

### 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 More -> Third Party Apps, and search for Google Sheets

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/ke720x0JdeTD7K295Zne/images/google-sheets-step-1.png)

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

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/u12WLCGpEFVYmJhQvrsW/images/google-sheets-step-2.png)

5. Click **“Add Configuration”** and fill the configuration name. Then, click on "Continue to Google Sheets" to start OAuth Flow.

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/qNTo863y8onLMaMvZ7zA/images/google-sheets-step-3.png)

7. Once Oauth flow is compelted, click on **Save Configuration** to add the configruation.

***

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

1. Access the "**More"** -> "**Custom Attribute**" sub-tab.
2. Click on "Add Attribute" to 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%2FBb9u1UoC8rwzcSZ1Q8bP%2Fimage.png?alt=media&amp;token=29d16c42-0a72-4e99-aa76-478083814d51" alt=""><figcaption></figcaption></figure>

3. Once the attributes are made, ensure each attribute toggle is turned **ON.**
4. Return to the metadata panel and enable **“Extract Metadata”** for each attribute.

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/gqncoEtBGpiGCm3ZwNcA/images/google-sheets-step-9.png)

***

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

1. Open the **Prompt** screen.
2. Click on **Add Tools** to open the tool selector.

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/6MkrinJe79s9JBMrNPnK/images/google-sheets-step-10.png)

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

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/3xFIA8RmDfSFCOjeKkM5/images/google-sheets-step-11.png)

4. Choose the credential from the dropdown and click **Continue.**

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/vlTfbbQ8AZB6KnKbpZOP/images/google-sheets-step-12.png)

**Configure Tool Settings**

1. Select all the actions that you want to allow the sheet to have.

![](https://content.gitbook.com/content/APDb8cKQtGlIAfgHjcsQ/blobs/fahgqlkh7yEr2cVnkDIz/images/google-sheets-step-13.png)

3. Configure the sheet prompt, making sure to mention when the tool should be activated.

{% hint style="success" %}
🎉 Congratulations, you have successfully completed this section! You're one step closer to mastering BotPenguin.
{% endhint %}

***

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

***

### Support

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.
