Skip to content

docs: explain why GCS is needed and each settings field #688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SangeetaMishr wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: explain why GCS is needed and each settings field #688

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad27afb
docs: explain why GCS is needed and each settings field
sangeeta1911 Oct 16, 2026
e1e9239
docs: explain bucket and service account setup choices in GCS guide
sangeeta1911 Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 69 additions & 20 deletions docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
<h3>
<table>
<tr>
<td><b>10 minutes read</b></td>
<td><b>12 minutes read</b></td>
<td style={{ paddingLeft: '40px' }}><b>Level: Beginner</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: June 2025</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: October 2026</b></td>
</tr>
</table>
</h3>
Expand All @@ -20,7 +20,19 @@ ___
___

**Google Cloud Storage (GCS) is a cloud-based service provided by Google Cloud Platform (GCP) that allows you to store and access data—such as files, images, videos, backups, and large datasets—on Google’s secure servers instead of on your local computer or server.**
**Google Cloud Storage (GCS) will be used for various purposes like storing data for reporting via BigQuery as well as for storing media files.**

### Why does Glific need GCS?

GCS isn't optional background storage — several Glific features won't work at all until it's configured:

| Feature | Why it needs GCS |
|---|---|
| Uploading media in HSM Templates and Flows | Without GCS, you can only attach media by pasting a public URL you've hosted elsewhere. Once GCS is configured, an **Upload Attachment** option appears so you can upload the file directly from your computer instead. |
| AI Assistant voice replies (Text-to-Speech) | WhatsApp can only deliver audio as a link, never as raw audio data. Glific saves each generated voice reply to your GCS bucket and sends that link — without GCS, voice replies fail outright. |
| Reporting via BigQuery | BigQuery authenticates using the same Google service account as GCS, so GCS has to be set up before BigQuery reporting can be connected. |
| Backing up chat media | Images, videos, audio, and documents that your contacts send or receive are archived to your bucket, giving you a record outside of WhatsApp. |

If GCS isn't set up: attachments need a public URL instead of a direct upload, voice replies won't send, and BigQuery reporting can't be connected.

### Prerequisites

Expand All @@ -30,7 +42,7 @@ Before starting, make sure you have:

- A valid phone number and payment details for Google Cloud billing.

- Legal documents of your for verification.
- Legal documents for your organisation (for verification).

### Setup

Expand Down Expand Up @@ -192,17 +204,23 @@ The account dashboard shows the credited USD 300 trial funds.
<img width="1462" alt="Screenshot 2024-12-18 at 2 24 31 PM" src="https://github.com/user-attachments/assets/5973b443-e108-448f-bbc2-6411189ee649" />


2. Click on `+CREATE` button to create a bucket to store data

