Skip to main content

Local Intelligence & 360° Omnichannel Marketing API Specification

This document details the REST API routes and FastMCP tools for Google Business Profile (GBP), Google Maps local rank tracking, customer review management, and WhatsApp Cloud API notification dispatches.

1. Google Business Profile & Local Intelligence API Routes​

GET /api/gbp/audit​

Returns tenant's aggregate 0–100 local health audit score, review count, average star rating, and verification status.

Headers: x-tenant-id (optional fallback if session cookie is absent)

Response:

{
  "tenantId": "c0a80101-0000-0000-0000-000000000001",
  "auditScore": 88,
  "totalReviews": 142,
  "averageRating": "4.9",
  "totalPosts": 12,
  "verificationStatus": "VERIFIED",
  "lastSyncedAt": "2026-08-25T16:30:00.000Z"
}

GET /api/gbp/competitors​

Returns Google Maps local 3-pack competitor ranking matrix.

Response:

{
  "tenantId": "...",
  "competitors": [
    { "name": "Target Business (You)", "localRank": 1, "averageRating": 4.9, "reviewCount": 142 },
    { "name": "Competitor A", "localRank": 2, "averageRating": 4.7, "reviewCount": 98 }
  ]
}

GET /api/gbp/reviews​

Lists synced GBP customer reviews ordered by publication timestamp.

GET /api/gbp/reviews/draft?reviewId=[id]​

Generates an AI-drafted, SEO-optimized response tailored to customer star rating.

POST /api/gbp/reviews/[id]/reply​

Publishes review response and automatically tags 4–5 star reviewers with the advocate tag in the CRM contacts table.

Body:

{
  "replyText": "Thank you for your 5-star review!"
}

GET|POST /api/gbp/posts​

Lists and schedules new Google Business Profile updates (STANDARD, EVENT, OFFER, PRODUCT).

2. WhatsApp Intelligence & Notification Routes​

GET|PATCH /api/notifications/whatsapp/settings​

Configures WhatsApp phone number registration and trigger preferences.

POST /api/notifications/whatsapp/test​

Dispatches a test alert via Meta WhatsApp Cloud API.

3. FastMCP Tool Definitions (apps/ai-service/app/mcp_server/tools/local_intelligence.py)​

  • get_gbp_audit(tenant_id)
  • respond_to_review(tenant_id, review_id, reply_text)
  • schedule_gbp_post(tenant_id, summary, topic_type, action_url)
  • get_competitor_ranks(tenant_id, target_keyword)
  • send_whatsapp_report(tenant_id, phone_number)