What we do
Tools
Industries
Department
How we workLet's talk →
Home/Gorgias/When the Gorgias API Beats an HTTP Integration
Gorgias

Two Ways Into Gorgias: The REST API and HTTP Integrations

A request lands on your desk: show the loyalty balance in Gorgias tickets, or mark the order reshipped when an agent resolves a ticket. Gorgias gives you two tools for that. The Gorgias API is a REST interface your code calls. HTTP integrations live in the helpdesk settings and let Gorgias call out to someone else's API when a ticket event fires. Plenty of jobs need both, but it's worth knowing which side starts the conversation.

Your code calls Gorgias, or Gorgias calls your code

REST API

Your system starts the request

  • Base URL is your own subdomain: https://{your-domain}.gorgias.com/api/.
  • HTTP Basic auth: your account email as the username and an API key as the password, from Settings, then Account, then REST API.
  • Tickets, customers, messages, tags, teams and users, read and written by your code.
  • Lists page with cursor, limit (30 by default) and order_by; follow meta.next_cursor.
HTTP integration

A ticket event starts the request

  • Set up under Settings, then Account, then HTTP integration, with no app of your own required.
  • Triggers: ticket created, updated, self unsnoozed, message created, message failed, assignment updated and status updated. The last two can't be combined with the others.
  • GET, POST, PUT or DELETE to any URL, with headers or OAuth2 for auth and variables like {{ticket.customer.email}} in the URL or body.
  • Data it fetches can sit in the ticket sidebar as a widget, or feed macros as variables.

If the other system has a usable API and you only need its data in the sidebar, an HTTP integration may be all it takes. If the other system has no API, or the logic needs more than one call, you need a server in the middle, and that's where the REST API comes in.

Ticket events that fire and change nothing

A status trigger lumped in with the others

How you'll know: The integration saves, but the status-change call never goes out.

Fix: Ticket status updated and assignment updated can't share an integration with the other triggers. Give them one of their own.

An endpoint that answers but does nothing

How you'll know: Gorgias logs a successful call and the order still isn't updated.

Fix: The event firing is the easy part. The receiving service needs logging, retries against the downstream system, and a note back on the ticket through the REST API so agents can see it worked.

Every integration on one key

How you'll know: Intermittent 429s, worst when someone runs an export.

Fix: Read X-Gorgias-Account-Api-Call-Limit on each response, pace calls from one queue, and keep bulk jobs to quiet hours.

Settle these before writing the Gorgias integration

  • Will it fit inside 40 requests every 20 seconds?

    That's the API-key limit; OAuth2 apps get 80, and Enterprise accounts get the same counts in a 10-second window. Over it you get a 429 and a Retry-after header. A backfill of old tickets and a live sync sharing one key will collide.

  • Does anything depend on agent or user changes?

    None of the triggers fire on an agent being added, deactivated or edited. You can list users through the API, but staffing changes have to be detected by polling or taken from the HR or scheduling tool you actually manage the team in.

  • Whose credentials does the API key carry?

    Basic auth pairs the key with one user's email. Decide which account owns the integration before go-live, so it isn't tied to whoever happened to set it up.

  • Can the other system answer within the sidebar load?

    An HTTP integration fetching a slow API leaves the agent looking at an empty widget. A small caching endpoint in front of the slow system fixes that.

  • Is this only for your own helpdesk, or for other Gorgias accounts too?

    For your own account, the REST API key is enough. An app that other brands install needs OAuth2 on each account's own subdomain, with scopes.

Questions people ask

Does Gorgias have a public API, and what can it reach?

Yes. It's a REST API on your account's subdomain that reads and writes tickets, customers, messages, tags, teams and users, with HTTP integrations alongside it for calling out when ticket events happen.

What webhook events does Gorgias support through HTTP integrations?

The triggers are ticket created, ticket updated, ticket self unsnoozed, ticket message created, ticket message failed, ticket assignment updated and ticket status updated. Each one can call any URL with the ticket's data in the request.

Can Gorgias's API track agent activity?

Not through events. There's no trigger for agents being created, deactivated or updated. You can read the user list with the API and compare it over time, but coverage and staffing tracking is easier from the system you schedule the team in.

Do I need Gorgias's app marketplace approval to use the API?

Not for your own helpdesk. Create a key under Settings, Account, REST API and use it with your email. Building something other Gorgias accounts install is different: that's an OAuth2 app.

What is the Gorgias API rate limit?

40 requests per 20 seconds for API-key integrations and 80 for OAuth2 apps, measured as a leaky bucket. Enterprise accounts use a 10-second window. Wait the seconds in Retry-after when you get a 429.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.