# Google Workspace

> Two roles: A platform administrator registers one Google OAuth client once (steps 1–4 below). After that, each workspace operator just clicks Connect Google account and approves the consent screen. Credentials never leave the admin settings; operators never see a Client ID or Secret.

## Overview

A single Google sign-in connects an entire workspace to Google Workspace and unlocks several features at once: Calendar slot pickers for appointment booking, on-demand Google Meet links inside flows and the inbox composer, and the Sheets, Docs, and Forms flow-builder nodes.

You manage the connection from More → Google account. Connect once per workspace — the connection is stored securely (encrypted) against that workspace and reused everywhere Google is needed.

> Note: The Google account belongs to whoever clicks Connect first. Calendar events and Meet links appear in that user's Google Calendar — typically the workspace owner. There is a hard cap of one Google account per workspace.

## Admin: create the Google OAuth client

Do this once for the whole platform in the Google Cloud Console.

### Step 1 — Project + OAuth consent screen

1. Create (or select) a Google Cloud project.
2. Open APIs & Services → OAuth consent screen. Choose External (unless every connecting user is inside your own Google Workspace org, in which case Internal). Fill in the app name, support email, and authorized domain.
3. Add the scopes you intend to use (listed in step 3 / the scope table). While the app is in Testing, add the Google accounts that will connect as Test users; publish the app to remove that limit.

### Step 2 — Enable the required APIs

Under APIs & Services → Library, enable each of these (search by name, click Enable):

- Google Calendar API — slot pickers + Meet link generation.
- Google Sheets API — the Sheets flow node.
- Google Docs API — the Docs flow node.
- Google Drive API — doc copy/share + the file pickers.
- Google Forms API — the Forms flow node.

> If an API isn't enabled, calls to it return a Google error even when the OAuth scope was granted. Enable all five up front so every flow node works.

### Step 3 — Create the OAuth 2.0 Client (Web) + redirect URI

1. Open APIs & Services → Credentials → Create credentials → OAuth client ID.
2. Application type: Web application.
3. Under Authorized redirect URIs, click Add URI and paste exactly:

`https://YOUR-DOMAIN/appointments/oauth/google/callback`

Replace `YOUR-DOMAIN` with the real host WaDesk runs on (protocol, host, and path must match character-for-character, with no trailing slash). This is the single callback WaDesk uses for the whole Google integration — Calendar, Meet, Sheets, Docs, and Forms all return here.

4. Click Create. Google shows the Client ID and Client Secret — copy both.

### Step 4 — Paste the credentials into WaDesk (admin)

1. Go to Admin → Settings → Integrations → Google.
2. Paste the Client ID and Client Secret (the secret is encrypted and never shown again).
3. Turn Enable on and save. A readiness strip confirms the credentials are saved, the feature is on, and the redirect is set.

The redirect URI defaults to `https://YOUR-DOMAIN/appointments/oauth/google/callback`; there's an optional override field if your setup needs a different one — whatever you use must match what you registered in step 3 exactly. The standard set of permissions is pre-filled (see the scope table), and you can trim it if you want to request less.

> Until this is done: the workspace Google account page shows an Admin setup needed banner and the Connect button is disabled. Workspace operators cannot self-configure this — it is a one-time platform setup.

## Operator: connecting your account

