> ## Documentation Index
> Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Business

Kavenio supports Google Business Profile as a first-class connected account for
location posts, media, reviews, menu and service management, place actions,
verification, and performance analytics.

Google Business uses the same composable Kavenio API shape as other platforms:
connect the account once, select a location, then use shared posts, media,
accounts, inbox, and analytics endpoints.

## Capabilities

| Capability                                    | Endpoint family                                            |
| --------------------------------------------- | ---------------------------------------------------------- |
| OAuth connection                              | `POST /v1/connect/begin` with `platform: "googlebusiness"` |
| Location discovery and selection              | `/v1/connect/googlebusiness/*`                             |
| Post creation and scheduling                  | `POST /v1/posts` with a `googlebusiness` target            |
| Media upload and validation                   | `/v1/media/*` and `POST /v1/tools/validate/media`          |
| Location details, attributes, services, menus | `/v1/accounts/:accountId/gmb-*`                            |
| Reviews and replies                           | `/v1/accounts/:accountId/gmb-reviews*`                     |
| Cross-account review inbox                    | `GET /v1/inbox/reviews?platform=googlebusiness`            |
| Verification                                  | `/v1/accounts/:accountId/gmb-verifications*`               |
| Photos                                        | `/v1/accounts/:accountId/gmb-media`                        |
| Booking and ordering links                    | `/v1/accounts/:accountId/gmb-place-actions`                |
| Performance metrics                           | `GET /v1/analytics/googlebusiness/performance`             |
| Search keywords                               | `GET /v1/analytics/googlebusiness/search-keywords`         |

## Connection

Start with the hosted OAuth flow:

```bash theme={null}
kavenio connect begin \
  --profile-id customer_user_123 \
  --platform googlebusiness \
  --return-to https://app.example.com/accounts
```

Google Business requires a Google Cloud OAuth client, approved Business Profile
API access, and the `https://www.googleapis.com/auth/business.manage` scope.
Kavenio requests offline access so credentials can be refreshed by the shared
credential refresh worker.

After OAuth, list and select the location that Kavenio should manage:

```bash theme={null}
kavenio connect googlebusiness-locations \
  --account-id acc_123 \
  --page-size 25
```

```bash theme={null}
kavenio connect googlebusiness-select-location \
  --account-id acc_123 \
  --profile-id customer_user_123 \
  --location-id 9281089117903930794
```

If there is exactly one manageable location, Kavenio may select it
automatically. Otherwise the account remains connected but needs setup until a
location is selected.

## Posts

Use the normal posts API. Google Business-specific fields live in the target
`platformSpecificData` object.

```json theme={null}
{
  "profileId": "customer_user_123",
  "content": "Weekend tasting flight starts Friday.",
  "platforms": [
    {
      "platform": "googlebusiness",
      "accountId": "acc_123",
      "platformSpecificData": {
        "topicType": "STANDARD",
        "callToAction": "LEARN_MORE",
        "ctaUrl": "https://example.com/weekend"
      }
    }
  ],
  "publishNow": true
}
```

```bash theme={null}
kavenio posts create \
  --profile-id customer_user_123 \
  --content "Weekend tasting flight starts Friday." \
  --publish-now \
  --platform googlebusiness:acc_123 \
  --topic-type STANDARD \
  --call-to-action LEARN_MORE \
  --cta-url https://example.com/weekend
```

Scheduled posts use the existing Kavenio scheduling worker. Provider publish
failures mark the target failed without retrying blindly after a provider
success.

## Media

Upload or presign media with the shared media endpoints, then use the public URL
in a post or photo-management request. Google Business image posts accept one
JPEG or PNG image and no videos.

```bash theme={null}
kavenio media presign \
  --file-name storefront.jpg \
  --content-type image/jpeg
```

```bash theme={null}
kavenio accounts gmb-media-create \
  --account-id acc_123 \
  --source-url https://cdn.example.com/storefront.jpg \
  --category EXTERIOR
```

Kavenio validates public media URLs with SSRF-safe checks before provider calls.

## Management

Use account-scoped routes for location management. The routes use Kavenio
account IDs and optional Google location IDs, not raw credential data.

```bash theme={null}
kavenio accounts gmb-location-details --account-id acc_123
kavenio accounts gmb-attributes --account-id acc_123
kavenio accounts gmb-services --account-id acc_123
kavenio accounts gmb-food-menus --account-id acc_123
kavenio accounts gmb-place-actions --account-id acc_123
```

Writes require JSON payload files:

```bash theme={null}
kavenio accounts gmb-services-replace \
  --account-id acc_123 \
  --file services.json
```

## Reviews

For one Google Business account:

```bash theme={null}
kavenio accounts gmb-reviews --account-id acc_123 --page-size 25
```

Reply to a review:

```bash theme={null}
kavenio accounts gmb-review-reply \
  --account-id acc_123 \
  --review-id review_123 \
  --comment "Thanks for visiting."
```

For a shared inbox across accounts:

```bash theme={null}
kavenio accounts inbox-reviews \
  --platform googlebusiness \
  --min-rating 4 \
  --limit 25
```

The initial inbox implementation reads live with bounded fan-out and reports
partial account failures where supported.

## Verification

Check status, fetch options, start verification, and complete pending
verification through account routes:

```bash theme={null}
kavenio accounts gmb-verifications --account-id acc_123
kavenio accounts gmb-verification-options --account-id acc_123 --language-code en-US
kavenio accounts gmb-verification-start --account-id acc_123 --method SMS --phone-number +15551234567
kavenio accounts gmb-verification-complete --account-id acc_123 --verification-id verification_123 --pin 12345
```

Verification start is a live provider action and is not idempotent.

## Analytics

Performance metrics are daily. Search keywords are monthly and Google may return
thresholds instead of exact impression counts for privacy. Keyword rows use
`valueType: "exact"` with `impressions`, or `valueType: "threshold"` with
`threshold`.

```bash theme={null}
kavenio analytics googlebusiness-performance \
  --account-id acc_123 \
  --metrics WEBSITE_CLICKS,CALL_CLICKS \
  --start-date 2026-06-01 \
  --end-date 2026-06-07
```

```bash theme={null}
kavenio analytics googlebusiness-search-keywords \
  --account-id acc_123 \
  --start-month 2026-05 \
  --end-month 2026-06
```

The first implementation reads Google live. Add caching only when dashboards or
agents need frequent repeated reads.

## Live verification checklist

Live testing requires:

* Google Cloud OAuth client configured for the Kavenio callback URL.
* Approved Google Business Profile API access.
* Enabled Business Profile APIs, including Performance.
* A verified test business location.
* Permissions for posts, media, reviews, location management, menus, services,
  attributes, verification, place actions, and analytics.
* `GOOGLE_BUSINESS_CLIENT_ID` and `GOOGLE_BUSINESS_CLIENT_SECRET` configured in
  the API environment.

Local tests use injectable Google API base URLs and do not call live Google
Business APIs.