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

# Help Scout

> Connect Help Scout to your Atako agents — 8 read and 6 write actions.

Let your agents manage conversations, customers, mailboxes and tags in your Help Scout workspace.

## Connection

* **Authentication**: OAuth 2.0 — you authorize Atako via Help Scout's consent screen; no key to copy.

<Note>
  Help Scout → Your Profile → My Apps → Create My App. Enter a name and a placeholder Redirect URL (e.g. [https://www.google.com](https://www.google.com)). Copy the App ID and App Secret. Then share them with your platform admin so INTEGRATION\_OAUTH\_HELPSCOUT\_CLIENT\_ID and INTEGRATION\_OAUTH\_HELPSCOUT\_CLIENT\_SECRET are set.

  See [Help Scout's documentation](https://developer.helpscout.com/mailbox-api/overview/authentication/).
</Note>

## Read actions (8)

| Action               | Description                                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_conversation`   | Fetch a single conversation by its id.                                                                                                                                                                                                |
| `get_customer`       | Fetch a single customer by its id.                                                                                                                                                                                                    |
| `list_conversations` | List and filter conversations. Optional filters: mailbox (inbox id number), status (active, all, closed, open, pending, spam), tag (comma-separated tag names), query (advanced search string, e.g. subject:"refund"), page (number). |
| `list_customers`     | List customers. Optional filters: mailbox (inbox id number), firstName, lastName, query (advanced search, e.g. email:"[user@example.com](mailto:user@example.com)"), page (number).                                                   |
| `list_mailboxes`     | List all mailboxes the token has access to.                                                                                                                                                                                           |
| `list_tags`          | List all tags used across all inboxes, in alphabetical order.                                                                                                                                                                         |
| `list_threads`       | List threads (messages, notes) in a conversation.                                                                                                                                                                                     |
| `list_users`         | List all users (agents) in the workspace. Optional filters: email (exact match), mailbox (inbox id number).                                                                                                                           |

## Write actions (6)

| Action                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_conversation`   | Create a conversation in an inbox. subject (string) is required. type (string: email, chat, phone) is required. mailboxId (number) is required. status (string: active, closed, pending) is required. customer (object with email string and optional firstName/lastName) is required. threads (array, at least one thread object with type and text) is required. Optional: tags (array of tag name strings), assignTo (number, user or team id). |
| `create_customer`       | Create a new customer. Optional: firstName (string, max 40 chars), lastName (string, max 40 chars), jobTitle (string, max 60 chars), background (string, max 200 chars), location (string, max 60 chars), organizationId (number), emails (array of objects with type and value), phones (array of objects with type and value).                                                                                                                   |
| `create_note`           | Add an internal note to a conversation. text (string) is required. Optional: status (string to change conversation status).                                                                                                                                                                                                                                                                                                                        |
| `reply_to_conversation` | Reply to a conversation by creating a reply thread. text (string, XHTML) is required. Optional: status (string to change conversation status), draft (boolean, default false), assignTo (number, user or team id).                                                                                                                                                                                                                                 |
| `update_conversation`   | Update a conversation using JSON Patch. Pass `field` (one of: status, assignTo, subject, mailboxId, primaryCustomerId, draft) and the new `value`. Status values: active, closed, pending, spam. For assignTo, pass a user ID number or team ID number. To unassign, omit the value.                                                                                                                                                               |
| `update_customer`       | Update a customer using JSON Patch. Optional fields: firstName (string, max 40 chars), lastName (string, max 40 chars), jobTitle (string, max 60 chars), background (string, max 200 chars), location (string, max 60 chars), organizationId (number). Only provided fields are updated.                                                                                                                                                           |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.