JUNOHUB-test/Documents/GMAIL_WEBHOOK_SETUP.md

Gmail Webhook Setup Guide

This guide explains how to set up automatic email detection and AI-powered replies using Gmail push notifications.

Overview

When a customer sends an email to your Gmail account, Gmail will send a push notification to our webhook endpoint. The webhook then:

1. Fetches the incoming email
2. Analyzes it using your store's knowledge base
3. Generates an AI-powered reply
4. Sends the reply automatically

Prerequisites

1. Gmail Integration: Your Gmail account must be connected via /dashboard/juno-engine/gmail-connect
2. Knowledge Base: Your store must have FAQs or documents in the knowledge base
3. Google Cloud Pub/Sub: Required for Gmail push notifications

Step 1: Set Up Google Cloud Pub/Sub

Gmail push notifications require Google Cloud Pub/Sub. Follow these steps:

1.1 Create a Pub/Sub Topic

1. Go to Google Cloud Console
2. Navigate to Pub/Sub > Topics
3. Click Create Topic
4. Name it gmail-notifications (or any name you prefer)
5. Click Create

1.2 Create a Subscription

1. In the topic page, click Create Subscription
2. Name it gmail-webhook-subscription
3. Choose Push delivery type
4. Set the Endpoint URL to: https://yourdomain.com/api/webhooks/gmail
   • Replace yourdomain.com with your actual domain
   • For local development with ngrok: https://your-ngrok-url.ngrok-free.dev/api/webhooks/gmail
5. Click Create

1.3 Grant Gmail API Access

1. Go to IAM & Admin > Service Accounts
2. Find or create a service account for Gmail API
3. Grant it the pubsub.topics.publish permission on your topic

1.4 Get Topic Name

Copy the full topic name in the format:

projects/YOUR_PROJECT_ID/topics/gmail-notifications

Step 2: Configure Environment Variables

Add the Pub/Sub topic name to your .env file:

GMAIL_PUBSUB_TOPIC=projects/YOUR_PROJECT_ID/topics/gmail-notifications

Step 3: Enable Gmail Watch

Once Pub/Sub is set up, enable Gmail push notifications:

Option A: Via API

Make a POST request to:

POST /api/integrations/gmail/watch

This will set up Gmail to send push notifications to your webhook.

Option B: Via UI (Recommended)

Add a button in the Gmail connect page to enable webhooks (coming soon).

Step 4: Verify Webhook

Gmail will send a verification request to your webhook endpoint. The endpoint automatically handles verification by returning the challenge token.

How It Works

Webhook Flow

1. Customer sends email → Gmail receives it
2. Gmail sends push notification → Webhook endpoint receives notification
3. Webhook processes email:
   • Fetches the email content
   • Extracts sender, subject, and body
   • Searches knowledge base for relevant information
   • Generates AI-powered reply using Bedrock
4. Reply is sent → Customer receives automated response
5. Email is marked as read → Prevents duplicate processing

Email Processing Logic

• Only processes emails from external senders (not same domain)
• Uses knowledge base to find relevant answers
• Generates contextual replies using AI
• Maintains email threading (replies are properly threaded)
• Logs all sent emails for tracking

Monitoring

Check logs for:

• Webhook notifications received
• Emails processed
• Replies sent
• Any errors during processing

Troubleshooting

Webhook Not Receiving Notifications

1. Verify Pub/Sub topic exists and is configured correctly
2. Check that Gmail watch is active (watch expires after 7 days)
3. Verify webhook URL is accessible (not behind firewall)
4. Check Google Cloud Console logs for Pub/Sub errors

Replies Not Being Sent

1. Verify Gmail integration is connected
2. Check that store has active knowledge base content
3. Review error logs for specific issues
4. Ensure Bedrock API credentials are configured

Watch Expired

Gmail watch requests expire after 7 days. You need to renew them:

• Call /api/integrations/gmail/watch again
• Or set up a cron job to renew automatically

Security

• Webhook endpoint verifies Gmail notifications
• Only processes emails for authenticated users
• Validates store ownership before processing
• Logs all actions for audit trail

Limitations

• Gmail watch expires after 7 days (needs renewal)
• Only processes unread emails in inbox
• Requires active knowledge base for quality replies
• May have rate limits from Gmail API

Next Steps

• Set up automatic watch renewal (cron job)
• Add email filtering rules (only reply to certain senders)
• Implement reply templates
• Add analytics dashboard for email metrics