KosmoKrator

data

Helpscout CLI for AI Agents

Use the Helpscout CLI from KosmoKrator to call Helpscout tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Helpscout CLI Setup

Helpscout can be configured headlessly with `kosmokrator integrations:configure helpscout`.

Install, configure, and verify 
# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure helpscout --set access_token="$HELPSCOUT_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor helpscout --json
kosmokrator integrations:status --json

Credentials

Authentication type: Bearer token bearer_token. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

KeyEnv varTypeRequiredLabel
access_token HELPSCOUT_ACCESS_TOKEN Secret secret yes Access Token
url HELPSCOUT_URL URL url no API Base URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call 
kosmo integrations:call helpscout.helpscout_list_conversations '{"mailbox":1,"status":"example_status","assignee":1,"customer":1,"tag":"example_tag","page":1,"per_page":1,"sort_field":"example_sort_field"}' --json
Provider shortcut 
kosmo integrations:helpscout helpscout_list_conversations '{"mailbox":1,"status":"example_status","assignee":1,"customer":1,"tag":"example_tag","page":1,"per_page":1,"sort_field":"example_sort_field"}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands 
kosmo integrations:docs helpscout --json
kosmo integrations:docs helpscout.helpscout_list_conversations --json
kosmo integrations:schema helpscout.helpscout_list_conversations --json
kosmo integrations:search "Helpscout" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

helpscout.helpscout_list_conversations

List support conversations from HelpScout. Supports filtering by mailbox, status, assignee, customer, and more. Returns paginated results.

Read read
Parameters
mailbox, status, assignee, customer, tag, page, per_page, sort_field, sort_order, query
Generic call 
kosmo integrations:call helpscout.helpscout_list_conversations '{"mailbox":1,"status":"example_status","assignee":1,"customer":1,"tag":"example_tag","page":1,"per_page":1,"sort_field":"example_sort_field"}' --json
Shortcut 
kosmo integrations:helpscout helpscout_list_conversations '{"mailbox":1,"status":"example_status","assignee":1,"customer":1,"tag":"example_tag","page":1,"per_page":1,"sort_field":"example_sort_field"}' --json

helpscout.helpscout_get_conversation

Get full details of a specific HelpScout conversation, including threads, customer info, and custom fields.

Read read
Parameters
id
Generic call 
kosmo integrations:call helpscout.helpscout_get_conversation '{"id":1}' --json
Shortcut 
kosmo integrations:helpscout helpscout_get_conversation '{"id":1}' --json

helpscout.helpscout_create_conversation

Create a new conversation in HelpScout. Requires a subject, customer, mailbox, and at least one thread (message or note).

Write write
Parameters
subject, mailbox_id, customer_id, customer_email, body, type, status, assignee_id, tags, cc, bcc
Generic call 
kosmo integrations:call helpscout.helpscout_create_conversation '{"subject":"example_subject","mailbox_id":1,"customer_id":1,"customer_email":"example_customer_email","body":"example_body","type":"example_type","status":"example_status","assignee_id":1}' --json
Shortcut 
kosmo integrations:helpscout helpscout_create_conversation '{"subject":"example_subject","mailbox_id":1,"customer_id":1,"customer_email":"example_customer_email","body":"example_body","type":"example_type","status":"example_status","assignee_id":1}' --json

helpscout.helpscout_update_conversation

Update an existing HelpScout conversation. Change status, assignee, tags, subject, or other fields.

Write write
Parameters
id, status, subject, assignee_id, mailbox_id, tags
Generic call 
kosmo integrations:call helpscout.helpscout_update_conversation '{"id":1,"status":"example_status","subject":"example_subject","assignee_id":1,"mailbox_id":1,"tags":"example_tags"}' --json
Shortcut 
kosmo integrations:helpscout helpscout_update_conversation '{"id":1,"status":"example_status","subject":"example_subject","assignee_id":1,"mailbox_id":1,"tags":"example_tags"}' --json

helpscout.helpscout_list_customers

List or search customers in HelpScout. Supports filtering by name, email, and pagination.

Read read
Parameters
first_name, last_name, email, page, per_page, sort_field, sort_order, query
Generic call 
kosmo integrations:call helpscout.helpscout_list_customers '{"first_name":"example_first_name","last_name":"example_last_name","email":"example_email","page":1,"per_page":1,"sort_field":"example_sort_field","sort_order":"example_sort_order","query":"example_query"}' --json
Shortcut 
kosmo integrations:helpscout helpscout_list_customers '{"first_name":"example_first_name","last_name":"example_last_name","email":"example_email","page":1,"per_page":1,"sort_field":"example_sort_field","sort_order":"example_sort_order","query":"example_query"}' --json

helpscout.helpscout_get_customer

Get full details of a specific HelpScout customer, including contact info, social profiles, and custom fields.

Read read
Parameters
id
Generic call 
kosmo integrations:call helpscout.helpscout_get_customer '{"id":1}' --json
Shortcut 
kosmo integrations:helpscout helpscout_get_customer '{"id":1}' --json