1. Open More → Google account.
2. Click Connect Google account. You're taken to Google's consent screen. (WaDesk asks Google for the kind of access that lets the connection renew itself in the background, so you don't have to keep signing in again.)
3. Sign in and approve the access. Google shows you exactly what you're granting.
4. You land back on the page. The status flips to connected, and the connection row shows your account email and avatar, the selected calendar, the access you granted, and the connection time.

The page also shows a four-stat row: connection Status, number of Calendars available, how many permissions you granted, and whether the auto-renew is active. A side panel lists everything this connection powers (the Book Appointment node, the Google Meet node, the inbox Send Meet button, and the Sheets/Docs/Forms nodes).

> Tip: Your main Google calendar is selected automatically on connect, so Meet links work right away. If you have more than one calendar, a Change calendar action (in the connection row and on the Appointments settings page) lets you pick which calendar appointment events are written to.

## OAuth scopes & privacy

WaDesk requests the minimum scopes needed for the features it powers, bundled into one consent so a single approval unlocks every flow node. These are the exact scopes the default consent requests:

Feature | Scope | Access
--- | --- | ---
Calendar & Meet | `auth/calendar` | Check your free/busy times, create and update calendar events, and generate Meet links
Sheets node | `auth/spreadsheets` | Add and read rows in your spreadsheets
Docs node | `auth/documents` | Copy a template document and fill in its placeholders
Drive (file pickers + sharing) | `auth/drive` | List your existing Sheets/Docs/Forms so the flow-builder pickers can show them, copy a Docs template you choose, and share the copy. A narrower Drive permission won't work here — it would only see files WaDesk itself created, leaving the pickers empty.
Forms node | `auth/forms.body.readonly` | Read a form's structure and its responder link

WaDesk also requests the basic profile permissions (`openid`, `userinfo.email`, `userinfo.profile`) so the account page can show your email and avatar.

> Privacy: The `drive` permission is needed so the flow builder can list and copy the files you choose. WaDesk only reads or writes the specific files you pick in a flow node — it never touches the rest of your Drive.

## Reconnecting for new scopes

If your Google account was connected before the Sheets/Docs/Forms nodes existed, the page compares your granted scopes against the required set and shows a Reconnect to unlock new flow nodes banner listing exactly which scopes are missing. Click Reconnect to re-run OAuth with the full scope set. Existing Calendar and Meet features keep working throughout — the reconnect only adds access, it never breaks the current connection.

## Calendar & Meet links

Once connected, the Google token powers three Meet/Calendar touchpoints:

- Book Appointment node — offers the customer real open time slots (your availability minus whatever is already busy on your Google calendar) and writes the booking to your calendar.
- Google Meet node — creates a fresh Meet link inside a flow and sends it to the customer.
- Inbox “Send Meet link” — a button in the Team Inbox composer. The operator picks a duration and a Meet link is generated and dropped into the reply. The button is hidden until Google is connected.

> Note: If you disconnect Google, your saved flows stay intact, but any flows currently running that hit a Calendar or Meet node will fail, and the inbox Send Meet button disappears. Reconnect anytime — everything resumes immediately with the same settings.

## Sheets, Docs & Forms flow nodes

Connecting Google enables these nodes in the visual flow builder. Each node reads its target file through a Drive picker populated from your account, so you select the file by name rather than pasting IDs.

Node | What it does
--- | ---
Google Sheets | Append a row to a sheet (e.g. log a lead) or look up a row by matching a column value, then map the result onto flow variables.
Google Docs | Copy a template document, replace `{{placeholder}}` and `{placeholder}` tokens with flow variables, optionally make it shareable (anyone-with-the-link can read), and return the link to the new doc.
Google Forms | Send a form's link to the customer, pause the flow, and resume it when the customer submits the form.

The picker for each node lists the matching files from your account (spreadsheets, documents, or forms), with the most recently edited ones first.

## Forms: resuming a paused flow

The Google Forms node uses a small Google Apps Script so that submitting the form can resume a paused WhatsApp flow. When you set up a Forms node, WaDesk generates a ready-to-paste script with your connection details already filled in — you never edit anything by hand.

1. Open your Google Form, then the three-dot menu (⋮) → Script editor.
2. Paste the entire generated script and save it.
3. Open Triggers (the clock icon) and add a trigger: function `onWaDeskFormSubmit`, event source From form, type On form submit.
4. Save and grant the permissions Google asks for.

From then on, each submission sends the answers securely to WaDesk, which finds the paused flow and continues it down its “submitted” path, with the answers available as flow variables.

## Google Sheets Add-on (manage your shop from a Sheet)

Separate from the Sheets flow node above, WaDesk also ships a Google Sheets add-on that lets you build and manage your WhatsApp storefront straight from a spreadsheet — one row per product. Find it under More → Integrations → Sheets Add-on.

> No address to set here. Unlike the browser extension, you never enter a server address for the Sheets add-on. The script WaDesk gives you already points at your install and signs in with a personal API key — so the only thing you paste in is that key.

### Step 1 — Generate your Sheets API key

On the Sheets Add-on page click Generate API key. You get a key (it looks like `wsn_live_…`), shown only once — copy it right away. The server only keeps a scrambled version (with the last few characters for display), so it can never be read back. You can revoke or regenerate it from the same page anytime, which instantly cancels the old key.

### Step 2 — Install the add-on script

Two routes, both offered on the page:

- Marketplace — install the add-on from the Google Workspace Marketplace in one click (if you publish it there).
- Manual — create a new Apps Script project at script.google.com and copy in the files WaDesk provides (`Code.gs`, `appsscript.json`, and a few HTML files). The page has a Download button and step-by-step paste-in instructions. Save and grant the permissions Google asks for.

### Step 3 — Use it in a Sheet

1. Open any Google Sheet, then Extensions → [Your app] WhatsApp Shop → Open.
2. Paste your API key into the add-on's Settings sidebar.
3. The sidebar lists your existing shops and lets you create a new shop from the sheet's rows — one product per row (title, price, image, and so on).

> White-label note: the add-on's menu name and the script WaDesk gives you both pick up your platform's app name automatically — so when you rename WaDesk in admin settings, the Sheet add-on follows along with no edits to the script.

## Disconnecting

Use the Disconnect button on the Google account page to remove the connection. You'll be asked to confirm, because disconnecting stops the Book Appointment and Google Meet nodes and hides the inbox Send Meet button until you reconnect. Your flows and their node settings are kept — only the live connection is removed.

## Troubleshooting

Symptom | Cause | Fix
--- | --- | ---
redirect_uri_mismatch on the Google consent screen | The redirect URI registered in Cloud Console doesn't match the one WaDesk sends. | In Cloud Console → Credentials → your OAuth client, set Authorized redirect URIs to exactly `https://YOUR-DOMAIN/appointments/oauth/google/callback` — same protocol, host, and path, no trailing slash. If the admin set a custom Redirect URI override in WaDesk, register that instead.
Admin setup needed banner / Connect button disabled | The platform OAuth client isn't set up, or the feature is off. | An administrator pastes the Client ID and Secret under Admin → Settings → Integrations → Google and turns Enable on.
A flow node fails with "missing scope" / "insufficient permission" | The connection predates that node, so the scope was never granted. | Click Reconnect on the Google account page to re-run OAuth with the full scope set (the page tells you which scopes are missing).
Connection works but a Sheets/Docs/Forms call errors despite the scope | The matching Google API isn't enabled on the Cloud project. | Admin enables Calendar, Sheets, Docs, Drive, and Forms APIs in APIs & Services → Library (see step 2).
Auto-renew shows as missing on the stat row; the connection drops after about an hour | Google only enables background renewal when you go through the full consent screen; a quick re-sign-in that skips it doesn't. | Click Disconnect, then Connect again so Google shows the consent screen and enables auto-renew.
"access blocked: app not verified" or only test users can connect | The OAuth consent screen is still in Testing. | Add the operator's Google account as a Test user, or publish the consent screen to production.