> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Helpwise

The Helpwise connector lets your AI agent act in each user's Helpwise account. Each user connects their own Helpwise API key and secret once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 26 tools.

**Authentication:** API Key and Secret
**Categories:** Customer Support, Communication
**Tools:** 26: 12 read, 10 write, 4 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=HELPWISE)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Helpwise connection

   In **AgentKit > Connections**, create a Helpwise connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'helpwise_contact_get',
  toolInput: {
    contact_id: 24621644,
  },
  connector: 'helpwise',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="helpwise_contact_get",
    tool_input={
        "contact_id": 24621644,
    },
    connection_name="helpwise",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `helpwise_contact_get`

Get Contact · Read-only

Get one contact by ID with emails, phones, company and custom fields. Returns the contact.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`integer`, required): Contact ID, from helpwise_contacts_list or helpwise_contacts_search. Example: 24621644.

Example input: `{"contact_id":24621644}`

### `helpwise_contacts_list`

List Contacts · Read-only

List contacts in the account with limit and offset paging. Returns contacts with names, emails, phones and custom fields. Use helpwise_contacts_search to find by text.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Number of contacts to return. Example: 50.
- `offset` (`integer`, optional): Number of contacts to skip. Example: 0.

Example input: `{}`

### `helpwise_contacts_search`

Search Contacts · Read-only

Search contacts by name, email, phone or company text. Returns matching contacts.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `term` (`string`, required): Text to search for. Example: john.doe@acme.com.
- `limit` (`integer`, optional): Number of contacts to return. Example: 20.
- `offset` (`integer`, optional): Number of contacts to skip. Example: 0.

Example input: `{"term":"<term>"}`

### `helpwise_conversation_get`

Get Conversation · Read-only

Get the messages of one conversation in an inbox, with token paging. Returns messages with sender, body and time, and the next page token.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `conversation_id` (`integer`, required): Conversation ID, from helpwise_conversations_list. Example: 116851645.
- `inbox_id` (`integer`, required): Inbox (mailbox) ID; it appears in the inbox URL in Helpwise. Example: 227136.
- `label_id` (`integer`, optional): Folder to read: 14 all (default), 0 assigned, 10 unassigned, 11 starred, 9 snoozed, 2 draft, 1 sent, 7 closed, 8 spam, 5 trash, 6 scheduled. Example: 14. One of: `14`, `0`, `10`, `11`, `9`, `2`, `1`, `7`, `8`, `5`, `6`.
- `limit` (`integer`, optional): Number of messages to return. Example: 20.
- `page_token` (`string`, optional): Page token from the previous response, to get the next page. Example: 2026-01-15+11:06:54.

Example input: `{"conversation_id":116851645,"inbox_id":227136}`

### `helpwise_conversations_list`

List Conversations · Read-only

List conversations in an inbox, optionally in one folder (assigned, unassigned, closed, spam and so on), with token paging. Returns conversations with subject, contact, assignee, status and the next page token. Use helpwise_conversation_get for a conversation's messages.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbox_id` (`integer`, required): Inbox (mailbox) ID to list conversations from. Example: 204568.
- `label_id` (`integer`, optional): Folder to read: 14 all (default), 0 assigned, 10 unassigned, 11 starred, 9 snoozed, 2 draft, 1 sent, 7 closed, 8 spam, 5 trash, 6 scheduled. Example: 14. One of: `14`, `0`, `10`, `11`, `9`, `2`, `1`, `7`, `8`, `5`, `6`.
- `limit` (`integer`, optional): Number of conversations to return, up to 100. Example: 50.
- `page_token` (`string`, optional): Page token from the previous response, to get the next page. Example: 2026-01-15+11:06:54.

Example input: `{"inbox_id":204568}`

### `helpwise_custom_field_get`

Get Custom Field · Read-only

Get one custom field by ID. Returns the field.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `custom_field_id` (`integer`, required): Custom field ID, from helpwise_custom_fields_list. Example: 204514.

Example input: `{"custom_field_id":204514}`

### `helpwise_custom_fields_list`

List Custom Fields · Read-only

List the account's contact custom fields. Returns field IDs, names and descriptions. Use the IDs in contact custom_fields.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpwise_inbox_custom_fields_list`

List Inbox Custom Fields · Read-only

