> 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/integrations/google-sheets.md).

# 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="/files/G8PEQul0VromKLQY5I7U" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/HXDXSLYY6f7fQJBQ4qJo" 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="/files/N7GylkqP4JFXlJCGPWxP" 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="/files/1gGNKonwqHyw560FPkjN" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/LYsGq5g3mPASqUVrulPY" 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="/files/7yVMlXS9rGLFCXLNUSKl" 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="/files/nsotvdk2cvCpQSbYhMtk" 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="/files/R1qxYX0Xo4ZG7gZWayhc" 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="/files/q5lf2hWJddCl3CAk002M" 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="/files/ugKojK03Ij8vF8IC9tj5" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/50d3eiSMJjLGtg9vYSVT" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/QG0UKsLGir7cH1FJe51F" 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="/files/frw8vLsUjcwB6xdAGDaT" 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.