Google My Business (Google Business Profile)

scope: https://www.googleapis.com/auth/business.manage

Stored in integrations:
  provider:   'google_my_business'
  api_key:    encrypt(refresh_token)
  metadata:   {
    accountId:         'accounts/123456789',   // GBP Account ID
    locationId:        'accounts/123456789/locations/987654321',  // Location resource name
    locationName:      'Acme Plumbing - Sydney',
    accessToken:       string,
    accessTokenExpiresAt: string,
  }

GOOGLE_CLIENT_ID=xxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

class GoogleMyBusinessTool {
  constructor(
    private locationId:  string,   // Full resource name: 'accounts/.../locations/...'
    private accessToken: string,
    private baseUrl:     string = 'https://mybusiness.googleapis.com/v4',
  ) {}
 
  private headers() {
    return { Authorization: `Bearer ${this.accessToken}` };
  }
 
  async createPost(options: {
    summary:     string;       // Post body text (max 1,500 chars)
    callToAction?: {
      actionType: 'BOOK' | 'ORDER' | 'SHOP' | 'LEARN_MORE' | 'SIGN_UP' | 'CALL';
      url?:       string;      // Required for all except CALL
    };
    mediaUrl?:   string;       // Public image URL
    topicType?:  'STANDARD' | 'EVENT' | 'OFFER';   // Default: STANDARD
    event?: {
      title:     string;
      startDate: string;       // YYYY-MM-DD
      endDate:   string;
    };
    offer?: {
      couponCode?: string;
      redeemUrl?:  string;
      termsConditions?: string;
    };
  }): Promise<{ postName: string; postUrl?: string }> {
    const body: any = {
      languageCode: 'en',
      summary:      options.summary,
      topicType:    options.topicType ?? 'STANDARD',
    };
 
    if (options.callToAction) {
      body.callToAction = {
        actionType: options.callToAction.actionType,
        url:        options.callToAction.url,
      };
    }
 
    if (options.mediaUrl) {
      body.media = [{
        mediaFormat:  'PHOTO',
        sourceUrl:    options.mediaUrl,
      }];
    }
 
    if (options.topicType === 'EVENT' && options.event) {
      body.event = {
        title:    options.event.title,
        schedule: {
          startDate: this.parseDate(options.event.startDate),
          endDate:   this.parseDate(options.event.endDate),
        },
      };
    }
 
    if (options.topicType === 'OFFER' && options.offer) {
      body.offer = options.offer;
    }
 
    const response = await axios.post(
      `${this.baseUrl}/${this.locationId}/localPosts`,
      body,
      { headers: this.headers() },
    );
 
    return {
      postName: response.data.name,
      postUrl:  response.data.searchUrl,
    };
  }
 
  async listReviews(options?: {
    pageSize?: number;
    orderBy?:  'update_time desc' | 'rating desc';
  }): Promise<GBPReview[]> {
    const response = await axios.get(
      `${this.baseUrl}/${this.locationId}/reviews`,
      {
        headers: this.headers(),
        params: {
          pageSize: options?.pageSize ?? 20,
          orderBy:  options?.orderBy ?? 'update_time desc',
        },
      },
    );
    return (response.data.reviews ?? []).map((r: any) => ({
      reviewId:     r.reviewId,
      reviewer:     r.reviewer.displayName,
      starRating:   r.starRating,    // 'ONE' | 'TWO' | 'THREE' | 'FOUR' | 'FIVE'
      comment:      r.comment,
      createTime:   r.createTime,
      updateTime:   r.updateTime,
      reply:        r.reviewReply?.comment ?? null,
    }));
  }
 
  async replyToReview(reviewId: string, reply: string): Promise<void> {
    await axios.put(
      `${this.baseUrl}/${this.locationId}/reviews/${reviewId}/reply`,
      { comment: reply },
      { headers: this.headers() },
    );
  }
 
  async getInsights(options: {
    startDate: string;   // YYYY-MM-DD
    endDate:   string;
    metrics:   string[];
  }): Promise<LocationInsight[]> {
    const response = await axios.post(
      `${this.baseUrl}/${this.locationId}:reportInsights`,
      {
        locationNames: [this.locationId],
        basicRequest: {
          metricRequests:   options.metrics.map(m => ({ metric: m })),
          timeRange: {
            startTime: new Date(options.startDate).toISOString(),
            endTime:   new Date(options.endDate).toISOString(),
          },
        },
      },
      { headers: this.headers() },
    );
    return response.data.locationMetrics ?? [];
  }
 
  async verify(): Promise<void> {
    const response = await axios.get(
      `${this.baseUrl}/${this.locationId}`,
      { headers: this.headers() },
    );
    if (!response.data.name) throw new Error('Google Business Profile location not found');
  }
 
  private parseDate(dateStr: string) {
    const [year, month, day] = dateStr.split('-').map(Number);
    return { year, month, day };
  }
}

Review posted on Google Maps
        │
        ▼ (webhook or polling — GBP has no webhook, polling every 4hrs)
Review saved to reviews table in PostgreSQL
        │
        ▼
Review Response Writer agent generates draft reply
        │
        ▼ (HITL — shown in DM Portal reviews queue)
DM staff approves or edits reply
        │
        ▼
GBP Publisher posts reply via replyToReview()