add_google_sheets

add_google_sheets_row(sheet_id: str, data: dict, sheet_name: str = None) -> dict

Adds a row to a Google Sheet. Each key in the data dict maps to a column header, and the value becomes the cell content.

By default the row goes to the first tab. Pass sheet_name to append to a specific tab instead — useful for keeping several trackers in one spreadsheet.

Parameters

Name	Type	Description
`sheet_id`	`str`	The spreadsheet ID — the part of the Google Sheets URL between `/d/` and `/edit`
`data`	`dict`	Column-value pairs. Keys are column headers, values are cell contents. All values are converted to strings
`sheet_name`	`str`	Optional. The tab to append to, named exactly as it appears on the tab at the bottom of the spreadsheet. Defaults to the first tab

Returns

dict — {"success": bool, "message": str}

Prerequisites

The Google Sheet must be shared with the Octocom service account:

[email protected]

Give it Editor access. The sheet must have a header row — column names in the first row that match the keys in your data dict.

Tab names must match exactly

sheet_name must match the tab name exactly, including capitalization and any spaces. If it doesn't match, the call fails with a 404 listing the tabs that do exist, and nothing is written.

Examples

Log refund events to a spreadsheet

def execute_action(context):
    order_id = context["args"]["orderId"]
    amount = process_refund(order_id)

    add_google_sheets_row("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms", {
        "Order ID": order_id,
        "Refund Amount": amount,
        "Reason": context["args"].get("reason", ""),
        "Date": datetime.now().isoformat(),
        "Conversation ID": context["conversation"]["id"],
    })

    return {"success": True, "amount": amount}

Keep several trackers in one spreadsheet

Each tracker writes to its own tab of the same spreadsheet, so everything stays in one file.

def execute_action(context):
    add_google_sheets_row(
        "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
        {
            "Conversation ID": context["conversation"]["id"],
            "Topic": context["args"]["topic"],
            "Resolved": context["args"]["resolved"],
        },
        sheet_name="Escalations",
    )

    return {"success": True}

Each tab keeps its own header row, so different trackers can have completely different columns.

Collect lead information

def execute_action(context):
    add_google_sheets_row("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms", {
        "Name": context["args"]["name"],
        "Email": context["args"]["email"],
        "Company": context["args"]["company"],
        "Interest": context["args"]["interest"],
    })

    return {"success": True, "message": "Thank you, we'll be in touch!"}

add_google_sheets_row