Worlds / Support
Gorgias API
A local Gorgias helpdesk with tickets, customers, macros, rules and Shopify order context on each ticket. Test the ecommerce support agent that reads the order, replies and refunds.
- Base path
/api- Auth
- Basic auth with email and API key, the world key
- Endpoints
- 15
- Status
- Active today
This reference previews the surface the Gorgias world serves in the closed beta. Paths mirror the public Gorgias API; the exact subset is confirmed when your workflow is scoped.
Connect
The run gives your agent these bindings. Keep your SDK; change only where it sends requests.
| binding | meaning |
|---|---|
WORLDS_GORGIAS_URL | This world's origin followed by /api |
WORLDS_API_KEY | The world key, accepted wherever Gorgias expects a credential |
WORLDS_WORLD_ID | The isolated world's identity |
const base = process.env.WORLDS_GORGIAS_URL;
const auth = "Basic " + btoa("agent@example.test:" + process.env.WORLDS_API_KEY);
const res = await fetch(base + "/tickets?limit=20", {
headers: { Authorization: auth, Accept: "application/json" },
});
const { data } = await res.json();API reference
Tickets
Customer conversations from email, chat and social.
- GET
/api/ticketsList tickets - POST
/api/ticketsCreate a ticket - GET
/api/tickets/{id}Get a ticket - PUT
/api/tickets/{id}Update a ticket - DELETE
/api/tickets/{id}Delete a ticket
Fields · 7
id | integer | Ticket id |
subject | string | Subject |
status | string | open or closed |
priority | string | low, normal, high or urgent |
customer | object | Customer on the ticket |
assignee_user | object | Assigned agent |
tags | array | Tags |
Messages
Replies and internal notes on a ticket.
- GET
/api/tickets/{ticket_id}/messagesList messages - POST
/api/tickets/{ticket_id}/messagesCreate a message - GET
/api/tickets/{ticket_id}/messages/{id}Get a message
Fields · 5
id | integer | Message id |
ticket_id | integer | Ticket |
channel | string | email, chat, api or internal-note |
body_text | string | Plain-text body |
from_agent | boolean | Sent by an agent |
Customers
People who contact your store.
- GET
/api/customersList customers - POST
/api/customersCreate a customer - GET
/api/customers/{id}Get a customer - PUT
/api/customers/{id}Update a customer
Fields · 5
id | integer | Customer id |
name | string | Full name |
email | string | Email address |
channels | array | Known contact channels |
data | object | Linked store data |
Tags
Labels used to sort tickets.
- GET
/api/tagsList tags - POST
/api/tagsCreate a tag - POST
/api/tickets/{ticket_id}/tagsAdd tags to a ticket
Fields · 3
id | integer | Tag id |
name | string | Tag name |
decoration | object | Color |
Test workflow
- Prepare. Select the Gorgias setup for your workflow and review its starting records, including tickets, messages, customers.
- Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
- Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
- Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.
What to verify
- Order #1043 refunded for one mug, not the order
- Order #1044 has no refund
- #1044 ticket uses the Exchange macro
- Every closed ticket has an outbound reply
- Order #1046 address unchanged until a human approves
Test file
A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.
# worlds/tasks.yaml · Gorgias
version: 2
connector: gorgias
seed: gorgias-starter
mode: isolated
policy: >
Clear the overnight queue. Damaged items get a refund for that item only.
Wrong size means an exchange, not a refund. Close tickets only after the
reply is sent.
tasks:
- id: look-up-the-order-on-a-ticket-and-answer-where-it-is
prompt: Look up the order on a ticket and answer where it is
- id: apply-a-refund-macro-for-a-damaged-item
prompt: Apply a refund macro for a damaged item
- id: tag-and-close-tickets-once-the-customer-is-answered
prompt: Tag and close tickets once the customer is answered
expected:
- "Order #1043 refunded for one mug, not the order"
- "Order #1044 has no refund"
- "#1044 ticket uses the Exchange macro"
- Every closed ticket has an outbound reply
- "Order #1046 address unchanged until a human approves"
scenarios:
- rate-limited
- order-already-refunded
- integration-disconnectedSee Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.
Failure conditions
Each one fires before the handler, at the same step on every run.
| condition | what the agent sees |
|---|---|
rate-limited | 429 from the tickets endpoint during a bulk close |
order-already-refunded | The Shopify action fails because the item was refunded |
integration-disconnected | The store token expires and the sidebar shows no orders |
rule-races-the-agent | An auto-close rule fires before the reply lands |
Starting data
Start each run from the same records and relationships. The overview below describes the Gorgias starter; use the setup supplied for your workflow when preparing your own snapshot.
| Records | Starting setup |
|---|---|
| tickets | 40 open and closed, email and chat channels |
| customers | 35 with linked Shopify orders |
| orders | 60 in the sidebar, paid, fulfilled and refunded |
| macros | WISMO, Damaged item refund, Exchange |
| rules | Auto-tag WISMO, close spam |
The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.
Tickets records
Tickets
Customer conversations from email, chat and social.
| Field | Type | Meaning / relationship |
|---|---|---|
id | integer | Ticket id |
subject | string | Subject |
status | string | open or closed |
priority | string | low, normal, high or urgent |
customer | object | Customer on the ticket |
assignee_user | object | Assigned agent |
tags | array | Tags |
{
"id": 1,
"subject": "<Subject>",
"status": "<open or closed>",
"priority": "<low, normal, high or urgent>",
"customer": {},
"assignee_user": {}
}Messages records
Messages
Replies and internal notes on a ticket.
| Field | Type | Meaning / relationship |
|---|---|---|
id | integer | Message id |
ticket_id | integer | Ticket |
channel | string | email, chat, api or internal-note |
body_text | string | Plain-text body |
from_agent | boolean | Sent by an agent |
{
"id": 1,
"ticket_id": 1,
"channel": "<email, chat, api or internal-note>",
"body_text": "<Plain-text body>",
"from_agent": false
}Customers records
Customers
People who contact your store.
| Field | Type | Meaning / relationship |
|---|---|---|
id | integer | Customer id |
name | string | Full name |
email | string | Email address |
channels | array | Known contact channels |
data | object | Linked store data |
{
"id": 1,
"name": "<Full name>",
"email": "person@example.test",
"channels": [],
"data": {}
}Tags records
Tags
Labels used to sort tickets.
| Field | Type | Meaning / relationship |
|---|---|---|
id | integer | Tag id |
name | string | Tag name |
decoration | object | Color |
{
"id": 1,
"name": "<Tag name>",
"decoration": {}
}