HubSpot
Connect HubSpot with your own OAuth app so an agent can save leads, add notes and look up a contact during a call.
What you will achieve
An agent will be able to create a contact in HubSpot, add a note to one, and read a contact's history while the caller is on the line.
Overview and use cases
- Save every new caller as a HubSpot contact with name, email, phone and company.
- Add a call note to the right contact after the conversation.
- Greet a returning caller with what HubSpot already knows about them.
Prerequisites
- A HubSpot account, and a HubSpot developer account to create the OAuth app. HubSpot no longer offers API keys (sunset in November 2022), so OAuth is the only way.
- The owner or admin role in Phynxa.
External account setup (in HubSpot)
HubSpot controls these screens; the wording may change. HubSpot's guide: HubSpot CRM API.
- In your HubSpot developer account, create an app for Phynxa.
- In the app's authentication settings, add the redirect URL shown in Phynxa's Connect dialog (copy it exactly).
- Add the scopes listed below.
- Copy the app's Client ID and Client secret.
Connect it in Phynxa
- Open Integrations and choose Connect on HubSpot.
- Paste the Client ID and Client secret.
- Continue to HubSpot, choose your account and approve.
- You return to Phynxa and the card shows Connected.
Permissions and settings
| Scope | Why |
|---|---|
crm.objects.contacts.read and crm.objects.contacts.write | Find, create and update contacts |
crm.objects.deals.read and crm.objects.deals.write | Deals (reserved for later use; not offered as an agent tool yet) |
tickets | Tickets (used by Create ticket) |
Use it in a call
On an agent's Tools tab, Add tool, Integration, HubSpot:
| Action | What it does | Runs |
|---|---|---|
| Create lead | Creates a contact from first name, last name, email, phone and company. | In the background |
| Add note | Adds a note. Give it the contact's id so it is attached to that contact; without one the note is not linked to a contact. | In the background |
| Fetch customer history | Reads a contact (by email or id) with their notes, tasks, deals and tickets. | Waits for the answer |
| Update contact | Changes a contact's name, email, phone or company; only what you give is changed. Needs the contact's id from a history lookup. | In the background |
| Create task | Creates a follow-up task for your team (subject, optional body and due_date like 2026-11-02), linked to a contact when you give its id. | In the background |
| Create ticket | Opens a support case with a subject and optional body, linked to a contact when you give its id. | In the background |
Test it
- In the card's ⋯ menu choose Test connection. Expect "HubSpot is responding."
- Attach Create lead to an agent, open Chat, say "My name is Sam Lee, email sam@example.com, phone +14155550100", and check HubSpot for the new contact.
Expected result
The contact appears in HubSpot within seconds, and the Integrations page counts a successful request.
Troubleshooting
- HubSpot says the redirect URL does not match. The URL in your HubSpot app must be exactly the one Phynxa showed.
- 403 or "missing scopes". Add the scopes above to the app, then Reconnect.
- Add note creates a note nobody sees. It had no contact id; use Fetch customer history first or make the prompt pass the id.
- The card shows Error. Choose Reconnect; the card shows HubSpot's reason.
Security and credentials
Your Client secret is stored encrypted and never shown again. The access Phynxa gets is limited to the scopes above on the account you approved. Remove deletes the saved connection and credentials; also revoke the app in HubSpot if you stop using it.
Related guides
Something here does not match what you see in the dashboard? Let us know.