List the custom fields of one inbox with whether each is shown or hidden there. Returns fields.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbox_id` (`integer`, required): Inbox (mailbox) ID; it appears in the inbox URL in Helpwise. Example: 227136.

Example input: `{"inbox_id":227136}`

### `helpwise_inbox_tags_report_get`

Get Inbox Tags Report · Read-only

Get per-tag figures for one inbox over a period: conversations, average time to resolution, response time and first response time. Returns the report.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End of the period, YYYY-MM-DD HH:MM:SS. Example: 2026-01-31 23:59:59.
- `inbox_id` (`integer`, required): Inbox (mailbox) ID; it appears in the inbox URL in Helpwise. Example: 227136.
- `start` (`string`, required): Start of the period, YYYY-MM-DD HH:MM:SS. Example: 2026-01-01 00:00:00.
- `is_business_hours` (`integer`, optional): 1 to count only working hours, 0 (default) for all hours. Example: 0. One of: `0`, `1`.

Example input: `{"end":"<end>","inbox_id":227136,"start":"<start>"}`

### `helpwise_overall_report_get`

Get Overall Report · Read-only

Get the overall and team performance report for a period, optionally for one inbox or tag: emails per day, new, closed and assigned conversations, busiest hours, resolution and response times, CSAT and per-agent figures. Returns the report.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end` (`string`, required): End of the period, YYYY-MM-DD HH:MM:SS. Example: 2026-01-31 23:59:59.
- `start` (`string`, required): Start of the period, YYYY-MM-DD HH:MM:SS. Example: 2026-01-01 00:00:00.
- `inbox_id` (`integer`, optional): Only this inbox; all inboxes when empty. Example: 23456.
- `is_business_hours` (`integer`, optional): 1 to count only working hours, 0 (default) for all hours. Example: 0. One of: `0`, `1`.
- `tag_id` (`integer`, optional): Only conversations with this tag ID. Example: 87865.

Example input: `{"end":"<end>","start":"<start>"}`

### `helpwise_tag_get`

Get Tag · Read-only

Get one tag by ID. Returns the tag.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tag_id` (`integer`, required): Tag ID, from helpwise_tags_list. Example: 333333.

Example input: `{"tag_id":333333}`

### `helpwise_tags_list`

List Tags · Read-only

List the account's conversation tags. Returns tag IDs, names and colors. Use the IDs with helpwise_conversation_tags_apply.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `helpwise_contact_create`

Create Contact · Write

Create a contact with name, company, job title, emails, phones and custom field values. Returns the new contact.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `company` (`string`, optional): Company name. Example: Acme Inc.
- `custom_fields` (`array`, optional): Custom field values, each with id, name and value; field IDs from helpwise_custom_fields_list. Example: [{"id": 204513, "name": "City", "value": "San Francisco"}]
- `emails` (`array`, optional): Email addresses. Example: ["john.doe@acme.com"]
- `firstname` (`string`, optional): First name. Example: John.
- `job_title` (`string`, optional): Job title. Example: Operations Manager.
- `lastname` (`string`, optional): Last name. Example: Doe.
- `phones` (`array`, optional): Phone numbers, each with phoneTxt, phoneNo and type. Example: [{"phoneTxt": "+14155550123", "phoneNo": "+14155550123", "type": "0"}]

Example input: `{}`

### `helpwise_contact_update`

Update Contact · Write

Update a contact's name, company, job title, emails, phones or custom field values. Returns the updated contact.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`integer`, required): Contact ID, from helpwise_contacts_list or helpwise_contacts_search. Example: 24621644.
- `company` (`string`, optional): Company name. Example: Acme Inc.
- `custom_fields` (`array`, optional): Custom field values, each with id, name and value; field IDs from helpwise_custom_fields_list. Example: [{"id": 204513, "name": "City", "value": "San Francisco"}]
- `emails` (`array`, optional): Email addresses. Example: ["john.doe@acme.com"]
- `firstname` (`string`, optional): First name. Example: John.
- `job_title` (`string`, optional): Job title. Example: Operations Manager.
- `lastname` (`string`, optional): Last name. Example: Doe.
- `phones` (`array`, optional): Phone numbers, each with phoneTxt, phoneNo and type. Example: [{"phoneTxt": "+14155550123", "phoneNo": "+14155550123", "type": "0"}]

Example input: `{"contact_id":24621644}`

### `helpwise_conversation_tags_apply`

Apply Tags to Conversations · Write

Add tags to one or more conversations. Returns the result.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tag_ids` (`array`, required): Tag IDs, from helpwise_tags_list. Example: [333333, 444444]
- `thread_ids` (`array`, required): Conversation IDs, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"tag_ids":[333333,444444],"thread_ids":[116851645,116851702]}`

### `helpwise_conversation_tags_remove`

Remove Tags from Conversations · Write

Remove tags from one or more conversations. Returns the result.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `tag_ids` (`array`, required): Tag IDs, from helpwise_tags_list. Example: [333333, 444444]
- `thread_ids` (`array`, required): Conversation IDs, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"tag_ids":[333333,444444],"thread_ids":[116851645,116851702]}`

### `helpwise_conversations_close`

Close Conversations · Write

