# Gorgias Source: https://developers.swell.is/app-guides/gorgias The Gorgias app connects your Swell store to the Gorgias helpdesk. When a Swell customer writes in, the Gorgias ticket sidebar shows their Swell profile and five latest orders, with items, tracking and links to your Swell dashboard. Each customer in Swell gets a Support tab with their open tickets, and the app can create your customers in Gorgias before they write in. ## How it works | When | What the app does | | --- | --- | | You save the connection settings | Within about a minute, checks your API key and creates a Swell integration and sidebar widget in Gorgias. | | A ticket is created or updated in Gorgias | Matches the ticket's customer to a Swell account, sends back their profile and latest orders for the sidebar, and records the ticket on the customer in Swell. | | A customer signs up, changes their contact details or places an order | With customer sync on, creates or updates the customer in Gorgias. | | You turn on customer sync | Imports existing customers who have ordered, newest buyers first, up to the import limit. | | Every hour | Checks the connection again. | ## Before you begin - A Gorgias helpdesk, and an agent with the Admin role in it. The app uses that agent's REST API key, and only admins can create the integration and sidebar widget the app adds. - Customers with the same email in Swell and Gorgias. The app matches tickets to Swell accounts by email, or by Swell ID for customers it synced. ## Set up Install Gorgias from the Swell App Store, and set it up in your test environment before the live one. **1. Copy your API key** In Gorgias, signed in as an admin, go to **Settings > You > REST API** and copy the API key. Note the email you're signed in with, and your subdomain: the `acme` in `acme.gorgias.com`. **2. Add it to the app** In Swell, go to **Apps > Gorgias > Settings**. Under **Gorgias connection**, enter the **Gorgias subdomain**, the **Agent email** and the **API key**, and click **Save settings**. **3. Turn on customer sync** This step is optional. Under **Sync**, turn on **Sync customers to Gorgias**, choose the **Import limit** and save. Existing customers who have ordered are imported, newest buyers first. **4. Test with a ticket** About a minute after you save, email your Gorgias support address from the email of a Swell customer who has placed an order, and open the ticket in Gorgias. The **Swell** card in the sidebar shows the customer and their orders, and the customer's **Support** tab in Swell shows the ticket. If the card doesn't appear, see Troubleshooting below. **5. Go live** Settings are saved separately for each environment. In the live environment, repeat steps 2 and 3. Each environment adds its own Swell integration and widget to Gorgias, so if both connect to the same helpdesk, tickets show a Swell card from each. Use a separate Gorgias account for testing if you can. ## Using Gorgias ### The Swell card in tickets - **Customer:** name, email, number of orders, total spent and the date they became a customer, with a link to their account in your Swell dashboard. - **Orders:** the five latest orders, each with its number, status, date and total, the items with quantity and price, and tracking numbers once it has shipped. Each order links to it in your Swell dashboard. - Tickets from an email that doesn't belong to a Swell account show no Swell data. ### Open tickets in Swell Each customer gets a **Support** tab with **Open tickets**, **Last ticket**, **Last ticket activity** and **View in Gorgias**, which links to the ticket. The customer list gets an **Open tickets** column. The app counts open tickets among the 20 most recent tickets it has heard about for each customer. With **Hear about ticket updates** on, it hears when tickets change, so closed tickets drop out of the count. With it off, it only hears about new tickets, and closed tickets keep counting as open. ### Customer sync With **Sync customers to Gorgias** on, customers are created in Gorgias with their name, email and phone number, linked to their Swell account, and updated when they change their contact details or place an order. The import of existing customers covers those who have ordered, newest buyers first, up to 100, 500 or 1000 customers, and keeps going in the background until it's done. ## Settings Settings are in **Apps > Gorgias > Settings** and are saved separately for each environment. | Setting | Description | Default | | --- | --- | --- | | Gorgias subdomain | The acme in acme.gorgias.com. | None | | Agent email | Email of the Gorgias agent the API key belongs to. The agent needs the Admin role. | None | | API key | The agent's REST API key, from Gorgias Settings > You > REST API. | None | | Sync customers to Gorgias | Creates and updates Gorgias customers from Swell accounts. | Off | | Import limit | The most existing customers to import, newest buyers first: 100, 500 or 1000. Shown when sync is on. | 500 | | Hear about ticket updates | Also tells Swell when a ticket changes, not only when it's created. Keeps open-ticket counts and the sidebar current, at the cost of more traffic. | On | Changing a connection setting or **Hear about ticket updates** updates the existing Swell integration and widget in Gorgias. It doesn't create new ones. ## Limitations - The API key is stored like any other app setting. The settings page masks it, but other installed apps that can read settings can read it. - The sidebar shows the five latest orders. - Ticket history isn't imported. The app counts tickets created or updated after it connected, up to 20 per customer. - Tickets are matched to Swell accounts by email, or by Swell ID for synced customers. - Gorgias allows 40 API requests per 20 seconds. The app paces its requests to stay under that, so a large import takes a while. - The app can't remove what it created in Gorgias when you uninstall it. See Uninstalling below. ## Troubleshooting If the **Swell** card doesn't appear in tickets about a minute after you save, check the app's logs. In the Swell dashboard, they're under **Developer > Console > Logs**. A failed connection is logged as "Gorgias connection failed", followed by the reason. ### The log shows 401 or 403 Gorgias rejected the agent email or API key. The email has to be the one of the agent who owns the API key. Copy the key again from **Settings > You > REST API** in Gorgias, and check the email. ### The log shows 404 Check **Gorgias subdomain**. Enter only the `acme` part of `acme.gorgias.com`. ### The log shows another error from Gorgias Gorgias had a problem. After a failure, the app tries again after 15 minutes, or right away when you change a connection setting. ### The log says the Swell integration is deactivated Gorgias turned the integration off, for example after repeated errors. Reactivate it in Gorgias under **Settings > Integrations > HTTP**. ### The log says this environment has no app public key Gorgias can't reach your store. Uninstall the app and install it again in this environment. ### Nothing is logged and the card doesn't appear Check that **Gorgias subdomain**, **Agent email** and **API key** are all filled in and saved. ### The Swell card shows no customer The ticket's email doesn't belong to a Swell account. Customers synced by the app are also matched by their Swell ID. ### Open ticket counts are too high Turn on **Hear about ticket updates**, so the app hears when tickets are closed. ## Uninstalling Uninstalling the app stops the sidebar data and customer sync, and removes the **Support** tab and the **Open tickets** column. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately. The Swell integration and widget stay in Gorgias, and their calls to your store fail once the app is gone. Delete the Swell integration in Gorgias under **Settings > Integrations > HTTP**. Customers the app created in Gorgias stay there. ## For developers | Function | Runs on | What it does | | --- | --- | --- | | reconcile | Every minute | Connects when the connection settings change, checks the connection every hour and moves the import along. Logs a failure and saves it as the connection's last error. | | gorgias-events | Calls from Gorgias | Matches the ticket's customer, returns the sidebar data and records the ticket on the account. It has to answer within Gorgias's 5-second limit. | | sync-customer | account.created, account.updated, order.submitted | Creates or updates the Gorgias customer when sync is on. Account updates count only when contact details change. | | sync | Calls from the app | Syncs one account, or imports a page of customers and calls itself for the next one. | | connect | A private route | Runs reconcile right away. | The app stores ticket data on accounts under `$app.gorgias`: `open_ticket_count`, `last_ticket_subject`, `last_ticket_at`, `last_ticket_url`, and `tickets`, the 20 most recent tickets. The `connections` collection holds the integration and widget IDs, the last error and the import progress, and no secrets. Gorgias calls the app with a secret in the `X-Swell-Gorgias-Secret` header. The app derives its secrets from the API key with HMAC-SHA256 instead of storing them, so changing the API key or the subdomain replaces them and clearing the connection settings revokes them. To run the connection check without waiting for the next minute: ```sh swell api post /functions/gorgias/connect ``` ## Support Swell builds and maintains the Gorgias app. For help with the app, email support@swell.is. For questions about your Gorgias account, contact Gorgias.