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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.botpenguin.com/settings/integrations/google-sheets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.