App guides
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.
| When | What the app does |
| You save the connection settings | Within about a minute, checks your API key, creates a Swell integration and sidebar widget in Gorgias, and shows the result under Status. |
| 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 and updates Status. |
- 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.
Install Gorgias from the Swell App Store, and set it up in your test environment before the live one.
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.
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.
Check the connection
After about a minute, reload the page. Status reads "Connected to acme.gorgias.com". If it reads "Could not connect", the message says why; see Troubleshooting below.
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, and Status shows the progress.
Test with a ticket
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.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 to 4. 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.
- 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.
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.
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 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 |
| Status | Read-only. Written by the app: whether it's connected, when it last checked and the import progress. | 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.
- The API key is stored like any other app setting. It shows in plain text on the settings page, and 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.
Status shows the last result. The app writes it within about a minute of a save, so reload the settings page to see it.
A connection setting is empty. Fill in all three and click Save settings.
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.
Check Gorgias subdomain. Enter only the acme part of acme.gorgias.com.
Gorgias had a problem. After a failure, the app tries again after 15 minutes, or right away when you change a connection setting.
Gorgias turned the integration off, for example after repeated errors. Reactivate it in Gorgias under Settings > Integrations > HTTP.
Gorgias can't reach your store. Uninstall the app and install it again in this environment.
The ticket's email doesn't belong to a Swell account. Customers synced by the app are also matched by their Swell ID.
Turn on Hear about ticket updates, so the app hears when tickets are closed.
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.
| Function | Runs on | What it does |
| reconcile | Every minute | Connects when the connection settings change, checks the connection every hour, moves the import along and writes Status. |
| 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:
swell api post /functions/gorgias/connectSwell builds and maintains the Gorgias app. For help with the app, email support@swell.is. For questions about your Gorgias account, contact Gorgias.