Close up to 100 conversations. Returns the result. Use helpwise_conversations_move_to_inbox to reopen them.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): Conversation IDs, up to 100, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"ids":[116851645,116851702]}`

### `helpwise_conversations_move_to_inbox`

Move Conversations to Inbox · Write

Move up to 100 conversations back to the inbox, reopening closed, spam or trashed ones. Returns the result.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): Conversation IDs, up to 100, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"ids":[116851645,116851702]}`

### `helpwise_custom_field_create`

Create Custom Field · Write

Create a contact custom field. Returns the new field ID.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the custom field. Example: Pin Code.
- `description` (`string`, optional): Description of the custom field. Example: Postal code of the customer's location.

Example input: `{"name":"<name>"}`

### `helpwise_custom_field_update`

Update Custom Field · Write

Rename a custom field or change its description. Returns the result.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `custom_field_id` (`integer`, required): Custom field ID, from helpwise_custom_fields_list. Example: 204514.
- `description` (`string`, optional): New description. Example: Postal code of the billing address.
- `name` (`string`, optional): New name. Example: Postal Code.

Example input: `{"custom_field_id":204514}`

### `helpwise_inbox_custom_fields_update`

Show or Hide Inbox Custom Fields · Write

Hide and/or show custom fields in one inbox. Returns the result.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `inbox_id` (`integer`, required): Inbox (mailbox) ID; it appears in the inbox URL in Helpwise. Example: 227136.
- `hide_ids` (`array`, optional): Custom field IDs to hide in the inbox. Example: [204513]
- `unhide_ids` (`array`, optional): Custom field IDs to show in the inbox. Example: [204522]

Example input: `{"inbox_id":227136}`

### `helpwise_sms_whatsapp_message_send`

Send SMS or WhatsApp Message · Write

Send an SMS or WhatsApp message to a customer's phone number from an SMS or WhatsApp inbox, now or scheduled; WhatsApp can use an approved template. Optionally close, assign or move the conversation in the same call. Returns the sent message. The customer receives it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`string`, required): Message text. Example: Hi John, your order has shipped.
- `client_number` (`string`, required): Customer's phone number in international format. Example: +14155550123.
- `inbox_id` (`integer`, required): ID of the SMS or WhatsApp inbox to send from. Example: 256785.
- `action` (`object`, optional): Conversation action to apply with the message, for example {"assignTo": 0, "name": "unassign"}; name can be unassign, close, spam, trash or moveToInbox. Example: {"name": "close"}
- `hash` (`string`, optional): Your own identifier for this request, to match parallel calls. Example: h7hfjk8khjl99kngq.
- `schedule_msg` (`boolean`, optional): Set to true to schedule the message for send_at. Example: true.
- `send_at` (`string`, optional): When to send a scheduled message, ISO 8601 UTC. Example: 2026-02-01T09:46:00.000Z.
- `template` (`object`, optional): WhatsApp template: templateId and templateVariables, plus headerVariables or locationVariables when the template needs them. Example: {"templateId": 245670, "templateVariables": ["John", "112233", "Shipped"]}

Example input: `{"body":"<body>","client_number":"<client_number>","inbox_id":256785}`

### `helpwise_conversations_delete`

Delete Conversations · Destructive

Permanently delete up to 100 conversations. Returns the result. Use helpwise_conversations_trash to keep them recoverable.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): Conversation IDs, up to 100, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"ids":[116851645,116851702]}`

### `helpwise_conversations_mark_spam`

Mark Conversations as Spam · Destructive

Move up to 100 conversations to spam. Returns the result. Reverse it with helpwise_conversations_move_to_inbox.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): Conversation IDs, up to 100, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"ids":[116851645,116851702]}`

### `helpwise_conversations_trash`

Trash Conversations · Destructive

Move up to 100 conversations to trash. Returns the result. Reverse it with helpwise_conversations_move_to_inbox.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`array`, required): Conversation IDs, up to 100, from helpwise_conversations_list. Example: [116851645, 116851702]

Example input: `{"ids":[116851645,116851702]}`

### `helpwise_custom_field_delete`

Delete Custom Field · Destructive

Delete a custom field and its values on contacts. Returns the result.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `custom_field_id` (`integer`, required): Custom field ID, from helpwise_custom_fields_list. Example: 204514.

Example input: `{"custom_field_id":204514}`

## Related

Other Customer Support connectors ([all 38](/agentkit/connectors/?category=customer-support)):

- [ServiceNow](/agentkit/connectors/servicenow/): Scalekit connector, OAuth, 112 tools
- [Zendesk](/agentkit/connectors/zendeskoauth/): Scalekit connector, OAuth, 137 tools
- [Jira Service Management](/agentkit/connectors/jiraservicemanagement/): Scalekit connector, OAuth, 72 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
