Worlds / Support

Help Scout API

A local Help Scout with mailboxes, conversations, threads, saved replies, tags and customer profiles. Test the agent that replies, adds notes and moves conversations to the right status.

Base path: /v2
Auth: OAuth 2.0 bearer token, the world key
Endpoints: 13
Status: Active today

This reference previews the surface the Help Scout world serves in the closed beta. Paths mirror the public Help Scout 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_HELP_SCOUT_URL`	This world's origin followed by `/v2`
`WORLDS_API_KEY`	The world key, accepted wherever Help Scout expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_HELP_SCOUT_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(base + "/conversations?status=active", { headers });
const data = await res.json();

API reference

13 of 13

Conversations

Customer threads in a mailbox.

GET/v2/conversationsList conversations
POST/v2/conversationsCreate a conversation
GET/v2/conversations/{id}Get a conversation
PATCH/v2/conversations/{id}Update a conversation
PUT/v2/conversations/{id}/tagsUpdate tags

Fields · 6

`id`	integer	Conversation id
`subject`	string	Subject
`status`	string	active, pending, closed or spam
`mailboxId`	integer	Mailbox
`assignee`	object	Assigned user
`tags`	array	Tags

Threads

Customer messages, agent replies and notes.

GET/v2/conversations/{id}/threadsList threads
POST/v2/conversations/{id}/replyCreate a reply
POST/v2/conversations/{id}/notesCreate a note

Fields · 4

`id`	integer	Thread id
`type`	string	customer, reply, note and so on
`body`	string	HTML body
`createdBy`	object	Author

Customers

People who write in.

GET/v2/customersList customers
POST/v2/customersCreate a customer
GET/v2/customers/{id}Get a customer

Fields · 5

`id`	integer	Customer id
`firstName`	string	First name
`lastName`	string	Last name
`emails`	array	Email addresses
`organization`	string	Company

Mailboxes

Inboxes that hold conversations.

GET/v2/mailboxesList mailboxes
GET/v2/mailboxes/{id}Get a mailbox

Fields · 4

`id`	integer	Mailbox id
`name`	string	Mailbox name
`email`	string	Address
`slug`	string	URL slug

Test workflow

Prepare. Select the Help Scout setup for your workflow and review its starting records, including conversations, threads, 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

Dana Lee conversation has a reply thread and is pending
Moss & Co conversation in Billing, assigned to Sam, still active
Kim Park conversation closed
No note thread visible to customers
Lee Holdings profiles not merged

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.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Help Scout
version: 2
connector: help-scout
seed: help-scout-starter
mode: isolated
policy: >
  Work the Support mailbox. Password issues get the Reset password saved reply
  and status pending. Refund requests move to Billing, assigned to Sam, with a
  note. Close only when the customer confirms it is fixed.
tasks:
  - id: reply-using-a-saved-reply-and-set-status-pending
    prompt: Reply using a saved reply and set status pending
  - id: add-a-private-note-and-assign-to-a-teammate
    prompt: Add a private note and assign to a teammate
  - id: close-conversations-once-the-customer-confirms
    prompt: Close conversations once the customer confirms
expected:
  - Dana Lee conversation has a reply thread and is pending
  - "Moss & Co conversation in Billing, assigned to Sam, still active"
  - Kim Park conversation closed
  - No note thread visible to customers
  - Lee Holdings profiles not merged
scenarios:
  - rate-limited
  - token-expired
  - workflow-runs

See 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 Mailbox API on the threads endpoint
`token-expired`	The OAuth access token expires after two days and returns 401
`workflow-runs`	An automatic workflow changes the status after the agent's write
`conversation-moved`	404 after the conversation is moved to Billing

Starting data

Start each run from the same records and relationships. The overview below describes the Help Scout starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
mailboxes	Support and Billing
conversations	35 across active, pending and closed
customers	40 profiles, some with two email addresses
saved replies	10, including Refund timeline and Reset password
workflows	2 automatic workflows on tag refund

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.

Conversations records

Conversations

Customer threads in a mailbox.

Field	Type	Meaning / relationship
`id`	integer	Conversation id
`subject`	string	Subject
`status`	string	active, pending, closed or spam
`mailboxId`	integer	Mailbox
`assignee`	object	Assigned user
`tags`	array	Tags

json · illustrative record shape

{
  "id": 1,
  "subject": "<Subject>",
  "status": "<active, pending, closed or spam>",
  "mailboxId": 1,
  "assignee": {},
  "tags": []
}

See conversations operations

Threads records

Threads

Customer messages, agent replies and notes.

Field	Type	Meaning / relationship
`id`	integer	Thread id
`type`	string	customer, reply, note and so on
`body`	string	HTML body
`createdBy`	object	Author

json · illustrative record shape

{
  "id": 1,
  "type": "<customer, reply, note and so on>",
  "body": "<HTML body>",
  "createdBy": {}
}

See threads operations

Customers records

Customers

People who write in.

Field	Type	Meaning / relationship
`id`	integer	Customer id
`firstName`	string	First name
`lastName`	string	Last name
`emails`	array	Email addresses
`organization`	string	Company

json · illustrative record shape

{
  "id": 1,
  "firstName": "<First name>",
  "lastName": "<Last name>",
  "emails": [],
  "organization": "<Company>"
}

See customers operations

Mailboxes records

Mailboxes

Inboxes that hold conversations.

Field	Type	Meaning / relationship
`id`	integer	Mailbox id
`name`	string	Mailbox name
`email`	string	Address
`slug`	string	URL slug

json · illustrative record shape

{
  "id": 1,
  "name": "<Mailbox name>",
  "email": "person@example.test",
  "slug": "<URL slug>"
}

See mailboxes operations

See the Help Scout world in the catalog