Skip to content

GOOGLE_SHEETS_SETUP.md

Latest commit

 

History

History
131 lines (98 loc) · 4.42 KB

GOOGLE_SHEETS_SETUP.md

File metadata and controls

131 lines (98 loc) · 4.42 KB
Raw

Google Sheets Integration Setup

This guide will help you set up Google Sheets integration for the Instagram Message Tracker.

Overview

The Google Sheets integration allows you to:

  • Read Instagram usernames directly from a Google Sheet
  • Automatically update the sheet with tracking results (status, timestamp, reply preview)
  • No need to download/upload CSV files manually

Prerequisites

  1. A Google account
  2. The Google Sheet you want to use must have an "instagram" column (case-insensitive)

Step 1: Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Click "Select a project" at the top, then "New Project"
  3. Name your project (e.g., "Instagram Tracker") and click "Create"

Step 2: Enable Google Sheets API

  1. In the Cloud Console, go to "APIs & Services" > "Library"
  2. Search for "Google Sheets API"
  3. Click on it and click "Enable"
  4. Also search for and enable "Google Drive API"

Step 3: Create Service Account Credentials

  1. Go to "APIs & Services" > "Credentials"
  2. Click "Create Credentials" > "Service Account"
  3. Name it (e.g., "instagram-tracker-service")
  4. Click "Create and Continue"
  5. Skip the optional steps and click "Done"

Step 4: Generate and Download Credentials

  1. On the Credentials page, find your service account and click on it
  2. Go to the "Keys" tab
  3. Click "Add Key" > "Create new key"
  4. Choose "JSON" format and click "Create"
  5. A JSON file will be downloaded to your computer

Step 5: Install the Credentials

  1. Rename the downloaded JSON file to google_credentials.json
  2. Move it to the root directory of this project (same folder as app.py)

Important: The file MUST be named exactly google_credentials.json

Step 6: Share Your Google Sheet

  1. Open your Google Sheet
  2. Click the "Share" button in the top right
  3. Open the downloaded google_credentials.json file
  4. Find the client_email field (looks like: xxx@xxx.iam.gserviceaccount.com)
  5. Copy thi s email address
  6. In your Google Sheet, paste this email in the "Add people and groups" field
  7. Give it "Editor" permissions
  8. Click "Send"

Step 7: Prepare Your Google Sheet

Your Google Sheet must have:

  • An "instagram" column (can be "Instagram", "INSTAGRAM", etc. - case doesn't matter)
  • Instagram usernames in any of these formats:
    • username
    • @username
    • https://instagram.com/username
    • instagram.com/username

Example sheet structure:

| Name          | Instagram           | Email               |
|---------------|---------------------|---------------------|
| John Doe      | @johndoe           | john@example.com    |
| Jane Smith    | janesmith          | jane@example.com    |
| Bob Wilson    | instagram.com/bob  | bob@example.com     |

Using Google Sheets Integration

  1. Start the Flask app: python app.py
  2. Go to the dashboard (usually http://localhost:5000)
  3. Select "Google Sheets URL" from the Input Method dropdown
  4. Paste your Google Sheets URL (e.g., https://docs.google.com/spreadsheets/d/abc123.../edit)
  5. Enter your Instagram credentials
  6. Click "Track Messages"

The app will:

  1. Read usernames from your sheet
  2. Track the message status for each username
  3. Automatically add 3 new columns to your sheet:
    • "Tracking Status" (Not Seen / Seen / Replied)
    • "Tracking Timestamp"
    • "Reply Preview"

Troubleshooting

Error: "Google credentials file not found"

  • Make sure google_credentials.json is in the same folder as app.py
  • Check the file name is exactly google_credentials.json (case-sensitive)

Error: "Failed to authenticate with Google Sheets"

  • Verify the JSON file is valid and not corrupted
  • Make sure you enabled both Google Sheets API and Google Drive API

Error: "Permission denied" or "Requested entity was not found"

  • Make sure you shared the sheet with the service account email
  • The email address should be from the client_email field in the JSON file
  • Give it "Editor" permissions

Error: "Sheet must have an instagram column"

  • Add a column with "instagram" in the name (any case)
  • Make sure the column has Instagram usernames in it

Security Notes

  • NEVER commit google_credentials.json to version control (Git)
  • Add it to your .gitignore file
  • Keep the credentials file secure - it provides access to your Google Sheets
  • If compromised, delete the service account and create a new one

Example .gitignore Entry

# Google Sheets credentials
google_credentials.json