Google Sheets

With the Google Sheets action you use an ordinary spreadsheet as a customer file or a log. During the call the assistant can look up a customer by customer number; after the call the action appends a row with the date, phone number, summary and your custom variables. No programming needed, just a one-off preparation in Google Cloud. To set this up you need the Editor or Admin role in Yarla.

Prepare in Google Cloud

Yarla reads and writes your spreadsheet through a service account: a technical Google account that only has access to what you explicitly share with it.

1. Go to the Google Cloud Console and create a new project, or pick an existing one.
2. Go to APIs & Services → Library, search for Google Sheets API and click Enable.
3. Go to IAM & Admin → Service accounts and click Create service account. Give it a recognisable name, e.g. "yarla". No roles are needed.
4. Open the service account, go to the Keys tab and choose Add key → Create new key → JSON.
5. Download the JSON file and keep it safe. It contains a private key; do not share it by email or chat.

Add the connection

1. In Yarla, go to Settings → Connections and click Add connection.
2. Give the connection a name and under Kind choose Google service account (for Sheets).
3. Under Value, paste the full contents of the downloaded JSON file and click Save.

The key is stored encrypted and not shown again. Yarla does not check the contents when saving and does not show the service account's email address. You find that address (something like yarla@your-project.iam.gserviceaccount.com) in the JSON file under client_email, or in the list of service accounts in Google Cloud. You need it in the next step.

Share the spreadsheet

1. Open the spreadsheet in Google Sheets and click Share.
2. Paste the service account's email address.
3. Choose the role Editor. Appending rows requires it; if you only want to read, Viewer is enough.
4. Turn off the notification and click Share.

Make sure the column headers are in row 1; the action uses those headers as field names.

Configure the action

1. Open the assistant, go to the Tasks tab, open Actions, click Add new and choose Google Sheets.
2. Give the action a name and choose the Mode. When follows automatically: Append a row (after the call) sets it to After the conversation, Look up rows (during the call) to During the conversation.
3. Fill in the settings below.

The action saves automatically once it has a name and a spreadsheet id; there is no save button.

Setting	Meaning	Default
Mode	Append a row (after the call) or Look up rows (during the call)	Append a row (after the call)
Spreadsheet id	The long id from the spreadsheet URL, between /d/ and /edit. For https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit that is 1AbCdEfGhIjKlMnOpQrStUvWxYz.	—
Sheet name	The name of the tab at the bottom, e.g. Customers or Sheet1. Change the default if your tab has another name.	Sheet1
Google service account	The service account from Settings → Connections. You can also paste the JSON key here under Paste a new key and click Store as key. It then appears among your connections with the name Google.	—

If you change When yourself afterwards, the mode stays as it is. Looking up rows only works during the conversation: if it is set to After the conversation, the action is skipped. Appending a row does work during the conversation: the assistant then does it as soon as your condition applies. At that moment all built-in variables, such as {{personNumber}}, {{startTimestamp}}, {{contact.name}}, {{conversationLink}}, {{summary}} and {{outcome}}, are still empty, and so are your custom variables. The assistant cannot fill them either, because this mode has no Parameters the assistant fills. Such a row stays mostly empty, so keep appending on After the conversation.

Look up rows (during the call)

In this mode the assistant looks up rows with a Filter. You write the filter as JSON in the MongoDB style: the key is the column header, the value an operator with a value. Available operators: $eq, $ne, $in, $nin, $regex, $gt, $gte, $lt, $lte and $contains.

{ "Customer number": { "$eq": "{{customer_number}}" } }

A plain value, such as { "Status": "open" }, works as $eq. Capitals do not matter when comparing text. $gt, $gte, $lt and $lte compare numbers; a cell like 1,250 or €10 does not count as a number and is left out. If you leave the filter empty, the assistant gets the first 5 rows.

You also set:

Setting	Meaning	Default
Parameters the assistant fills	The data the assistant extracts from the conversation, e.g. customer_number (string, "The customer number the caller mentions"). Use them in the filter as {{customer_number}}.	—
When should the assistant use this?	When the assistant uses the action and what it does with the result, e.g. "When the caller mentions their customer number. Confirm the name and address and ask whether the details are still correct."	—

