Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Help Scout

Scalekit connector
Open markdown

The Help Scout connector lets your AI agent act in each user's Help Scout account. Each user signs in to Help Scout once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 100 tools.

Tools
100
What they doRead · write · destructive
48 · 38 · 1448 read38 write14 destructive
Users sign in with
OAuth app
Your own Help Scout app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Help Scout connection

    In AgentKit > Connections, create a Help Scout connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Help Scout connections use your own OAuth app. Register one with Help Scout and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Help Scout connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'helpscout'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Help Scout:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'helpscout_conversations_list',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • helpscout_conversation_attachment_data_getGet the content of a Help Scout conversation attachment as Base64 text.Read-only

    Get Attachment Data

    Get the content of a Help Scout conversation attachment as Base64 text. Returns an object whose data field holds the Base64-encoded file. Use conversation_attachment_data_get to read a file. Find attachment IDs in conversation_threads_list (`_embedded.attachments`).

    Inputs

    attachment_idintegerrequired
    Attachment ID from the thread's `_embedded.attachments[].id`.
    conversation_idintegerrequired
    Help Scout conversation ID (the internal `id`, not the conversation `number` shown in the app). Get it from List Conversations or Search Conversations.
  • helpscout_conversation_getGet one Help Scout conversation by ID.Read-only

    Get Conversation

    Get one Help Scout conversation by ID. Returns subject, status, inbox, assignee, customer, tags, custom fields, cc and bcc, snooze state and links, and the threads when embed is threads. Use conversation_get when you have the ID. Use conversations_list or conversations_search to find it. Use conversation_threads_list for the full message history.

    Inputs

    conversation_idintegerrequired
    Help Scout conversation ID (the internal `id`, not the conversation `number` shown in the app). Get it from List Conversations or Search Conversations.
    embedstring
    Set to threads to include the conversation's threads in the response.one of threads
  • helpscout_conversation_thread_source_getGet the original source of an email thread in a Help Scout conversation, as JSON.Read-only

    Get Thread Original Source

    Get the original source of an email thread in a Help Scout conversation, as JSON. Returns the raw email headers and body parts as received. Use conversation_thread_source_get to inspect email headers or the raw message. Use conversation_threads_list for normal reading.

    Inputs

    conversation_idintegerrequired
    Help Scout conversation ID (the internal `id`, not the conversation `number` shown in the app). Get it from List Conversations or Search Conversations.
    thread_idintegerrequired
    Thread ID inside the conversation. Get it from List Threads (`_embedded.threads[].id`).
  • helpscout_conversation_threads_listList the threads (customer messages, replies, notes, chats, phone calls and system events) of a Help Scout conversation, newest first.Read-only

    List Conversation Threads

    List the threads (customer messages, replies, notes, chats, phone calls and system events) of a Help Scout conversation, newest first. Returns each thread's id, type, status, body, author, recipients, cc and bcc, and attachment links, with page totals. Use conversation_threads_list to read the full message history. Use conversation_get for conversation-level details.

    Inputs

    conversation_idintegerrequired
    Help Scout conversation ID (the internal `id`, not the conversation `number` shown in the app). Get it from List Conversations or Search Conversations.
    pageinteger
    Page number to return, starting at 1. Each page holds up to 25 threads; the response's `page.totalPages` says how many pages exist. Leave empty for the first page.
  • helpscout_conversations_listList Help Scout conversations newest first, filtered by inbox, status, tag, assignee, customer, email, number or date.Read-only

    List Conversations

    List Help Scout conversations newest first, filtered by inbox, status, tag, assignee, customer, email, number or date. Returns conversations with id, number, subject, status, inbox, assignee, customer, tags and custom fields, plus a `_links.next` cursor link when more results exist. Use conversations_list to browse with exact filters. Use conversations_search for full-text or OR/NOT queries on subject, body or other fields.

    Inputs

    assigned_idinteger
    Only return conversations assigned to this user ID. Get IDs from List Users.
    contact_idstring
    Only return conversations of these customer IDs. One ID or several separated by commas.
    created_sincestring
    Only return conversations created after this time, as ISO 8601 UTC.
    cursorstring
    Pagination cursor for the next page. Copy the `cursor` query value from `_links.next.href` in the previous response (for example `...?cursor=eyJpZCI6MTIzfQ==` gives `eyJpZCI6MTIzfQ==`). Leave empty for the first page.
    custom_fields_by_idsstring
    Filter by custom field values as fieldId:value pairs separated by commas. Requires exactly one inbox_id. For dropdown fields the value is the option ID from List Inbox Custom Fields.
    emailstring
    Only return conversations whose customer has exactly this email address. Accepts one address.
    embedstring
    Set to threads to include each conversation's threads in the response (chat threads are truncated).one of threads
    inbox_idstring
    Only return conversations in these inboxes. One inbox ID or several separated by commas. Get IDs from List Inboxes.
    modified_sincestring
    Only return conversations modified after this time, as ISO 8601 UTC.
    numberinteger
    Look up a conversation by the conversation number shown in the Help Scout app.
    statusstring
    Conversation status filter, one value or several separated by commas: active, pending, closed, spam, open (active and pending) or all. Defaults to active.
    tagstring
    Only return conversations with these tag names. One tag or several separated by commas.
  • helpscout_customer_address_getGet the postal address of a Help Scout customer.Read-only

    Get Customer Address

    Get the postal address of a Help Scout customer. Returns city, state, postal code, country and address lines. Use customer_address_get to read the address alone. customer_get also embeds it.

    Inputs

    customer_idintegerrequired
    Help Scout customer ID. Get it from List Customers or Search Customers.
  • helpscout_customer_chat_handles_listList the chat handles of a Help Scout customer.Read-only

    List Customer Chat Handles

    List the chat handles of a Help Scout customer. Returns each entry's id, type and value. Use customer_chat_handles_list to get entry IDs before an update or delete. customer_get also embeds them.

    Inputs

    customer_idintegerrequired
    Help Scout customer ID. Get it from List Customers or Search Customers.
All 21 in Customer Support