> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Help Scout

> Client-mode REST API connector for Help Scout (Inbox API 2.0): open conversations from machine alarms, add notes and replies, close, assign, tag or snooze them, keep customer profiles and conversation custom fields current, run workflows

Technical Preview

## Overview

A client-mode connector for the [Help Scout Inbox API 2.0](https://developer.helpscout.com/mailbox-api/) (formerly the Mailbox API) that connects plant and product events to a shared support inbox. A connected machine that raises an alarm can open a conversation for the customer who owns it, the team can add internal notes while it is handled, and the conversation can be closed, reassigned, tagged or snoozed when the alarm clears. Customer profiles and conversation custom fields can be kept current from live data, and manual workflows can be run on conversations.

Help Scout now calls mailboxes "inboxes", but the API paths still use `/v2/mailboxes`. Topics use `crm/help-scout/<object>/<verb>`; each response is published on `<source topic>/response`.

> [!NOTE]
>
> The template was checked against the Help Scout Inbox API 2.0 reference pages and a local mock. On `api.helpscout.net` the token endpoint rejects a dummy client with 400 `invalid_client` and every packaged path answers 401 `invalid_token` to an invalid token. Help Scout checks the token before it connectors a request, so those probes confirm the host and authentication scheme but not each path. It has **not** been run against a real Help Scout account yet, so status stays blocked until an authenticated smoke passes.

## Authentication

Help Scout uses OAuth 2.0. For a broker integration the client credentials flow fits best (see [Help Scout authentication](https://developer.helpscout.com/mailbox-api/overview/authentication/)):

1. In Help Scout, open **Your Profile > My Apps** and create an app. A redirect URL is required but unused for client credentials, so any placeholder works.

2. Publish the app id and secret to `crm/help-scout/oauth/token` (event `TokenGet`):

   ```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
   {"body": {"grant_type": "client_credentials", "client_id": "<app id>", "client_secret": "<app secret>"}}
   ```

3. Read `access_token` from `crm/help-scout/oauth/token/response`. It is valid for 172800 seconds (two days). Pass it as `access_token` in every other payload; the connector sends `Authorization: Bearer <token>`. Request a new token only when a call answers 401.

The credentials must belong to an active, invited Help Scout user, or every call answers 401.

> [!WARNING]
>
> Store the app id and secret as broker secrets (for example `HELPSCOUT_APP_ID` and `HELPSCOUT_APP_SECRET`) and have a LoT action add them with `GET SECRET`. The token response topic carries a live token: restrict it with a rule, never retain it, and do not put tokens in retained messages.

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `body` | `TokenGet` and every POST / PUT / PATCH event | JSON object (or JSON Patch array for `CustomerUpdate`) sent as the request body |
| `access_token` | every event except `TokenGet` | Bearer token from `TokenGet` |
| `id` | `...Get`, updates, notes, replies, tags, fields, snooze, threads, `WorkflowRun` | Help Scout id of the inbox, conversation, customer or workflow |
| `query` | `UsersList`, `ConversationsList`, `CustomersList`, `OrganizationsList`, `ConversationsReport` | URL-encoded query string |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `TokenGet` | `POST` | `/v2/oauth2/token` | `crm/help-scout/oauth/token` | |
| `CurrentUser` | `GET` | `/v2/users/me` | `crm/help-scout/users/me/get` | |
| `UsersList` | `GET` | `/v2/users?{query}` | `crm/help-scout/users/list` | |
| `MailboxesList` | `GET` | `/v2/mailboxes` | `crm/help-scout/mailboxes/list` | |
| `MailboxGet` | `GET` | `/v2/mailboxes/{id}` | `crm/help-scout/mailboxes/get` | |
| `MailboxFieldsList` | `GET` | `/v2/mailboxes/{id}/fields` | `crm/help-scout/mailboxes/fields/list` | |
| `MailboxFoldersList` | `GET` | `/v2/mailboxes/{id}/folders` | `crm/help-scout/mailboxes/folders/list` | |
| `ConversationsList` | `GET` | `/v2/conversations?{query}` | `crm/help-scout/conversations/list` | |
| `ConversationGet` | `GET` | `/v2/conversations/{id}` | `crm/help-scout/conversations/get` | |
| `ConversationCreate` | `POST` | `/v2/conversations` | `crm/help-scout/conversations/create` | yes |
| `ConversationUpdate` | `PATCH` | `/v2/conversations/{id}` | `crm/help-scout/conversations/update` | yes |
| `ThreadsList` | `GET` | `/v2/conversations/{id}/threads` | `crm/help-scout/conversations/threads/list` | |
| `NoteCreate` | `POST` | `/v2/conversations/{id}/notes` | `crm/help-scout/conversations/notes/create` | yes |
| `ReplyCreate` | `POST` | `/v2/conversations/{id}/reply` | `crm/help-scout/conversations/reply` | yes |
| `CustomerThreadCreate` | `POST` | `/v2/conversations/{id}/customer` | `crm/help-scout/conversations/customer-thread/create` | yes |
| `ConversationTagsUpdate` | `PUT` | `/v2/conversations/{id}/tags` | `crm/help-scout/conversations/tags/update` | yes |
| `ConversationFieldsUpdate` | `PUT` | `/v2/conversations/{id}/fields` | `crm/help-scout/conversations/fields/update` | yes |
| `ConversationSnooze` | `PUT` | `/v2/conversations/{id}/snooze` | `crm/help-scout/conversations/snooze/update` | yes |
| `CustomersList` | `GET` | `/v2/customers?{query}` | `crm/help-scout/customers/list` | |
| `CustomerGet` | `GET` | `/v2/customers/{id}` | `crm/help-scout/customers/get` | |
| `CustomerCreate` | `POST` | `/v2/customers` | `crm/help-scout/customers/create` | yes |
| `CustomerUpdate` | `PATCH` | `/v2/customers/{id}` | `crm/help-scout/customers/update` | yes |
| `CustomerPropertiesList` | `GET` | `/v2/customer-properties` | `crm/help-scout/customer-properties/list` | |
| `TagsList` | `GET` | `/v2/tags` | `crm/help-scout/tags/list` | |
| `OrganizationsList` | `GET` | `/v2/organizations?{query}` | `crm/help-scout/organizations/list` | |
| `WebhooksList` | `GET` | `/v2/webhooks` | `crm/help-scout/webhooks/list` | |
| `WorkflowsList` | `GET` | `/v2/workflows` | `crm/help-scout/workflows/list` | |
| `WorkflowRun` | `POST` | `/v2/workflows/{id}/run` | `crm/help-scout/workflows/run` | yes |
| `ConversationsReport` | `GET` | `/v2/reports/conversations?{query}` | `crm/help-scout/reports/conversations/get` | |

Creates answer `201 Created` with the new id in the `Resource-ID` header and an empty body; updates, tags, fields, snooze and workflow runs answer `204 No Content`. `ConversationUpdate` and `CustomerUpdate` use JSON Patch. No delete events are packaged on purpose. Writes count as two requests against the account rate limit, which depends on the plan (`X-RateLimit-Limit-Minute`, `X-RateLimit-Remaining-Minute`, `X-RateLimit-Retry-After`). The conversations report needs a Plus or Pro plan.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE HelpScoutRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.helpscout.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TokenGet
        WITH SOURCE_TOPIC "crm/help-scout/oauth/token"
        WITH DESTINATION_TOPIC "crm/help-scout/oauth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CurrentUser
        WITH SOURCE_TOPIC "crm/help-scout/users/me/get"
        WITH DESTINATION_TOPIC "crm/help-scout/users/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UsersList
        WITH SOURCE_TOPIC "crm/help-scout/users/list"
        WITH DESTINATION_TOPIC "crm/help-scout/users/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxesList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxGet
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/get"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxFieldsList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/fields/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/fields/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}/fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxFoldersList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/folders/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/folders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}/folders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationsList
        WITH SOURCE_TOPIC "crm/help-scout/conversations/list"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationGet
        WITH SOURCE_TOPIC "crm/help-scout/conversations/get"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/conversations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ThreadsList
        WITH SOURCE_TOPIC "crm/help-scout/conversations/threads/list"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/threads/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/threads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT NoteCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/notes/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/notes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ReplyCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/reply"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/reply/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/reply"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerThreadCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/customer-thread/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/customer-thread/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/customer"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationTagsUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/tags/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/tags/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationFieldsUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/fields/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/fields/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationSnooze
        WITH SOURCE_TOPIC "crm/help-scout/conversations/snooze/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/snooze/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/snooze"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomersList
        WITH SOURCE_TOPIC "crm/help-scout/customers/list"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CustomerGet
        WITH SOURCE_TOPIC "crm/help-scout/customers/get"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customers/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CustomerCreate
        WITH SOURCE_TOPIC "crm/help-scout/customers/create"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/customers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerUpdate
        WITH SOURCE_TOPIC "crm/help-scout/customers/update"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/customers/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerPropertiesList
        WITH SOURCE_TOPIC "crm/help-scout/customer-properties/list"
        WITH DESTINATION_TOPIC "crm/help-scout/customer-properties/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customer-properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TagsList
        WITH SOURCE_TOPIC "crm/help-scout/tags/list"
        WITH DESTINATION_TOPIC "crm/help-scout/tags/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT OrganizationsList
        WITH SOURCE_TOPIC "crm/help-scout/organizations/list"
        WITH DESTINATION_TOPIC "crm/help-scout/organizations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/organizations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WebhooksList
        WITH SOURCE_TOPIC "crm/help-scout/webhooks/list"
        WITH DESTINATION_TOPIC "crm/help-scout/webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WorkflowsList
        WITH SOURCE_TOPIC "crm/help-scout/workflows/list"
        WITH DESTINATION_TOPIC "crm/help-scout/workflows/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/workflows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WorkflowRun
        WITH SOURCE_TOPIC "crm/help-scout/workflows/run"
        WITH DESTINATION_TOPIC "crm/help-scout/workflows/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/workflows/{value.json.id}/run"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationsReport
        WITH SOURCE_TOPIC "crm/help-scout/reports/conversations/get"
        WITH DESTINATION_TOPIC "crm/help-scout/reports/conversations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/reports/conversations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Examples

**Conversation from an alarm**

Get a `mailboxId` from `crm/help-scout/mailboxes/list`, then publish to `crm/help-scout/conversations/create`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "body": {"subject": "Press 7 overtemperature (E42)", "mailboxId": 85, "type": "email", "customer": {"email": "ops@acme.com"}, "threads": [{"type": "customer", "customer": {"email": "ops@acme.com"}, "text": "Press 7 reported E42 at 13:55"}], "tags": ["alarm", "line-4"]}}
```

Add `"assignTo": <user or team id>` to assign it, or `"imported": true` to log it without sending email.

**Note and close**

While the alarm is handled, publish to `crm/help-scout/conversations/notes/create`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "id": "<conversation id>", "body": {"text": "Spindle temperature back to 61 C"}}
```

When it clears, publish `{"access_token": "...", "id": "<conversation id>", "body": {"op": "replace", "path": "/status", "value": "closed"}}` to `crm/help-scout/conversations/update`.

**Open alarms in an inbox**

Publish to `crm/help-scout/conversations/list`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "query": "mailbox=85&status=active&tag=alarm"}
```

**Custom fields**

Read field ids with `crm/help-scout/mailboxes/fields/list` (`"id": "<mailbox id>"`), then publish to `crm/help-scout/conversations/fields/update`. The list replaces all non-system fields:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "id": "<conversation id>", "body": {"fields": [{"id": 104, "value": "E42"}]}}
```

## Receiving webhooks

Help Scout can notify the broker about conversation and customer events (for example `convo.created`, `convo.status`, `convo.assigned`). Register the webhook once in Help Scout (or with `POST /v2/webhooks`), with a 40-character secret, and receive it with a separate server-mode REST\_API connector that enables `ENABLE_SERVER`. Help Scout signs each delivery with HMAC-SHA1 in the `X-HelpScout-Signature` header; verify it before trusting the payload. `WebhooksList` shows which webhooks are configured.

## Troubleshooting

| Symptom | Cause |
| - | - |
| 400 `invalid_client` on `TokenGet` | Wrong app id or secret, or `grant_type` missing |
| 401 `invalid_token` | Token expired (two days) or missing; request a new one |
| 401 on every call with a fresh token | The app's user is not an active, invited user |
| `ConversationsReport` refused | Reporting endpoints are only available on Plus and Pro plans |
| 412 on a note or reply | The conversation has 100 threads or is locked by an age policy |
| 429 | Account rate limit; wait for `X-RateLimit-Retry-After` seconds |

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Help Scout Inbox API 2.0 reference](https://developer.helpscout.com/mailbox-api/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.