Worlds / Support

Intercom API

A local Intercom workspace with conversations, contacts, companies, teams and tags. Test the agent that replies, assigns, snoozes and closes conversations.

Base path: /
Auth: Bearer access token, the world key
Endpoints: 20
Status: Active today

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

js · intercom-client

import { IntercomClient } from "intercom-client";

const client = new IntercomClient({
  token: process.env.WORLDS_API_KEY,
  environment: process.env.WORLDS_INTERCOM_URL,
});

const contacts = await client.contacts.list();

API reference

20 of 20

Conversations

Message threads between contacts and your team.

GET/conversationsList conversations
GET/conversations/{id}Retrieve a conversation
POST/conversations/{id}/replyReply to a conversation
POST/conversations/{id}/partsClose, snooze or assign
POST/conversations/searchSearch conversations

Fields · 6

`id`	string	Conversation id
`state`	string	open, closed or snoozed
`priority`	string	priority or not_priority
`admin_assignee_id`	integer	Assigned teammate
`source`	object	First message in the thread
`updated_at`	integer	Unix time of last change

Contacts

Users and leads you talk to.

GET/contactsList contacts
POST/contactsCreate a contact
GET/contacts/{id}Retrieve a contact
PUT/contacts/{id}Update a contact
POST/contacts/searchSearch contacts

Fields · 5

`id`	string	Contact id
`role`	string	user or lead
`email`	string	Email address
`name`	string	Full name
`custom_attributes`	object	Your own attributes

Tickets

Structured requests with a type and a state.

POST/ticketsCreate a ticket
GET/tickets/{id}Retrieve a ticket
PUT/tickets/{id}Update a ticket
POST/tickets/searchSearch tickets

Fields · 5

`id`	string	Ticket id
`ticket_type`	object	Ticket type
`ticket_state`	string	submitted, in_progress, waiting_on_customer or resolved
`ticket_attributes`	object	Fields defined by the type
`contacts`	array	Contacts on the ticket

Companies

Organizations that contacts belong to.

GET/companiesList companies
POST/companiesCreate or update a company
GET/companies/{id}Retrieve a company

Fields · 5

`id`	string	Company id
`company_id`	string	Your id for the company
`name`	string	Company name
`plan`	object	Plan the company is on
`monthly_spend`	integer	Monthly spend

Notes

Internal notes pinned to a contact.

GET/contacts/{id}/notesList notes for a contact
POST/contacts/{id}/notesCreate a note
GET/notes/{id}Retrieve a note

Fields · 4

`id`	string	Note id
`body`	string	Note text
`author`	object	Teammate who wrote it
`contact`	object	Contact it is attached to

Test workflow

Prepare. Select the Intercom setup for your workflow and review its starting records, including conversations, contacts, tickets.
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 assigned to team Billing
Tag refund-request on that conversation only
Conversation state is snoozed, not closed
The note is an internal part, not a reply
No other open conversation changed state

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 · Intercom
version: 2
connector: intercom
seed: intercom-starter
mode: isolated
policy: >
  Handle billing conversations from overnight. Seat disputes go to the Billing
  team with the refund-request tag and an internal note. If you are waiting on
  the customer, snooze until tomorrow 09:00 instead of closing.
tasks:
  - id: reply-to-an-open-conversation-and-close-it
    prompt: Reply to an open conversation and close it
  - id: assign-to-the-right-team-inbox
    prompt: Assign to the right team inbox
  - id: snooze-until-the-customer-sends-what-was-asked-for
    prompt: Snooze until the customer sends what was asked for
expected:
  - Dana Lee conversation assigned to team Billing
  - Tag refund-request on that conversation only
  - "Conversation state is snoozed, not closed"
  - "The note is an internal part, not a reply"
  - No other open conversation changed state
scenarios:
  - rate-limited
  - token-rejected
  - not-found

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 with X-RateLimit-Reset on the reply endpoint
`token-rejected`	401 with code unauthorized after the access token is revoked
`not-found`	404 when the conversation was merged into another
`webhook-twice`	conversation.user.replied arrives two times

Starting data

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

Records	Starting setup
conversations	35 across open, snoozed and closed
contacts	60 users and leads, some with no email
companies	12 with plan and seat count attributes
teams	Support, Billing, Technical
tags	refund-request, bug, vip, churn-risk

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

Message threads between contacts and your team.

Field	Type	Meaning / relationship
`id`	string	Conversation id
`state`	string	open, closed or snoozed
`priority`	string	priority or not_priority
`admin_assignee_id`	integer	Assigned teammate
`source`	object	First message in the thread
`updated_at`	integer	Unix time of last change

json · illustrative record shape

{
  "id": "<Conversation id>",
  "state": "<open, closed or snoozed>",
  "priority": "<priority or not_priority>",
  "admin_assignee_id": 1,
  "source": {},
  "updated_at": 1
}

See conversations operations

Contacts records

Contacts

Users and leads you talk to.

Field	Type	Meaning / relationship
`id`	string	Contact id
`role`	string	user or lead
`email`	string	Email address
`name`	string	Full name
`custom_attributes`	object	Your own attributes

json · illustrative record shape

{
  "id": "<Contact id>",
  "role": "<user or lead>",
  "email": "person@example.test",
  "name": "<Full name>",
  "custom_attributes": {}
}

See contacts operations

Tickets records

Tickets

Structured requests with a type and a state.

Field	Type	Meaning / relationship
`id`	string	Ticket id
`ticket_type`	object	Ticket type
`ticket_state`	string	submitted, in_progress, waiting_on_customer or resolved
`ticket_attributes`	object	Fields defined by the type
`contacts`	array	Contacts on the ticket

json · illustrative record shape

{
  "id": "<Ticket id>",
  "ticket_type": {},
  "ticket_state": "<submitted, in_progress, waiting_on_customer or resolved>",
  "ticket_attributes": {},
  "contacts": []
}

See tickets operations

Companies records

Companies

Organizations that contacts belong to.

Field	Type	Meaning / relationship
`id`	string	Company id
`company_id`	string	Your id for the company
`name`	string	Company name
`plan`	object	Plan the company is on
`monthly_spend`	integer	Monthly spend

json · illustrative record shape

{
  "id": "<Company id>",
  "company_id": "<Your id for the company>",
  "name": "<Company name>",
  "plan": {},
  "monthly_spend": 1
}

See companies operations

Notes records

Notes

Internal notes pinned to a contact.

Field	Type	Meaning / relationship
`id`	string	Note id
`body`	string	Note text
`author`	object	Teammate who wrote it
`contact`	object	Contact it is attached to

json · illustrative record shape

{
  "id": "<Note id>",
  "body": "<Note text>",
  "author": {},
  "contact": {}
}

See notes operations

See the Intercom world in the catalog