Google Sheets Integration

Overview

The Google Sheets integration allows you to:

Import contacts directly from Google Sheets
Export campaign results back to sheets
Sync contact data bidirectionally
Map spreadsheet columns to contact fields
Update call status in real-time

Prerequisites

A Google account with access to Google Sheets
Google Cloud Platform project with Sheets API enabled
OAuth 2.0 credentials configured

Setup Instructions

Create Google Cloud Project

Go to Google Cloud Console
Click Create Project or select an existing project
Give your project a name (e.g., “TelemanAI Integration”)
Click Create

Enable Google Sheets API

In the Cloud Console, go to APIs & Services → Library
Search for “Google Sheets API”
Click on it and press Enable
Also enable “Google Drive API” for listing spreadsheets

Create OAuth 2.0 Credentials

Go to APIs & Services → Credentials
Click Create Credentials → OAuth client ID
If prompted, configure the OAuth consent screen:
- Choose External user type
- Fill in app name, support email, and developer contact
- Add scopes: https://www.googleapis.com/auth/spreadsheets and https://www.googleapis.com/auth/drive.readonly
For Application type, select Web application

Add authorized redirect URI:

https://your-domain.com/google/callback

Click Create
Copy the Client ID and Client Secret

Keep your Client Secret secure. Do not share it publicly.

Configure Environment Variables

Add the credentials to your .env file:

GOOGLE_CLIENT_ID="519487288503-em802oaj52q01bufcvt8p7akccd8tc1c.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your_actual_client_secret_here"
GOOGLE_REDIRECT_URI="${APP_URL}/google/callback"

The GOOGLE_REDIRECT_URI must match exactly what you configured in Google Cloud Console.

Connect Your Google Account

Log in to TelemanAI
Navigate to Integrations → Google Sheets
Click Connect Google Sheets
Authorize TelemanAI to access your Google Sheets
You’ll be redirected back to TelemanAI after authorization

Importing Contacts from Google Sheets

Select a Spreadsheet

After connecting your Google account:

Click Select Spreadsheet
Choose the spreadsheet containing your contacts
Select the specific sheet/tab within the spreadsheet

Map Columns to Fields

Map your spreadsheet columns to TelemanAI contact fields:

Name: Contact’s full name
Phone: Phone number (required for calling)
Email: Email address (optional)
Custom Fields: Any additional data columns

The first row of your spreadsheet should contain column headers.

Import Contacts

Review the column mappings
Click Import Contacts
TelemanAI will validate and import the data
Duplicate phone numbers are automatically skipped

Exporting Campaign Data

TelemanAI can write campaign results back to your Google Sheets:

Enable Status Column

TelemanAI automatically creates a “Status” column in your sheet if it doesn’t exist. This column will be updated with:

Called: Contact was successfully called
Completed: Call completed successfully
Failed: Call attempt failed
No Answer: Contact didn’t answer
Busy: Line was busy

Configure Campaign for Export

When creating a campaign:

Enable Update Google Sheets
Select the spreadsheet and sheet
Choose the status column to update

Monitor Real-time Updates

As your campaign runs, TelemanAI updates the status column in real-time. You can:

Watch live updates in Google Sheets
Filter contacts by status
Use formulas to calculate success rates

Sheet Format Requirements

For best results, format your Google Sheets as follows:

| Name           | Phone          | Email                | Status    |
|----------------|----------------|----------------------|-----------|
| John Doe       | +1234567890    | [email protected]     | Pending   |
| Jane Smith     | +0987654321    | [email protected]     | Pending   |
| Bob Johnson    | +1122334455    | [email protected]      | Pending   |

Phone numbers should be in E.164 format (e.g., +1234567890)
The first row must contain headers
Avoid empty rows between data
Status column can be anywhere; TelemanAI will find or create it

Advanced Features

Column Header Detection

TelemanAI automatically detects column headers from the first row:

// Example: Get headers from a sheet
GET /api/google/column-headers
{
  "spreadsheet_id": "1abc...",
  "sheet_name": "Contacts"
}

Response:

{
  "headers": ["Name", "Phone", "Email", "Status"]
}

Bidirectional Sync

Update cell values programmatically:

// Update a specific cell
POST /api/google/update-cell
{
  "spreadsheet_id": "1abc...",
  "sheet_name": "Contacts",
  "row_index": 2,
  "column_index": 3,
  "status_value": "Completed"
}

