> 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/bots/whatsapp-bot/manage-chatflow/components-in-chatflow/integrations-component/google-sheets-integration/google-sheets-chat-flow-trigger.md).

# Google Sheets - Chat Flow Trigger

### What is Google Sheets Chat Flow Trigger?

Google Sheets Chat Flow Trigger allows your chatbot to interact with Google Sheets at specific points within a conversation.

Unlike Lead Alert Trigger, which automatically sends lead information to a spreadsheet, Chat Flow Trigger executes only when the Google Sheets component is reached in the chatbot flow.

Using Chat Flow Trigger, you can:

* Retrieve information from Google Sheets
* Add new records to a spreadsheet
* Update existing records
* Delete records when required
* Build dynamic, data-driven chatbot workflows

{% hint style="info" %}
Chat Flow Trigger gives you complete control over when Google Sheets actions are executed during a conversation.
{% endhint %}

***

### When should you use this?

Use Chat Flow Trigger when you need to:

* Verify customer information
* Retrieve order details
* Check appointment records
* Save form submissions
* Update customer data
* Delete outdated records
* Build spreadsheet-based workflows

{% hint style="info" %}
**Note**: This integration component is only available for WhatsApp Chatbots.
{% endhint %}

***

### Step-by-Step Instructions

#### Step 1: Open Google Sheets Integration

1. Open your desired WhatsApp Bot.
2. Navigate to Third Party Integrations.
3. Search Google Sheets and click Connect.

<figure><img src="/files/q3AGrfgpN0cl1AZjKp2Z" alt=""><figcaption></figcaption></figure>

***

#### Step 2: Connect Your Google Account

4. Click Sign in with Google.
5. Select the Google account you want to connect.
6. Review the requested permissions.
7. Click Continue.

Your Google account will be connected once authorization is complete.

<figure><img src="/files/flAhLpVm7iMxplVzrKnO" alt=""><figcaption></figcaption></figure>

***

#### Step 3: Enter a Title

8. Enter a name for this configuration. Examples:
   1. Lead Capture Sheet
   2. Appointment Records
   3. Customer Database

The title helps you identify this configuration when using Google Sheets inside Chatflows.

<figure><img src="/files/AZipRW94BqCtgvUwHskO" alt=""><figcaption></figcaption></figure>

***

#### Step 4: Select a Trigger Type

9. Choose when the platform should send data to Google Sheets. In this article, we will be focusing on Chatflow Trigger. For Lead Alert Trigger refer to-

| Trigger Type           | When It Fires                                                |
| ---------------------- | ------------------------------------------------------------ |
| **Chatflow Trigger**   | When a Google Sheets component is executed inside a Chatflow |
| **Lead Alert Trigger** | Automatically when a new lead is generated                   |

<figure><img src="/files/VTuLd4ANNsJR1dWD5Eqq" alt=""><figcaption></figcaption></figure>

#### Step 5: Map Questions

10. Select a chatbot question from the dropdown.

<figure><img src="/files/oLxNwN5Kqxl0XYVju1qu" alt=""><figcaption></figcaption></figure>

11. Enter the corresponding column name as the mapping value.

<figure><img src="/files/39WzYBoTMYCQ9uEzLWM7" alt=""><figcaption></figcaption></figure>

12. Repeat for all required questions.
13. Click Add Parameters to add more rows.

<figure><img src="/files/qZRUtdGcJY6QpVDpRVHI" alt=""><figcaption></figcaption></figure>

***

#### Step 6: Map Custom Attributes

14. Select a customer attribute from the dropdown.

<figure><img src="/files/3Sn0dznCEbEEdzkbxFIT" alt=""><figcaption></figcaption></figure>

15. Enter the corresponding column name as the mapping value.

<figure><img src="/files/ngUPmUcUwVghohYCHbmb" alt=""><figcaption></figcaption></figure>

16. Click Add Parameters to add more rows.
17. Click on Save.

<figure><img src="/files/UAmJphMHaLXHtvLefH5A" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Congratulation! You are done with the mapping of the Google sheet. Now, we move to adding the Component in the chatflow.
{% endhint %}

***

### Accessing the Google Sheets Component

1. Navigate to Chat Flows.
2. Open the flow you want to edit.
3. Search Google Sheets component and click on it to add it onto the canvas.

<figure><img src="/files/0eyt1lwTTdxOQrRF3pOS" alt=""><figcaption></figcaption></figure>

4. Click on configure on the Google Sheets component.

<figure><img src="/files/QZtSoeX06ovGLkbbNAx2" alt=""><figcaption></figcaption></figure>

***

### Understanding the Configuration Panel

1. Provide a name for the Google Sheets action. Examples:
   1. Get Customer Details
   2. Add Lead Record
   3. Update Appointment
   4. Delete Registration

This name is used for identification within the flow.

