Skip to content

Integrating GrooveHQ

Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23

Groove is a small-business help-desk built around shared inboxes. The adapter targets Groove’s REST API and exposes conversations, contacts, mailboxes, and agents into the canonical customer-support schema.

  • OAuth 2.0 Authorization Code grant. Authorize at https://api.groovehq.com/oauth/authorize. Exchange via POST to https://api.groovehq.com/oauth/token (application/x-www-form-urlencoded).
  • Access tokens expire after 7200 seconds. Refresh tokens are issued on the same exchange and rotate on refresh.
  1. A Groove account at groovehq.com.
  2. A registered OAuth application in your Groove account. Note the Client ID, Client Secret, and pre-register the exact redirect URI you will use — Groove rejects mismatched redirects at the token exchange.
  1. Open /platforms in the admin UI, filter to Customer Support, click GrooveHQ.
  2. Fill Configure:
    • clientId — from your Groove OAuth app.
    • clientSecret — from your Groove OAuth app.
    • redirectUri — ${PUBLIC_BASE_URL}/auth/customer-support/groove/callback.
  3. Enable the adapter.

Groove does not publish a granular OAuth scope catalog — tokens issued through the standard authorization flow inherit the connecting user’s permissions across the account. If a stricter model is required, fall back to a per-agent personal API token and supply it via the credential form.

Configure webhooks under Settings → Webhooks in your Groove inbox. Groove signs each delivery with HMAC-SHA256 in the X-Groove-Signature header (base64). Subscribe to conversation_*, message_*, and customer_* events.

  • REST API is legacy. Groove now recommends its GraphQL API for new integrations; the REST endpoints (which the adapter currently targets) remain supported but the documentation is no longer actively maintained.
  • Redirect URI must match exactly. Trailing slashes, query parameters, and scheme are all compared verbatim.
  • No sandbox tenant. Test against a free Groove trial account — there is no separate dev environment.