Automatic Status Column Creation

TelemanAI can automatically append a status column if it doesn’t exist:

POST /api/google/ensure-status-column
{
  "spreadsheet_id": "1abc...",
  "sheet_name": "Contacts",
  "column_name": "Call Status"
}

API Endpoints

Key endpoints for Google Sheets integration:

Endpoint	Method	Description
`/google/connect`	GET	Initiate OAuth flow
`/google/callback`	GET	OAuth callback handler
`/google/disconnect`	POST	Disconnect Google Sheets
`/google/spreadsheets`	GET	List all spreadsheets
`/google/spreadsheet/select`	POST	Select a spreadsheet
`/google/sheet/data`	GET	Get all sheet data
`/google/column-headers`	GET	Get column headers
`/google/update-cell`	POST	Update a cell value

See GoogleSheetController.php (lines 24-260) for implementation details.

Troubleshooting

Authentication Failed

Problem: “Google API token not found in session”Solution:

Ensure you’ve completed the OAuth flow
Check that GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct

Clear your session and reconnect:

Session::forget('google_access_token');

Permission Denied

Problem: “Insufficient permissions to access spreadsheet”Solution:

Verify the Google Sheets API is enabled in your GCP project
Check OAuth scopes include:
- https://www.googleapis.com/auth/spreadsheets
- https://www.googleapis.com/auth/drive.readonly
Re-authorize with the “consent” prompt to grant new permissions

Token Expired

Problem: “Could not refresh the Google access token”Solution:

The refresh token is automatically handled by TelemanAI
If issues persist, disconnect and reconnect Google Sheets
Ensure setAccessType('offline') is configured for refresh token

Column Headers Not Found

Problem: “Could not retrieve column headers”Solution:

Ensure the first row of your sheet contains headers
Check that the sheet is not empty
Verify the sheet name is spelled correctly (case-sensitive)
Sheet names with spaces are automatically handled with quotes

Import Fails with Validation Error

Problem: Contacts fail to importSolution:

Verify phone numbers are in valid format
Check for empty rows or cells in required columns
Ensure no duplicate phone numbers exist
Review Laravel logs for specific validation errors

Security Best Practices

Important Security Considerations:

Never commit GOOGLE_CLIENT_SECRET to version control
Use environment variables for all sensitive credentials
Regularly rotate OAuth credentials
Limit API scopes to only what’s necessary
Use HTTPS for all redirect URIs

Token Refresh Mechanism

TelemanAI automatically refreshes expired tokens:

if ($client->isAccessTokenExpired() && $client->getRefreshToken()) {
    $client->fetchAccessTokenWithRefreshToken($client->getRefreshToken());
    Session::put('google_access_token', $client->getAccessToken());
}

See GoogleSheetsService.php (line 39-48) for the implementation.

Next Steps

Import Contacts

Learn more about importing contacts

Create Campaign

Use your imported contacts in a campaign

Export Results

Export campaign results to sheets

API Reference

Full API documentation

Third-Party Services

Payment Gateways

Google Sheets Integration

Overview

Prerequisites

Setup Instructions

Importing Contacts from Google Sheets

Exporting Campaign Data

Sheet Format Requirements

Advanced Features

Column Header Detection

Bidirectional Sync

Automatic Status Column Creation

API Endpoints

Troubleshooting

Security Best Practices

Token Refresh Mechanism

Next Steps

Import Contacts

Create Campaign

Export Results

API Reference

Build docs developers (and LLMs) love

Third-Party Services

Payment Gateways

​Overview

​Prerequisites

​Setup Instructions

​Importing Contacts from Google Sheets

​Exporting Campaign Data

​Sheet Format Requirements

​Advanced Features

​Column Header Detection

​Bidirectional Sync

​Automatic Status Column Creation

​API Endpoints

​Troubleshooting

​Security Best Practices

​Token Refresh Mechanism

​Next Steps

Import Contacts

Create Campaign

Export Results

API Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup Instructions

Importing Contacts from Google Sheets

Exporting Campaign Data

Sheet Format Requirements

Advanced Features

Column Header Detection

Bidirectional Sync

Automatic Status Column Creation

API Endpoints

Troubleshooting

Security Best Practices

Token Refresh Mechanism

Next Steps