helpscout.helpscout_create_customer

Create a new customer in HelpScout. Provide at least a name or email address.

Write write
Parameters
first_name, last_name, email, organization, job_title, phone
Generic call 
kosmo integrations:call helpscout.helpscout_create_customer '{"first_name":"example_first_name","last_name":"example_last_name","email":"example_email","organization":"example_organization","job_title":"example_job_title","phone":"example_phone"}' --json
Shortcut 
kosmo integrations:helpscout helpscout_create_customer '{"first_name":"example_first_name","last_name":"example_last_name","email":"example_email","organization":"example_organization","job_title":"example_job_title","phone":"example_phone"}' --json

helpscout.helpscout_list_mailboxes

List all mailboxes in HelpScout. Returns mailbox IDs, names, and email addresses. Use mailbox IDs when creating or filtering conversations.

Read read
Parameters
page, per_page
Generic call 
kosmo integrations:call helpscout.helpscout_list_mailboxes '{"page":1,"per_page":1}' --json
Shortcut 
kosmo integrations:helpscout helpscout_list_mailboxes '{"page":1,"per_page":1}' --json

helpscout.helpscout_get_mailbox

Get details of a specific HelpScout mailbox, including name, email, folders, and user assignments.

Read read
Parameters
id
Generic call 
kosmo integrations:call helpscout.helpscout_get_mailbox '{"id":1}' --json
Shortcut 
kosmo integrations:helpscout helpscout_get_mailbox '{"id":1}' --json

helpscout.helpscout_get_current_user

Get the profile of the currently authenticated HelpScout user. Useful for verifying API connectivity and identifying the active account.

Read read
Parameters
none
Generic call 
kosmo integrations:call helpscout.helpscout_get_current_user '{}' --json
Shortcut 
kosmo integrations:helpscout helpscout_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

helpscout.helpscout_list_conversations 10 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_list_conversations --json
ParameterTypeRequiredDescription
mailbox integer no Filter by mailbox ID.
status string no Filter by status: "open", "closed", "pending", "spam", "all". Defaults to "all".
assignee integer no Filter by assigned user ID. Use 0 for unassigned.
customer integer no Filter by customer ID.
tag string no Filter by tag name.
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 25, max: 50).
sort_field string no Sort field: "createdAt", "updatedAt", "customer.name", "subject", "status", "mailbox".
sort_order string no Sort direction: "asc" or "desc" (default: "desc").
query string no Search query to filter conversations by keyword.
helpscout.helpscout_get_conversation 1 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_get_conversation --json
ParameterTypeRequiredDescription
id integer yes The conversation ID.
helpscout.helpscout_create_conversation 11 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_create_conversation --json
ParameterTypeRequiredDescription
subject string yes The conversation subject line.
mailbox_id integer yes The mailbox ID to create the conversation in.
customer_id integer no The customer ID. Required unless customer_email is provided.
customer_email string no Customer email address. Used if customer_id is not provided.
body string yes The content of the first message in the conversation.
type string no Conversation type: "email" (default) or "chat".
status string no Initial status: "open" (default), "pending", or "closed".
assignee_id integer no User ID to assign the conversation to.
tags array no Array of tag names to apply.
cc array no Array of email addresses to CC.
bcc array no Array of email addresses to BCC.
helpscout.helpscout_update_conversation 6 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_update_conversation --json
ParameterTypeRequiredDescription
id integer yes The conversation ID to update.
status string no New status: "open", "closed", "pending", or "spam".
subject string no Updated subject line.
assignee_id integer no User ID to assign. Use 0 to unassign.
mailbox_id integer no Move to a different mailbox.
tags array no Replace all tags (array of strings).
helpscout.helpscout_list_customers 8 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_list_customers --json
ParameterTypeRequiredDescription
first_name string no Filter by first name (partial match).
last_name string no Filter by last name (partial match).
email string no Filter by email address (partial match).
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 25, max: 50).
sort_field string no Sort field: "firstName", "lastName", "createdAt", "updatedAt".
sort_order string no Sort direction: "asc" or "desc" (default: "asc").
query string no Search query to filter customers by keyword.
helpscout.helpscout_get_customer 1 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_get_customer --json
ParameterTypeRequiredDescription
id integer yes The customer ID.
helpscout.helpscout_create_customer 6 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_create_customer --json
ParameterTypeRequiredDescription
first_name string no Customer first name.
last_name string no Customer last name.
email string no Primary email address for the customer.
organization string no Company or organization name.
job_title string no Job title.
phone string no Phone number.
helpscout.helpscout_list_mailboxes 2 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_list_mailboxes --json
ParameterTypeRequiredDescription
page integer no Page number for pagination (default: 1).
per_page integer no Number of results per page (default: 25, max: 50).
helpscout.helpscout_get_mailbox 1 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_get_mailbox --json
ParameterTypeRequiredDescription
id integer yes The mailbox ID.
helpscout.helpscout_get_current_user 0 parameters
Schema command 
kosmo integrations:schema helpscout.helpscout_get_current_user --json
ParameterTypeRequiredDescription
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.