Helpin
Dark mode
Connect Google (Gmail & Calendar) on a self-hosted server

Connect Google (Gmail & Calendar) on a self-hosted server

Self-hosted Helpin includes the Google integration — Gmail sync, sending CRM email, and Google Calendar meetings in Meetings — but it ships with no shared Google credentials. Each server supplies its own Google OAuth client, so you (the server admin) create one OAuth app in Google Cloud and point Helpin at it.

This page covers the server-side setup. For what the integration does for end users, see Gmail and Google Calendar integration.

What you need

  • Admin access to the server's environment (or the helpin CLI).

  • A Google Cloud project where you can enable APIs and create an OAuth client.

  • A public https APP_BASE_URL. Google accepts a plain http redirect only for localhost, so any server reached by another hostname must be https.

  • CRM_ENCRYPTION_KEY set: OAuth tokens are encrypted with it.

What you configure

Setting

Required

Purpose

GMAIL_CLIENT_ID

Yes

OAuth client ID of your Google Cloud OAuth client

GMAIL_CLIENT_SECRET

Yes

OAuth client secret

GMAIL_OAUTH_REDIRECT_URL

Optional

Leave empty to use <APP_BASE_URL>/api/crm/email/oauth/callback

CRM_ENCRYPTION_KEY

Yes

Encrypts stored Google tokens

The redirect URI is fixed: <APP_BASE_URL>/api/crm/email/oauth/callback. Leaving GMAIL_OAUTH_REDIRECT_URL empty is recommended — the server derives it from APP_BASE_URL, so it stays correct if the domain changes. If you set it explicitly, it must match APP_BASE_URL plus that callback path exactly, or the server reports a configuration problem and the Connect Google buttons stay disabled.

Step 1 — Create the Google OAuth client

  1. Open the Google Cloud console credentials page.

  2. Select (or create) your project, then enable the Gmail API and the Google Calendar API.

  3. Configure the OAuth consent screen. Helpin requests these scopes:

    • gmail.readonly — import email conversations into CRM

    • gmail.send — send and reply to CRM email

    • calendar.readonly — show upcoming meetings in CRM

    • plus offline access, so it can keep syncing in the background

  4. Create an OAuth client ID of type Web application.

  5. Add the authorized redirect URI: https://<your-APP_BASE_URL>/api/crm/email/oauth/callback

  6. Copy the generated client ID and client secret.

While the consent screen is unverified, only the test users you add to it can connect an account. Add each person's Google address, or complete Google's verification, before rolling it out.

Step 2 — Set the credentials on the server

Either edit the environment directly:

GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_OAUTH_REDIRECT_URL=

Or let the CLI write them. The client secret can come from a file or the HELPIN_GOOGLE_CLIENT_SECRET environment variable rather than an argument:

helpin configure --yes \
  --google-client-id "your-client-id.apps.googleusercontent.com" \
  --google-client-secret-file /run/secrets/google-client-secret

A previously stored key or secret is kept when you don't supply a new one. Then restart the server:

helpin restart

Step 3 — Verify the setup

  • Settings → System status shows a google_workspace capability:

    • needs setup — the client is missing, or the redirect address isn't APP_BASE_URL plus the callback path (or Google would refuse it).

    • unable to verify — the configuration is present but nobody has connected an account yet.

    • ready — at least one account has connected.

  • helpin doctor reports the same state.

  • While it still needs setup, Connect Google buttons are disabled with an explanation.

Once ready, members connect their own Google accounts in Settings → Email & calendar (or from Meetings). Each connection is per person — there is no shared mailbox.

Google Calendar events appear in Meetings through the Google connection above. Separately, meeting capture (recording/transcribing calls) uses its own provider — Recall or Vexa — with its own keys, webhook secret, and a public https APP_BASE_URL. Configure that with helpin configure --meeting-provider ...; it is not part of the Google OAuth client.

Troubleshooting

Symptom

Likely cause

google_workspace shows needs setup despite credentials

GMAIL_OAUTH_REDIRECT_URL set but not equal to <APP_BASE_URL>/api/crm/email/oauth/callback

Connect Google disabled

Redirect URI or client missing; check Settings → System status

Google refuses the redirect

APP_BASE_URL is plain http on a non-localhost host, or the URI isn't registered on the OAuth client

Only some people can connect

Consent screen is unverified — add them as test users or complete verification

Login returns to Helpin but nothing syncs

Recheck enabled Gmail/Calendar APIs and the granted scopes

Was this article helpful?