On a phone call, the assistant can say in a few words that it is checking while we search.

The action returns the matching rows as JSON (at most 5 rows), with the column headers as field names. Combine several conditions in one object; all of them must then match:

{
  "Postcode": { "$regex": "^SW1" },
  "Status": { "$in": ["active", "trial"] }
}

If you test this with Try it out, turn on Perform actions for real. Otherwise the action is only simulated and the assistant reads nothing from your spreadsheet.

Append a row (after the call)

In this mode you map columns to templates under Columns. Each line is a column header and the value that goes into it:

Column	Template
Date	{{startTimestamp}}
Phone	{{personNumber}}
Name	{{contact.name}}
Outcome	{{outcome}}
Summary	{{summary}}
Postcode	{{postcode}}
Conversation	{{conversationLink}}

{{postcode}} is not a built-in variable: add postcode under Custom variables to extract, and the assistant takes it from the conversation afterwards. {{startTimestamp}} is a timestamp in ISO format, such as 2026-11-03T09:30:00.000Z. {{outcome}} is an English code: resolved, transferred, appointment_booked, abandoned, no_interaction, spam, voicemail or callback_requested.

If the sheet is still empty, we create row 1 with the column headers automatically. If you later add a column in the action that does not exist in the sheet yet, we add it at the end. Existing columns are matched by their exact name, so the order in your sheet may differ from the order in the action.

Examples

Conversation log

An action with the mode Append a row (after the call) and the columns from the table above. Leave Under what condition should this run after the conversation? empty: every conversation then becomes one row. Put a filter on the Outcome column in the sheet with the value callback_requested to see all callback requests at a glance, or use postcode as a custom variable to see which areas most enquiries come from.

Customer lookup

A sheet Customers with the columns Customer number, Name, Address and Service plan. Create an action with the mode Look up rows (during the call) and:

• parameter customer_number (string, "The customer number the caller mentions, usually five digits");
• filter { "Customer number": { "$eq": "{{customer_number}}" } };
• under When should the assistant use this?: "When the caller mentions their customer number. Say the name and ask whether the address is still correct. Mention whether they have a service plan."

The assistant then says something like: "I can see you're Mrs de Vries on Canal Street, with a service plan. Is that right?"

Troubleshooting

If a row fails after the conversation, you see the error in the Inbox: open the conversation, expand Technical details and look under What the actions did. Yarla does not retry that row. If a lookup fails during the conversation, the error is not kept with the conversation. In a text conversation the assistant carries on without the data and says it cannot retrieve them right now. On a phone call with a ChatGPT voice, a Google error or an invalid key gives the assistant no answer: it can stay silent until the caller speaks again. In that case, go through the points below.

• Error 403 (no access): the spreadsheet is not shared with the service account's email address, or only as Viewer while you want to append rows. Check the spreadsheet's sharing dialog.
• Error 404 (not found): the spreadsheet id is wrong. Do not paste the whole URL.
• Error 400 (Unable to parse range): the sheet name does not exist. Copy the name exactly from the tab at the bottom.
• no Google credential configured or Google credential not found: no existing service account is selected on the action. Choose one under Google service account.
• Error about the key or about JSON: the connection's value is not the full JSON file. Paste the contents again with Replace under Settings → Connections. It can take up to 5 minutes for the new value to apply.
• Empty result when looking up: the column header in the filter does not exactly match row 1 (watch for capitals and spaces), or the value differs from what the cell shows. We compare with the text in the cell: a customer number the sheet displays as 12,345 does not match "12345". Format the column in the sheet as plain text.
• Phone number without the +: we enter values as if you typed them, so Google Sheets can store +31612345678 as a number. Format the column in the sheet as plain text.
• An extra column at the end: the headers in row 1 were changed after the action was set up. The action cannot find the old name and creates a new column. Make sure the names in the action and in the sheet are identical.
• Message that the API is not enabled: enable the Google Sheets API in the right project (step 2 of the preparation) and try again after a few minutes.

Related articles

• Actions
• HTTP request action
• Appointments — a calendar connects differently: by signing in, without a service account