SmsPort Docs / WhatsApp

Docs/
WhatsApp/
Bot Builder/
Integrations/
Google Sheets

Bot Builder / Integrations

Google Sheets integration

Connect Google Sheets once, test the credential, then reuse it in Visual Bot Builder google_sheets nodes.

Current Implementation

  • Provider key is google_sheets.
  • Recommended mode is OAuth2; Apps Script web_app remains as fallback.
  • OAuth callback is /api/integrations/oauth/google/callback.
  • OAuth popup posts smsport_google_sheets_oauth back to SmsPort and tries to close automatically.
  • Visual Builder uses the saved credential through the google_sheets node.

Google Cloud Setup

  1. Create or select a Google Cloud project.
  2. Enable Google Sheets API.
  3. Enable Google Drive API only if SmsPort later adds spreadsheet picker/list/search from Google Drive.
  4. Configure OAuth consent screen and add test users while the app is in Testing mode.
  5. Create an OAuth client with application type Web application.
  6. Add the SmsPort OAuth Redirect URL as an Authorized redirect URI. It must match exactly.

Callback URL Shape

text
Local:
http://localhost:3005/api/integrations/oauth/google/callback

Production:
https://<api-domain>/api/integrations/oauth/google/callback

Production should not show localhost. Use INTEGRATIONS_GOOGLE_OAUTH_CALLBACK_URL as the explicit override when needed.

SmsPort Credential Flow

  1. Open Integrations or the Google Sheets credential modal from Visual Builder.
  2. Set Connection mode to OAuth2 (recommended).
  3. Enter OAuth Client ID and OAuth Client Secret.
  4. Copy OAuth Redirect URL into the Google Cloud OAuth client.
  5. Click Connect Google and complete Google consent.
  6. Click Save. The modal should stay open so the connection can be tested.
  7. Click Test and confirm the status becomes healthy.

Visual Builder Node Fields

  • credentialId: saved Google Sheets connection.
  • operation: for example get_rows.
  • documentId: spreadsheet ID from the Google Sheets URL.
  • sheetName: tab name, such as Leads or Sheet1.
  • lookupVariableKey, keyColumn, resultColumn, and outputVariableKey are used for lookup-style flows.

Required Branches

  • success: Google Sheets operation succeeded.
  • not_found: lookup ran but no matching row was found.
  • error: credential, API, permission, or request failed.

Common Errors

  • access_denied: add the Google account as a test user or publish/verify the app.
  • redirect_uri_mismatch: paste the exact redirect URL shown by SmsPort into Google Cloud.
  • Google Drive API has not been used: current code is calling Drive API and should be changed to use Sheets API for normal tests.
  • Failed to refresh Google OAuth access token: reconnect Google after confirming client ID/secret and APIs.
  • value too long for type character varying(240): fixed by truncating run summaries before writing integration_runs.

Debug Logs

text
google_oauth_start requested
google_oauth_start redirect_resolved
google_oauth_callback received
google_oauth_callback success
connection_test requested
connection_test result

Related:

google_sheets node|Visual builder guide|Bot builder API map