Gorgias is a customer support helpdesk built for ecommerce. Once connected, you can use OuterSignal's Playbooks to send persona and signal data into Gorgias, so your support team can see who they're talking to — and act on it — right inside a ticket.
Connecting Gorgias is a two-part process: you connect the account once in Settings, then use it inside a Playbook.
Part 1: Connect your account (one-time setup)
In OuterSignal, go to Settings → Integrations → Gorgias and select Connect.
A window opens asking for three things: your Gorgias API key, the account email it's paired with, and your Gorgias subdomain. Gorgias is a three-field connection, not just an API key — most generic "how do I get my API key" guidance only covers the key itself, so it's worth knowing upfront you'll need the email and subdomain too, or you'll get stuck partway through.
Log in to Gorgias (in a separate tab) and select the Settings icon in the bottom-left corner.
Go to Account → REST API.
Under API Access & Credentials, you'll see:
Password (API Key) — select Create API Key if one doesn't exist yet, then copy it.
Username — this is the account email tied to the key.
Your subdomain — the first part of your Gorgias URL. If you log in at https://yourcompany.gorgias.com, your subdomain is yourcompany.
Back in OuterSignal, enter the API key, the account email (username), and the subdomain into the Gorgias connect window, then select Connect.
The integration card flips to Connected.
You only need to do this once. You won't be asked for these credentials again — every Playbook that uses Gorgias pulls them from here automatically.
Note: an API key in Gorgias is tied to the permission level of the user who created it. If you're setting this up for the long term, consider creating a dedicated Gorgias user for the integration rather than tying it to one person's account — that way the connection doesn't break if that person leaves or loses access.
Part 2: Use it in a Playbook
Every Gorgias Playbook action runs on enter — as soon as a customer enters the segment you picked, the action fires. There are three Gorgias actions to choose from, and each has its own setup. Pick the one below that matches what you're trying to do.
Gorgias matches customers by email, so make sure the customer records you're segmenting on in OuterSignal have a reliable email address — that's what ties the data to the right ticket and customer profile in Gorgias.
Gorgias Customer — update a field on the customer's profile
Use this when you want persona or signal data visible on the customer record itself, so it shows up any time an agent opens that customer — not just on one ticket.
First, create the field in Gorgias (it must already exist — OuterSignal doesn't create new custom fields for you):
In Gorgias, click the Workflows dropdown in the top-left corner.
Under Fields and tags, select Customer fields.
Click Create field.
Enter a Name — this is what you'll reference from OuterSignal, so keep it clear (e.g. Customer Biography).
Add a Description if you'd like (agents won't see this).
Choose a Type — Dropdown, Text, Number, etc. Note: the field type can't be changed once it's saved, so pick carefully. If you choose Dropdown, add the values you want available (use Text for Biography).
Click Create field.
Note: Gorgias allows a maximum of four active customer fields at a time. If you're at that limit, archive an existing field before creating a new one. If a Playbook is already mapped to the field you archive, that Playbook's action will start erroring (something like custom field not found) — worth checking your Playbooks before you archive. That's the opposite failure mode from a bad email match described in the FAQ, which fails silently instead of throwing an error.
Then, set up the action in OuterSignal:
In OuterSignal, go to Playbooks → Create Playbook and pick the segment you want to act on (use All Customers to apply to all OuterSignal Customers).
Select Add an Action, then choose Gorgias Customer.
Under Customer Fields, select + Add Field.
Enter the exact Gorgias field name you created above (e.g. Customer Biography).
From the variable dropdown, choose the OuterSignal value to map into it — options include Biography, Customer Name, Email, Customer Persona, Segment Name, Customer Age, Customer Gender, and any custom profile variables you've set up.
Select + Add Field again to map additional fields, if needed.
Select Add Action → Review & Create → Create Playbook. Note: getting a synced field to actually display in the agent's sidebar in Gorgias is a separate configuration step on the Gorgias side — see above for instructions on adding the customer field.
Gorgias Note — open a follow-up ticket, with an optional title
Notes are visible to agents only; the customer never sees them. Use this to flag context for whoever picks up the next ticket, without cluttering the customer-facing thread.
In OuterSignal, go to Playbooks → Create Playbook and pick the segment you want to act on.
Select Add an Action, then choose Gorgias Note.
Enter a Note title (optional) — a short label, e.g. OuterSignal: {{segment.name}}. If filled in, this becomes the subject line of the ticket it creates in Gorgias — the field is just named differently on each side.
Enter the Note text (required) — this is where most of the useful context goes, e.g. High-value shopper — {{persona}}, {{order_count}} orders. See Using template variables below for what you can drop in here.
Select Add Action → Review & Create → Create Playbook.
Gorgias Ticket — open an internal follow-up ticket
Like notes, these tickets are never customer-visible — they're a way to route a customer into your support team's queue based on their persona or segment, without the customer having reached out first.
In OuterSignal, go to Playbooks → Create Playbook and pick the segment you want to act on.
Select Add an Action, then choose Gorgias Ticket.
Enter the Ticket subject (required) — e.g. Follow up: {{segment.name}}.
Enter the Ticket message (required) — e.g. Reach out to {{first_name}} — {{persona}}, {{order_count}} orders. See Using template variables below for what you can drop in here.
Select Add Action → Review & Create → Create Playbook.
Choosing between the three options
The underlying question is whether a customer should be handled now, or should just have context waiting for later. A custom field is passive — it only helps once an agent happens to open that profile, so it can't start work on its own. A ticket is the only one of the three that puts something in front of an agent who wasn't already looking. So the real choice is: do you want this customer handled, or do you just want context waiting there for whenever they write in?
Put context on the customer: Gorgias Customer — persona or biography sits in the sidebar whenever that customer writes in, and it costs the queue nothing.
Create work in the queue: Gorgias Ticket, or Gorgias Note if you'd rather skip the required subject line. Same mechanism, same use cases — Note is just the version that lands untitled if you leave the title blank.
The strongest use case: proactive outreach. Support reaching out to a customer before they have a problem, using a Gorgias Ticket to route the work:
A customer crosses the VIP threshold. A ticket lands in the queue — "Reach out to {{first_name}} — {{persona}}, {{order_count}} orders, ${{total_spent}} lifetime" — and an agent sends a personal thank-you within seconds of the customer crossing the threshold, something nobody would have known to do otherwise. This maps onto the VIP Customers segment we already ship playbook templates for on the Shopify and Klaviyo side.
A high-value or unusual order comes in. A ticket tells the team to confirm it personally before it ships.
A customer goes quiet or hits an at-risk segment. A ticket gives someone the chance to attempt a save while there's still something to save.
A persona that deserves different handling — a first-time buyer, a gift buyer. A ticket gets a person to put a human touch on the first interaction.
The contrast is Gorgias Customer, which is the right answer when you don't want work created: the agent sees the persona or biography in the sidebar whenever that customer writes in, and it costs the queue nothing. Gorgias's own rules and views can also filter on customer fields, so a field like "VIP" can drive priority and routing inside Gorgias without anyone reading it.
A warning worth stating explicitly: Gorgias actions fire once per customer entering the segment. Pair Gorgias Ticket with a large segment — or with All Customers — and you get one ticket per customer. Ticket is for segments that are small and meaningful, not for broad ones; broad segments belong on Gorgias Customer instead.
Using template variables
Note text, ticket subject/message, and other free-text fields all accept {{...}} template variables — OuterSignal resolves each one per customer profile at the moment the action runs. Available variables include:
{{segment.name}} — the name of the segment that triggered the Playbook
{{persona}} — the customer's persona
{{total_spent}} — lifetime spend
{{order_count}} — total number of orders
{{first_name}} — the customer's first name
You can combine as many of these as you like in a single field — e.g. {{first_name}} — {{persona}}, {{order_count}} orders, ${{total_spent}} lifetime. These five are just a sample — check the variable dropdown in the Playbook builder for the full set. If a variable has no value for a given customer, it simply resolves to blank, so it's worth planning your copy around that.
FAQ
Where do I enter my API key, email, and subdomain? Always in Settings → Integrations → Gorgias — never inside a Playbook. The Playbook builder doesn't have fields for any of these.
How does Gorgias match customers to OuterSignal data? By email address. If the OuterSignal profile has no email, or no Gorgias customer exists with that email, nothing happens at all — no field written, no note, no ticket, and no error anywhere.
What permissions does my API key need? The key inherits whatever permissions the Gorgias user it's tied to has. For a support-data integration like this, an admin-level user is the safest bet.
What's the difference between a Gorgias Note and a Gorgias Ticket? They're the same mechanism: both create a new ticket in your support queue carrying one internal, agent-only message. The only difference is that Ticket requires a subject line, while Note's title is optional — fill in the Note title and you've built the same thing a Ticket builds. The behavior people expect from "Note" (context added with nothing new for an agent to work) actually describes Gorgias Customer, not Gorgias Note.
Can I use more than one Gorgias action in the same Playbook? Yes — you can add multiple Gorgias actions (e.g. a Customer field update and a Note) to the same Playbook if you want several things to happen when a customer enters the segment.
What does a broken connection look like? If the API key, account email, or subdomain stop working, that surfaces as a broken-integration notification — it's not a silent failure the way a bad email match is.