HubSpot: connecting

The assistant reads from HubSpot who is writing to it: the contact and the company, deals and support tickets. It never writes to HubSpot. What exactly it may read, you decide for each mailbox separately. How connections work in draften in general is described on the Integrations page.

What you need

• A HubSpot account with super admin rights (or with the Developer tools access permission) — only such an account can create an API key.
• In draften, an owner or manager of the organisation.

draften needs an API key with read scopes only. HubSpot issues it today as a service key. Older accounts may also have an earlier private app token (it starts with pat-); it keeps working, only HubSpot no longer lets you create new private apps.

In HubSpot: service key

1. Open the list of keys: in the main menu, Development → Keys → Service keys (in some accounts Settings → Integrations → Service Keys).
2. At the top right, click Create service key and name the key, for example draften.
3. Click Add new scope. In the panel on the right, search (the Find a scope field) and tick only these read scopes:
   • crm.objects.contacts.read — contacts,
   • crm.objects.companies.read — companies,
   • crm.objects.owners.read — who looks after the contact,
   • crm.objects.deals.read — deals,
   • crm.objects.tickets.read — tickets.

   Add nothing with .write. A key can only get the scopes its creator has.

4. Create the key. On its page, click Show and then Copy.

You can replace the key later (Rotate and expire now, or Rotate and expire later — the old one then stays valid for 7 more days). Paste the new key into draften (below).

In draften

1. Open Organisation → Integrations and, in the Integrations card, fill in:
   • System — HubSpot,
   • Name — for example HubSpot - sales and support,
   • Access secret — the copied key.

   Click Add connection. The key is stored encrypted and never shown again.

2. In the connection's row, open the ⋯ menu → Test the connection. In a moment it shows "Connection fine (…)". Missing scopes are listed under "Not available with this token:"; when the key has write scopes too, the test points that out.
3. In the Which mailboxes may use the connection part, click Grant by a mailbox, tick what the assistant may read and click Save the grant:
   • Contact and company,
   • Deals and, under it, Deal amounts,
   • Support tickets and, under it, Ticket detail and Internal notes of a ticket.
4. The assistant's editor then adds, in the assistant's Settings → Knowledge, a source of the external system kind and chooses what the assistant really reads — see Connecting a CRM and other systems.

When you replace the key, paste the new one into New access secret by the connection and click Replace; then Test the connection again.

Connection test errors

The test's message is in English, straight from HubSpot or from draften: