# HelpScout API

{% hint style="info" %}
This piece is documentation for Lightward AI's presence in our HelpScout work.
{% endhint %}

{% code title="Conversations" %}

```markdown
<!--
  1. https://developer.helpscout.com/mailbox-api/endpoints/conversations/get/
  2. copy <section> tag to outerHTML
  3. pass through https://mixmark-io.github.io/turndown/
  -->

# Get Conversation

`id` - ID
`number` - Unique identifier
`threads` - Number of threads the conversation has
`type` - Type of the conversation, one of: `chat` `email` `phone`
`folderId` - Id of the folder
`status` - Status of the conversation, one of: `active`, `all`, `closed`, `open`, `pending`, `spam`
`state` - State of the conversation, one of `deleted`, `draft`, `published`
`subject` - Subject
`preview` - Preview text from the most recent thread in the conversation
`mailboxId` - Mailbox ID
`assignee` - Who the conversation is assigned to. Contains a name, id and email of the user
`createdBy` - Id, email and type of who created the conversation
`createdAt` - UTC time when the conversation was created
`closedBy` - Id of the user that closed the conversation
`closedAt` - UTC time when the conversation was closed
`userUpdatedAt` - UTC time when the last user update occurred; equal to `customerWaitingSince` if a no user action since the last customer action
`customerWaitingSince` - Object containing the timestamp of when the conversation was last updated
`source.via` - Originating source of the conversation, one of: `user`, `customer`
`source.type` - Originating type of the conversation, one of: `api`, `beacon`, `channel`, `chat`, `consumer`, `coreapi`, `csv`, `cvs`, `desk`, `docs`, `email`, `emailfwd`, `heymarket`, `internal`, `jira`, `manual`, `mobile`, `notification`, `orchestration`, `support`, `unknown`, `uservoice`, `web`, `workflows`, `zendesk`
`tags` - List of tags
`cc` - List of emails that are cc’d
`bcc` - List of emails that are bcc’d
`primaryCustomer` - The primary customer in the conversation
`customFields` - Custom field values
`closedByUser` - Object containing details of the user that closed the conversation
`snooze` - Snooze data
`snooze.snoozedBy` - The user that snoozed this conversation
`snooze.snoozedUntil` - Until when is this conversation snoozed
`snooze.unsnoozeOnCustomerReply` - Whether a new customer reply should automatically unsnooze this conversation
`nextEvent` - Next event data
`nextEvent.time` - ISO 8601 date string
`nextEvent.eventType` - One of: `snooze`, `scheduled`
`nextEvent.userId` - Who created the next event
`nextEvent.cancelOnCustomerReply` - Whether a new customer reply should automatically cancel the next event
`_embedded.threads` - List of threads
```

{% endcode %}

{% code title="Threads" %}

```markdown
<!--
  1. https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/list/
  2. copy <section> tag to outerHTML
  3. pass through https://mixmark-io.github.io/turndown/
  -->

# List Threads

============

`.id` - Unique identifier
`assignedTo` - The user assigned to this thread.
`status` - Thread status, accepted values: `active`, `closed`, `nochange`, `pending`, `spam`
`state` - Thread state, accepted values: `draft`, `hidden`, `published`, `review`
`.action.type` - Internal action type
`.action.text` - Human friendly description of the action. Applicable for thread type `lineitem` only
`.action.associatedEntities` - Contains IDs of entities associated with the action: workflow, user, mailbox, originalConversation.
`body` - Thread text content
`source.type` - Originating type of the thread, one of: `api`, `beacon`, `channel`, `chat`, `consumer`, `coreapi`, `csv`, `cvs`, `desk`, `docs`, `email`, `emailfwd`, `heymarket`, `internal`, `jira`, `manual`, `mobile`, `notification`, `orchestration`, `support`, `unknown`, `uservoice`, `web`, `workflows`, `zendesk`
`source.via` - Originating source of the thread, one of: `user`, `customer`. If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread.
`createdBy` - Who created this thread. The `type` property will specify whether it was created by a `user` or `customer`
`savedReplyId` - ID of Saved reply that was used to create this Thread
`to` - Email address from the `to:` field
`cc` - Email address from the `cc:` field
`bcc` - Email address from the `bcc:` field
`createdAt` - Creation date
`openedAt` - When this thread was viewed by the customer. Only applies to threads with a `type` of message.
`linkedConversationId` - The parent or child conversation ID/identifier for a forwarded conversation
`rating` - Customer-provided Rating details for the thread. Only applies to threads with a `type` of message.
`scheduled` - Schedule details
`_embedded.attachments` - Conversation attachments

A state of `underreview` means the thread has been stopped by Collision Detection and is waiting to be confirmed (or discarded) by the person that created the thread.

A state of `hidden` means the thread was hidden (or removed) from customer-facing emails.

Thread status is only updated when there is a status change. Otherwise, the status will be set to `nochange`.
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.lightward.guide/support/helpscout-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.