<figure><img src="/files/lqVFrEDNCffJl3GCFbY9" alt=""><figcaption></figcaption></figure>

2. Select the Google Sheet connected through your Google Sheets Integration.&#x20;

<figure><img src="/files/OA7v7JqoxMkJ69xs6AAJ" alt=""><figcaption></figcaption></figure>

3. Select the worksheet (tab) that contains the data you want to access.

<figure><img src="/files/6Yzv3khYnMkf3kFYc2ZO" alt=""><figcaption></figcaption></figure>

4. Select the action you want BotPenguin to perform. Available actions:

| Action          | Description                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Get Details** | Retrieve information from a Google Sheet by searching for a matching record and using the returned data within your chatbot flow. |
| **Add Row**     | Create a new row in the selected Google Sheet using chatbot responses, customer attributes, or mapped values.                     |
| **Update Row**  | Locate an existing record and update specific fields with the latest information collected during the conversation.               |
| **Delete Row**  | Find and permanently remove a matching record from the selected Google Sheet worksheet.                                           |

<figure><img src="/files/DGzWnYPxly9itVO1O23Y" alt=""><figcaption></figcaption></figure>

***

### 🔍 Get Details

Use Get Details when you want to retrieve information from a spreadsheet.

Common use cases:

* Customer Lookup
* Order Tracking
* Appointment Verification
* Membership Validation

***

1. Search Options: Search Options determine how BotPenguin locates records within the spreadsheet. Examples:
   1. Email Address
   2. Phone Number
   3. Customer ID
   4. Order Number

<figure><img src="/files/xC3Vo5tScG7AIDiAB1bk" alt=""><figcaption></figcaption></figure>

2. Search Range: Specify the range of columns that should be searched. Examples:
   1. A:D
   2. A:H
   3. C:F

<figure><img src="/files/6yOu2Ehczl0xrP3uXCXY" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
BotPenguin searches only within the specified column range.
{% endhint %}

3. Search Index: Specify which column contains the searchable value. Examples: If Email Address is stored in column B, the Search Index should be set to 2.

| Column | Index |
| ------ | ----- |
| A      | 1     |
| B      | 2     |
| C      | 3     |
| D      | 4     |

<figure><img src="/files/XmqHhQxrE3Xpl8H7Zwit" alt=""><figcaption></figcaption></figure>

