Overview
A client-mode connector for the Help Scout Inbox API 2.0 (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.
Authentication
Help Scout uses OAuth 2.0. For a broker integration the client credentials flow fits best (see Help Scout authentication):- 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.
-
Publish the app id and secret to
crm/help-scout/oauth/token(eventTokenGet):{"body": {"grant_type": "client_credentials", "client_id": "<app id>", "client_secret": "<app secret>"}} -
Read
access_tokenfromcrm/help-scout/oauth/token/response. It is valid for 172800 seconds (two days). Pass it asaccess_tokenin every other payload; the connector sendsAuthorization: Bearer <token>. Request a new token only when a call answers 401.
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 |
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
DEFINE CONNECTOR 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
- Note and close
- Open alarms in an inbox
- Custom fields
Get a Add
mailboxId from crm/help-scout/mailboxes/list, then publish to crm/help-scout/conversations/create:{"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"]}}
"assignTo": <user or team id> to assign it, or "imported": true to log it without sending email.While the alarm is handled, publish to When it clears, publish
crm/help-scout/conversations/notes/create:{"access_token": "<from TokenGet>", "id": "<conversation id>", "body": {"text": "Spindle temperature back to 61 C"}}
{"access_token": "...", "id": "<conversation id>", "body": {"op": "replace", "path": "/status", "value": "closed"}} to crm/help-scout/conversations/update.Publish to
crm/help-scout/conversations/list:{"access_token": "<from TokenGet>", "query": "mailbox=85&status=active&tag=alarm"}
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:{"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 exampleconvo.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 |

