![Ringle](assets/ringle-logo.png)

# Integrations and helpdesk connections

## Purpose
The Connections page links the tenant to its commerce and support systems: OAuth flows for Square and Shopify, and token forms for Redo, Gladly, Gorgias, Toast, Kustomer, Zendesk, Shopmonkey, and Tekmetric. The Helpdesk page is the read-only view of whichever helpdesk is connected: its escalation history, inboxes, and agents.

## Prerequisites
- A tenant role with integrations permission; members without it do not see Connections or Helpdesk in the sidebar.
- Credentials for the provider you are connecting (an OAuth login for Square or Shopify, an API token or key pair for the others). Never paste tokens you do not intend to use.

## Steps

### Step 1

![integrations-and-helpdesk, step-01](screenshots/integrations-and-helpdesk/step-01.png)

**Action:** Click Connections under Account & Access in the sidebar. Scroll through the grid.

**What you should see:** The provider cards appear, followed by a Site FAQ crawling section. Square starts an OAuth flow and then lets you link the resulting merchant connection to the tenant. Shopify takes your store domain and starts Shopify authorization. Redo (API token, store ID, webhook secret), Gladly (organization, username, API token, optional inbox), Gorgias (domain, email, API token, optional team), Toast (restaurant ID, client ID and secret), Kustomer (organization, API token, optional queue), and Zendesk (subdomain, email, API token, optional group) are inline token forms. Shopmonkey (API key) and Tekmetric (client ID, secret, shop ID) connect appointment booking. Every Connect button stays disabled until its required fields are filled. The Site FAQ crawling section at the bottom takes a domain you own and two options (override robots.txt, render JS pages) and lets Ringle gather FAQs from that site for review before they go live.

### Step 2

![integrations-and-helpdesk, step-02](screenshots/integrations-and-helpdesk/step-02.png)

**Action:** Click Start Square OAuth to connect Square. Complete the authorization in the new tab only when you mean to connect. Otherwise close that tab.

**What you should see:** A banner confirms "Square authorization opened in a new tab. After the callback completes, return here and link the merchant connection to this tenant." A second note says Square is running against the sandbox environment, so real merchant accounts cannot connect yet. To finish, return here, pick the merchant in the Available merchant connection dropdown, and click Link selected merchant. For Shopify, enter the store domain first. Start Shopify OAuth enables once a domain is present. (This capture abandoned the authorization without granting anything.)

### Step 3

![integrations-and-helpdesk, step-03](screenshots/integrations-and-helpdesk/step-03.png)

**Action:** Click Helpdesk in the sidebar.

**What you should see:** The Helpdesk page summarizes the connected provider. With none connected, as in the demo tenant, an info banner points you to Integrations to connect Gladly, Gorgias, Kustomer, or Zendesk. Below it, Escalation History lists tickets the assistant has opened (conversation, channel, reason, status, created). The Inboxes and Agents cards list the provider's directory once a helpdesk is connected.

## Troubleshooting
- A Connect button will not enable: every non-optional field on that card is required; optional fields are labeled as such.
- All cards show as disconnected on the demo tenant even though it clearly has POS, OMS, and helpdesk behavior: the demo providers are assigned on the Tenant Profile page, not through these connection flows. This page correctly shows no external connections.
- Square OAuth finished but the tenant still is not linked: the OAuth callback only creates a merchant connection. Return to the Square card, select it under Available merchant connection, and click Link selected merchant.
- The Helpdesk page says no provider is connected: it only recognizes Gladly, Gorgias, Kustomer, and Zendesk connections made on the Connections page. Connect one there first.
- Gladly, Gorgias, Toast, Kustomer, and Zendesk cards also have a Test Connection action once credentials are saved. Use it after connecting to confirm the token works before relying on escalation.

## Notes
- Routes: `/settings/integrations` (sidebar "Connections") and `/settings/helpdesk` (sidebar "Helpdesk") under Account & Access, both gated by the `integrations.manage` permission. Source: `pages/settings/IntegrationsPage.jsx` and `pages/settings/HelpdeskPage.jsx`.
- Square and Shopify use OAuth; the other seven cards are token forms rendered inline on the page (there are no separate dialogs to cancel). Test Connection exists for the Gladly, Gorgias, Toast, Kustomer, and Zendesk cards; Square, Shopify, Redo, Shopmonkey, and Tekmetric do not have one.
- The demo tenant has no external connections, so the connected state (green banner, Disconnect and Test Connection buttons, escalation rows, inbox and agent lists) could not be captured; no disconnects were performed and no tokens were entered.
- The Square authorization page itself is not shown: in this capture environment it opens against a Square sandbox that renders blank without a Square session, so the flow was abandoned at the redirect and the portal-side banner in step 2 documents the moment instead.
- Captures were taken in the Demo Auto Shop tenant, which has no external connections. No tokens were entered and the Square OAuth tab was closed without granting access.