2. Click on `+CREATE` button to create a bucket to store data. This bucket is where Glific will upload and read every media file — chat attachments, voice replies, and anything else covered in [Why does Glific need GCS?](#why-does-glific-need-gcs) above. Without a bucket, there's nowhere for Glific to put that data.

![image](https://user-images.githubusercontent.com/32592458/212659921-587ddafc-1d15-4e8c-849c-3b087c987dec.png)

3. Enter the name of the bucket to be created and the preferred data location where data will be stored
3. Enter the name of the bucket to be created and the preferred data location where data will be stored.

- **Bucket name** must be globally unique across all of GCS (not just your project) — if a name is taken, Google will reject it. You'll re-enter this exact name later in Glific's Google Cloud Storage settings, so make it something recognisable (e.g. your organisation's name).
- **Location**: pick a region close to where your team and contacts are, or one that matches any data-residency requirement your organisation has — this affects latency and, slightly, cost. **Location type**: Region is cheaper and sufficient for most NGOs; Multi-region costs more but keeps your data available even if an entire region goes down — usually unnecessary unless uptime is business-critical.

![image](https://user-images.githubusercontent.com/32592458/212659958-a2f60758-3580-4ebd-a2a6-ecd2d9c9ee97.png)

4. Choose the preferred plan for storage and access control type and click on the `CREATE` button.

- **Storage class**: choose **Standard**. It's priced for data that's accessed frequently and has no retrieval fees — a fit for chat media, which contacts and your team fetch shortly after it's sent. The alternatives (Nearline, Coldline, Archive) are cheaper to store but charge extra every time a file is retrieved, and are meant for backups you rarely touch — the wrong fit for live chat attachments.
- **Access control**: either **Uniform** or **Fine-grained** works for Glific. Uniform is Google's current recommendation and manages all access through project-level permissions (IAM) only; Fine-grained additionally allows per-file permissions, which Glific doesn't need.
- **Public access prevention**: make sure this is set to **Off**. The next section, "Making bucket Public," grants access to `allUsers` so WhatsApp and your contacts can open media links without logging in — if Public access prevention is left **On** (Google's default), that step will fail, since it exists specifically to block exactly that kind of public grant.

![image](https://user-images.githubusercontent.com/32592458/212659975-fa03ee09-ce26-4126-a12d-67533c64f2af.png)

5. A new bucket is created.
Expand Down Expand Up @@ -232,18 +250,25 @@ ___

### Step 5: Create Service Account & Key

A **service account** is a Google Cloud identity meant for an application, not a person — it signs in without anyone typing a password. Glific runs on its own servers outside Google Cloud, so it can't use your personal Google login to access your bucket; it needs this separate, non-human identity instead.

1. Select `IAM & Admin`and then `Service Accounts` from the side panel of Google Cloud Console Dashboard

<img width="478" alt="image" src="https://github.com/user-attachments/assets/a3b8cc7c-caa8-4737-8c9e-04a88bb3ae88" />

2. Click + Create Service Account, enter the details, and click Create and Continue.

- **Service account name**: a display name so you can recognise it later (e.g. "Glific chatbot").
- **Service account ID**: auto-filled from the name — this becomes part of the service account's unique email address (`<id>@<project>.iam.gserviceaccount.com`). You generally don't need to change it.
- **Service account description**: optional, for your own reference.

<img width="765" alt="image" src="https://github.com/user-attachments/assets/d2db4ba3-2066-4128-a878-8749def079dd" />


3. Grant this service account access to the project, ensuring it has Owner access as well. Click Done.

This same service account (and the same JSON key) is reused for Google Cloud Storage, BigQuery, and Google Sheets later in this guide — each of those needs a different permission (Storage Admin, BigQuery Data Editor, Sheets access, etc.). **Owner** covers all of them in one role, so you don't have to assign each one individually.

<img width="765" alt="image" src="https://github.com/user-attachments/assets/b64b0d27-0cd4-4e38-9c4c-c1b4869b9e26" />

<img width="789" alt="image" src="https://github.com/user-attachments/assets/26e5a8ec-250a-4ea4-b74d-8eedfd98a383" />
Expand All @@ -254,37 +279,61 @@ ___

5. Click Add Key, select JSON as the key type, and click Create.

A service account can't type in a login prompt, so it proves its identity with a **key** instead of a password — and because Glific lives outside Google Cloud, that key has to be an exportable file it can carry with it, which is exactly what this JSON file is.

<img width="685" alt="image" src="https://github.com/user-attachments/assets/981bf5e8-025c-4f64-9c66-dbe9cdb29df1" />

<img width="529" alt="image" src="https://github.com/user-attachments/assets/6d190658-b130-45a0-a261-5d7e0dd74e3b" />

6. Save the downloaded JSON file and copy its content.

Please Note - Save this JSON file securely. You will upload it to Glific later.
The JSON key is what authenticates Glific to access your data.
Please note — save this JSON file securely. You will upload it to Glific later. The JSON key is what authenticates Glific to access your data — anyone holding this file can act as this service account with the Owner access granted in Step 3, so treat it like a password: don't share it, don't commit it to a public repository, and if it's ever exposed, delete the key in the Google Cloud Console and generate a new one immediately.


### Integrate Google Cloud Storage with Glific

1. Open the Glific account and click on the NGO main account button (bottom left corner), then go to Settings and
select Google Cloud Storage.
2. Enable the active box, paste the copied JSON file into the Goth Credentials field.
1. Open the Glific account and click on the NGO main account button (bottom left corner), then go to Settings and select Google Cloud Storage.

2. Fill in the fields on this page:

| Field | What to enter | Why it's needed |
|---|---|---|
| **Active?** | Check this box to turn the integration on. | Glific only reads from or writes to GCS when this is enabled. |
| **Goth Credentials** | Paste the entire contents of the service account JSON key file you downloaded earlier in Step 5. | This is what authenticates Glific to your Google Cloud project — without it, Glific can't access your bucket at all. |
| **Bucket** | Enter the bucket name exactly as it appears under Cloud Storage > Buckets in the Google Cloud Console. | Tells Glific which bucket to store and fetch files from. |

3. Click **Save**.

### Integrate BigQuery with Glific

1. Open **BigQuery** from the left panel in Settings.

2. Fill in the fields on this page:

3. Copy the client email from the JSON file and paste it into Goth Credentials.
| Field | What to enter | Why it's needed |
|---|---|---|
| **Active?** | Check this box to turn the integration on. | Enables Glific to run queries and export your data to BigQuery. |
| **BigQuery Url** | Leave this as-is. | It's a fixed Google API endpoint, pre-filled by Glific — not something you configure per organisation. |
| **Goth Credentials** | Paste the same service account JSON content you used for Google Cloud Storage. | BigQuery authenticates with the same service account used for GCS. |

4. Enter the bucket name (you can find it in Google Cloud Console > Cloud Storage > Buckets).
3. Click **Save**.

### Integrate BigQuery API with Glific
### Integrate Google Sheets with Glific

1. Open BigQuery from the left panel in Glific.
1. Open **Google Sheets** from the left panel in Settings.

2. Enable the active box and paste the copied JSON content into the Goth Credentials field. Click Save.
2. Fill in the fields on this page:

### Integrate Google Sheets API with Glific
| Field | What to enter | Why it's needed |
|---|---|---|
| **Active?** | Check this box to turn the integration on. | Enables flows to read from and write to Google Sheets. |
| **Goth Credentials** | Paste the same service account JSON content you used above. | Lets Glific authenticate as this service account when reading or writing a sheet. |

1. Open Google Sheets from the left panel in Glific.
3. Click **Save**.

2. Enable the active box and paste the copied JSON content into the Goth Credentials field. Click Save.
:::note
Share any Google Sheet you want Glific to read or write with the service account's email address (the `client_email` field inside the JSON key file) — otherwise Glific won't have permission to access it, even with valid credentials saved.
:::

### What's the reason for setting the GCS bucket to public?

Expand Down
Loading