4. Response Mapping: Map values returned from Google Sheets to [customer attributes.](https://help.botpenguin.com/settings/managing-custom-attribute#what-are-custom-attributes) Example:

| Google Sheet Value | Customer Attribute |
| ------------------ | ------------------ |
| Name               | Name               |
| Email              | Email              |
| Order Status       | Order Status       |

<figure><img src="/files/vmD3iuXAIpPyD08cGWMs" alt=""><figcaption></figcaption></figure>

5. Success Next Message: Select the chatbot message that should be displayed when a matching record is found.

<figure><img src="/files/SdMduV6afI7LDjypgjEq" alt=""><figcaption></figcaption></figure>

6. Failure Next Message: Select the chatbot message that should be displayed when no matching record is found.

<figure><img src="/files/2Ud1vgUUea3w8SAWIpiz" alt=""><figcaption></figcaption></figure>

***

### ➕ Add Row

Use Add Row when you want to create a new record in Google Sheets. Common use cases:

* Lead Capture
* Registration Forms
* Appointment Requests
* Feedback Collection

***

1. Repeat Steps 1 - 6 specified in the Get Details Section

<figure><img src="/files/oR1B7pZpPBwIeC4osmDP" alt=""><figcaption></figcaption></figure>

2. Add Row Flow Logic: Configure the chatbot message that should be displayed after the action is completed

<figure><img src="/files/qbeIc6kdQDoAi1zE68dH" alt=""><figcaption></figcaption></figure>

***

### ✏️ Update Row

Use Update Row when you want to modify an existing spreadsheet record.

Common use cases:

* Updating Customer Information
* Editing Appointment Details
* Updating Order Status
* Managing Registrations

BotPenguin locates the existing record and updates the mapped fields.

***

1. Repeat Steps 1 - 6 specified in the Get Details Section
2. Update Row Flow Logic: Configure the chatbot message that should be displayed after the action is completed

<figure><img src="/files/KL1XbvGzIDONpRKOUmVJ" alt=""><figcaption></figcaption></figure>

***

### 🗑️ Delete Row

Use Delete Row when you want to remove an existing record from the spreadsheet.

Common use cases:

* Appointment Cancellation
* Record Cleanup
* Removing Obsolete Data

BotPenguin searches for the matching record and removes it from the worksheet.

***

1. Repeat Steps 1 - 6 specified in the Get Details Section
2. Delete Row Flow Logic: Configure the chatbot message that should be displayed after the action is completed

<figure><img src="/files/7JJlILh8fwI55lzq0KZ6" alt=""><figcaption></figcaption></figure>

<details>

<summary><strong>Advanced Settings</strong></summary>

1\. Notify me when the user responds: Enable this option when the chatbot should notify you when the user responds from Google Sheets

2. Delay Execution: Add a delay before the Google Sheets action executes. This can be useful when coordinating multiple workflow steps.

</details>

***

### Best Practices

> 💡 Use unique values such as Email Address, Phone Number, Customer ID, or Order Number when searching records.

> 💡 Always configure both Success and Failure paths.

> 💡 Use customer attributes to store retrieved values for later use.

> 💡 Test your workflow before publishing.

***

### Troubleshooting

<details>

<summary>Google Sheets action is not connecting</summary>

Ensure that your Google Sheets account is connected under **Integrations** and that the selected Google account has permission to access the spreadsheet. If necessary, reconnect the integration and try again.

</details>

<details>

<summary>Get Details is not returning any records</summary>

Verify that the **Search Key**, **Search Range**, **Search Index**, and selected worksheet are correct. Also ensure that the value being searched matches the spreadsheet data exactly, including formatting and capitalization where applicable.

</details>

<details>

<summary>Rows are not being added or updated</summary>

Check that all required fields are mapped correctly and that the selected worksheet still has the same column structure used during configuration. If the spreadsheet structure has changed, update the field mappings.

</details>

<details>

<summary>Update or Delete Row affects the wrong record</summary>

Ensure you are using a unique value such as an email address, phone number, customer ID, or order number as the Search Key. Using duplicate values may update or delete an unintended row.

</details>

<details>

<summary>Changes made to the spreadsheet are not reflected in the chatbot</summary>

If the worksheet structure, column names, or column order has changed after the component was configured, review the configuration and remap the affected fields before testing again.

</details>

***

### FAQs

<details>

<summary>What happens if no matching record is found during a Get Details action?</summary>

The chatbot follows the configured **Failure Next Message** path.

</details>

<details>

<summary>Can I update only specific fields in a spreadsheet record?</summary>

Yes. Only the fields mapped in the **Update Row** action will be modified.

</details>

<details>

<summary>What values should I use as a Search Key?</summary>

Use a unique identifier such as an email address, phone number, customer ID, membership ID, or order number to ensure accurate record matching.

</details>

<details>

<summary>Can I use multiple Google Sheets components in the same chatbot flow?</summary>

Yes. You can combine multiple Google Sheets actions within a single chatbot flow to build advanced spreadsheet-driven workflows.

</details>

<details>

<summary>Why is Get Details returning no results even though the record exists?</summary>

Verify that the **Search Key**, **Search Range**, **Search Index**, and worksheet selection are correct. Also ensure the stored data matches the value being searched exactly.

</details>

<details>

<summary>Can I create complete spreadsheet workflows using Google Sheets Integration?</summary>

Yes. By combining **Add Row**, **Get Details**, **Update Row**, and **Delete Row** actions, you can build complete spreadsheet-based workflows within BotPenguin.

</details>

<details>

<summary>What is the difference between Search Range and Search Index?</summary>

**Search Range** defines the group of columns BotPenguin searches within, while **Search Index** specifies the exact column containing the value to be matched.

</details>

<details>

<summary>What happens if the worksheet structure changes after configuration?</summary>

Changes to column names, positions, or worksheet structure may break existing mappings. Review and update the configuration after making structural changes to the spreadsheet.

</details>

<details>

<summary>Can I store retrieved Google Sheets values in customer attributes?</summary>

Yes. Retrieved values can be mapped to customer attributes and used later in the chatbot flow for personalization, routing, or additional actions.

</details>

<details>

<summary>Should I configure both Success and Failure paths?</summary>

Yes. Configuring both paths ensures your chatbot can handle successful and unsuccessful Google Sheets operations gracefully, resulting in a better user experience.

</details>

***

### Related Features

{% content-ref url="/pages/GWB2Dnqws1objlXWdyIl" %}
[Google Sheets Integration](/bots/whatsapp-bot/manage-chatflow/components-in-chatflow/integrations-component/google-sheets-integration.md)
{% endcontent-ref %}

{% content-ref url="/pages/6ttpiKsmzt3DBoquI8zO" %}
[Managing Custom Attribute](/settings/managing-custom-attribute.md)
{% endcontent-ref %}

{% content-ref url="/pages/2Zpm8t0xDV1XalyNwckp" %}
[Manage Chatflow](/bots/whatsapp-bot/manage-chatflow.md)
{% endcontent-ref %}

***

### 🎉 Completion

🎉 You now understand how to use Google Sheets Chat Flow Trigger to retrieve, create, update, and delete spreadsheet records directly from chatbot conversations.

***

### Support

If everything is correct and you are still unable to move forward, write to us at <support@botpenguin.com>. We will respond back within 48 business hours.