From ad27afbb1a46f5b8e7ed109c1fb177358940e42f Mon Sep 17 00:00:00 2001 From: sangeeta1911 Date: Fri, 16 Oct 2026 17:37:20 +0530 Subject: [PATCH 1/2] docs: explain why GCS is needed and each settings field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Why does Glific need GCS?" section covering the concrete features that depend on it (media uploads, AI voice replies, BigQuery reporting, chat media backup), grounded in the actual provider field schema from glific/glific (priv/repo/seeds/..._alter_glific_data.exs). Also fixes the Integrate GCS/BigQuery/Google Sheets sections, which previously instructed pasting both the JSON key and a "client email" into the same single Goth Credentials field — there is only one such field per integration, and it takes the full JSON. Replaces this with a field table per integration (what to enter, why it's needed) and a note on sharing Sheets with the service account's client_email. Closes #682 --- .../05. Google Cloud Storage Setup - GCS.md | 65 ++++++++++++++----- 1 file changed, 50 insertions(+), 15 deletions(-) diff --git a/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md b/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md index 45d7a4e03..16575fa2c 100644 --- a/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md +++ b/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md @@ -2,9 +2,9 @@

- + - +
10 minutes read12 minutes read Level: BeginnerLast Updated: June 2025Last Updated: October 2026

@@ -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 @@ -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 @@ -266,25 +278,48 @@ The JSON key is what authenticates Glific to access your data. ### 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? From e1e9239a84de6d594da0322f1b4d97c85ff76dca Mon Sep 17 00:00:00 2001 From: sangeeta1911 Date: Fri, 16 Oct 2026 18:26:14 +0530 Subject: [PATCH 2/2] docs: explain bucket and service account setup choices in GCS guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Grounded in the actual screenshots already in the doc: - Bucket creation: explains bucket name uniqueness, location/location type tradeoffs, why Standard storage class fits chat media (vs Nearline/Coldline/Archive), and Uniform vs Fine-grained access control. Flags that Public access prevention must be Off, since the doc's own later "Making bucket Public" step (granting allUsers) fails otherwise — visible as "Public access prevention: On" in the existing create-bucket screenshot. - Service account: explains why a service account (non-human identity) is needed instead of a personal login, why Owner role is granted (same account/key is reused across GCS, BigQuery, and Sheets), and why a JSON key specifically (Glific runs outside GCP and needs a portable credential) plus how to react if the key leaks. --- .../05. Google Cloud Storage Setup - GCS.md | 24 +++++++++++++++---- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md b/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md index 16575fa2c..81482d3d9 100644 --- a/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md +++ b/docs/2. Pre Onboarding/05. Google Cloud Storage Setup - GCS.md @@ -204,17 +204,23 @@ The account dashboard shows the credited USD 300 trial funds. Screenshot 2024-12-18 at 2 24 31 PM -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. @@ -244,6 +250,7 @@ ___ ### 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 @@ -251,11 +258,17 @@ ___ 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 (`@.iam.gserviceaccount.com`). You generally don't need to change it. +- **Service account description**: optional, for your own reference. + image 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. + image image @@ -266,14 +279,15 @@ ___ 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. + image image 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