Clientwell: setup and user guide
What Clientwell does
Clientwell shows the requester's HubSpot contact in the Zendesk ticket sidebar (and on user profiles): lifecycle stage, lead status and owner, their company, open deals with stage, amount and owner, recent notes, calls, emails and meetings, and the lists they are on. Agents you allow can create the contact, change the lifecycle stage, lead status or owner, log a note on the contact or company, and create a task or a deal. Every action asks for confirmation first and is logged on the ticket as an internal note.
1. Create a private app in HubSpot
A HubSpot super admin creates it: Development > Legacy apps > Create legacy app > Private. Name it "Clientwell for Zendesk". On the Scopes tab, add:
| Scope | What Clientwell uses it for | Needed? |
|---|---|---|
crm.objects.contacts.read | Find and show the contact; notes, calls and meetings | Yes |
crm.objects.companies.read | The contact's company; the domain match | Yes |
crm.objects.deals.read | Deals, pipelines and stage names | Yes |
crm.objects.owners.read | Owner names and the owner pickers | Yes |
crm.schemas.contacts.read, crm.schemas.companies.read | Your own lifecycle stages, lead statuses and extra field labels (without them Clientwell uses HubSpot's default stages and shows field names) | Recommended |
sales-email-read | Logged emails in the activity list | Recommended |
crm.lists.read | The lists a contact belongs to | Optional |
crm.objects.contacts.write | Create and update contacts, log notes, create tasks | For actions |
crm.objects.companies.write | Notes and tasks attached to a company | For actions |
crm.objects.deals.write | Create deals | For actions |
Create the app, open Auth and copy the access token. A token with only the read scopes gives the full panel without actions; if an agent tries an action anyway, Clientwell shows HubSpot's refusal with the missing scope and nothing changes.
2. Install and connect
- In the Zendesk Marketplace, open Clientwell and choose Install, then the plan for your team size: Team ($100 per month, up to 14 agents and admins) or Scale ($7.50 per agent per month, 15 or more). The 14-day trial starts and Zendesk asks for a card. Billing starts when the trial ends unless you uninstall.
- Paste the token into HubSpot private app access token. Zendesk stores it as a secure setting: it is never sent to agents' browsers, and Zendesk only adds it to requests going to api.hubapi.com.
- Save. Open any ticket whose requester is in your HubSpot CRM.
3. Settings
- Who may take actions:
agent(everyone, the default),admin, custom role ids (Admin Center > People > Roles; the id is in the role's URL) orgroup:<id>, separated by commas. Everyone else sees the panel read-only. - Allow creating contacts / changing stage, status and owner / logging notes / creating tasks / creating deals: switch any action type off.
- Let agents move lifecycle stages back: off by default. HubSpot only moves a lifecycle stage forward; to go back (Customer to Opportunity) Clientwell clears the stage and sets the new one, and by default only admins may do that.
- Default pipeline for new deals: a pipeline id (HubSpot > Settings > Objects > Deals > Pipelines). Empty means your first pipeline.
- Match a company by email domain: when the requester has no contact, show the company whose domain equals their email domain (gmail.com, outlook.com and other mailbox providers are skipped), so the agent can create the contact there.
- Show list memberships: the lists the contact is on (needs
crm.lists.read). - Extra contact fields / Extra company fields: up to 10 HubSpot internal property names each,
separated by commas, for example
plan_tier, renewal_date. Find internal names in HubSpot > Settings > Properties (open a property; the internal name is under its label).
4. Using the panel
- Matching: Clientwell searches HubSpot for every email address on the requester's Zendesk profile, against each contact's primary email and additional emails. Several matches are listed so the agent can switch. The lookup box finds a contact by exact email, contact id or a pasted HubSpot record link.
- Contact: lifecycle stage, lead status, owner, job title, phone, contact since and last contacted, and your extra fields. Open in HubSpot opens the record.
- Company, open deals, recent activity, lists: below the contact. Deals show pipeline, stage, amount, close date and owner, with a count of won and lost deals. Activity shows the newest five notes, calls, logged emails and meetings; Show all lists the rest.
- Refresh reloads everything. Nothing is kept once the sidebar closes.
5. Actions
Every action opens a form, shows a sentence saying exactly what will change, and lists anything that blocks it. Nothing is sent until the agent clicks the button. Afterwards Clientwell adds an internal note to the ticket (the HubSpot record, what changed, the agent, the agent's own note) and a tag.
| Action | What happens in HubSpot | Tag |
|---|---|---|
| Create a contact | A contact with the requester's email, name, and the stage, status, owner and company you pick. Clientwell searches again just before, so a contact someone else just added is never duplicated | clientwell_contact_created |
| Change stage, status or owner | Only the fields you changed are updated. A stage moving back is cleared, then set | clientwell_contact_updated |
| Log a note | A note on the contact, the company or both, with your text and a link to the ticket (and its subject, unless you untick it). Owned by the agent's HubSpot user when their emails match | clientwell_note |
| Create a task | A task with a title, due date (next business day by default), priority, type and owner, linked to the contact and company, with the ticket link | clientwell_task |
| Create a deal | A deal in the pipeline and stage you pick, with amount, close date and owner, associated with the contact and, if you choose, the company; the ticket link goes in the deal description | clientwell_deal |
Actions need a saved ticket. On a new ticket or a user profile the panel is read-only.
6. Plans
Clientwell counts the agents and admins in your Zendesk account when it opens. If the account has outgrown the plan (for example 20 agents on Team), the panel stays visible and actions turn off, with a message naming the plan that fits. An admin changes the plan in the Zendesk Marketplace.
7. Troubleshooting
| Message | What to do |
|---|---|
| "HubSpot did not accept the access token" | The private app was deleted, or its token was rotated. Paste the current token from Development > Legacy apps > the app > Auth |
| "The HubSpot access token is missing a permission for this (scope)" | Add that scope to the private app in HubSpot, save, and paste the token again if HubSpot asks you to |
| "Owner names are hidden" or "Logged emails are hidden" | An optional scope is missing; see the table in section 1 |
| No contact found | The email on the Zendesk profile differs from HubSpot's. Use the lookup box, or add the address as an additional email in HubSpot |
| "HubSpot already has a contact for this email" | Someone else created it, or it is another contact's additional email. Click Refresh |
| "Moving the lifecycle stage back... needs an admin" | Ask an admin, or turn on Let agents move lifecycle stages back |
| No actions visible | Your role or group is not in Who may take actions, the action type is off, the plan does not match your team size, or this is a new ticket or a user profile |
Questions: hello@greatwork.company. We reply within one business day.
8. Data and privacy
Clientwell has no server. HubSpot data is read live while the sidebar is open and never stored, copied or exported. Writes happen only when an agent confirms an action on a ticket, and only what the agent types plus the ticket link go to HubSpot, never the ticket conversation. Full policy: https://greatwork.company/apps/clientwell/privacy. Terms: https://greatwork.company/apps/clientwell/eula.