Overview
Connect your HubSpot account with OAuth, then use Voiceflow’s built-in Create contact, Create lead and Create ticket tools. Voiceflow manages authorization for these tools; you can configure their inputs and capture their results directly in Agent studio.
The manual also covers additional workflows: contact lookup and updates through separately authorized API tools, approved public articles for Knowledge, and Service Hub messaging through a hosted relay. Set up those connections only for the workflow you need.
- Capture an enquiry — use the built-in contact or lead tool to save confirmed details.
- Record follow-up — use Create ticket with the intended pipeline, stage and owner.
- Recognize returning customers — add an API-tool lookup for the contact your application has authorized.
- Update customer details — add an API-tool phone update and verify the saved value.
- Import help articles — answer from approved public policies.
- Human agent hand-off — exchange messages with your Service Hub team through a deployed relay.
Studio
Use an editable test project and an administrator who can authorize the intended HubSpot account. Start with HubSpot in the tool picker after connecting. The contact-lookup, phone-update and support-relay sections explain their additional setup locally.
Code
Use Voiceflow APIs or CLI to configure and execute the same built-in HubSpot tools with the project’s OAuth connection. Browser authorization remains required. Additional API-tool, Knowledge and support-relay recipes have their own prerequisites.
Connecting HubSpot actions
Authorize the CRM account and prepare actions for your agent or backend.
Use a project you can edit and a CRM account authorized for the objects and fields the agent will access. A CRM administrator must approve the connection and any account-specific required fields. OAuth acts through the connected account; it does not authenticate the customer chatting with the agent.
Available HubSpot tools
These tools use the HubSpot account connected below. They do not require a separate HubSpot API token or an API tool.
Authorize and prepare actions
Studio
Open the CRM connection
Open your project in Agent studio. In the left sidebar, expand More, select Integrations, then choose Connect on HubSpot. Check which connection slot you are editing before authorization.
Authorize the intended account
HubSpot does not request a subdomain. Complete authorization in the provider’s browser window. Return to Voiceflow and check the connected account before configuring actions.
Choose and test an action
Return to Agent → Global tools → +, choose HubSpot, and select the required action. Write its Trigger, review the named inputs and configure Capture response for values needed later. Alternatively use an Integration step in a Workflow when the action must occur at a fixed point. Test in a dedicated project with records you can inspect; a Connected badge alone does not verify a write.
Code
The Code path also requires browser OAuth. Open Agent studio, select the project matching PROJECT_ID, open More → Integrations → HubSpot → Connect, and authorize the intended account. HubSpot does not request a subdomain. Return to the project and check the connection before resuming the commands below. The generic Connect integration API does not replace this OAuth flow.
Use a Voiceflow bearer credential with access to this project and test Environment. Keep it on your backend and set:
Install the Voiceflow CLI if you choose CLI; these commands read VF_TOKEN and request JSON output.
Read the available tools[].toolName, inputs and integrationToolID:
Use the standalone action examples in the following sections to test the connected account. For conversation use, follow Use CRM tools in an agent before opening the detailed attachment commands.
connectedreports stored credential keys, not provider acceptance. A Draft-only connection can run while this flag reads false.- Standalone calls use the selected Environment’s Draft and the project’s Draft integration slot, falling back to its Published slot.
- The literal-input boundary and provided-field alternative are described in Use CRM tools in an agent.
The connected account belongs to the project, rather than an independently isolated account per Environment. Use a dedicated test project when testing another CRM account. API-tool and support-relay credentials are configured only for those additional workflows.
Use CRM tools in an agent
Start with an agent that already handles a Draft conversation in the selected test Environment. Keep its existing Playbooks or Workflows registered while adding these tools.
Native input binding can interpret brace-shaped strings in agent arguments as well as standalone requests. JSON quoting and backslashes do not escape them. The nativeCRMInputs guard validates backend-prepared literal fields; a per-turn proxy cannot sanitize model arguments after the agent generates them. Use the provided-field Workflow path for untrusted text requiring enforced literal-data validation.
Studio
Choose where the action is available
In Agent → Global tools → + → HubSpot, add the action the agent needs. For a task limited to one Playbook, use that Playbook’s tool picker. Use an Integration step in a Workflow for a fixed sequence such as confirmation → write → result check.
Explain when to call it and bind its inputs
Open the attached tool and set its Trigger to the customer job, such as “Create a contact after the customer confirms a sales enquiry.” Let the agent collect the named customer details. Bind record IDs and administrator-approved routing values as provided inputs; require the agent to ask for confirmation. A Trigger guides the model; use the guarded Workflow sequence below when confirmation must be enforced before the action.
Use the current result in the answer
Use Capture response for values needed later. Return to Agent and use Run to start a conversation; the individual tool’s Run is a separate request test. Ask “Can I arrange a demo for 25 people?”, supply the missing details and confirm the request. Inspect the actual tool call and CRM record before the agent says it was saved. A failed call must use the support fallback.
Code
Attach each saved catalog action to target: {"global":true}, or to {"playbookID":"YOUR_PLAYBOOK_ID"} when it belongs to one Playbook. The attachment’s description supplies the invocation guidance shown as Trigger in Studio. Use the action-specific guidance below; creating or executing a catalog action does not make it available in a conversation.
Let the model collect customer details through declared required inputs with null defaults. Supply authorized record IDs and approved routing values through provided defaults. This direct attachment uses model instructions for conversational confirmation; a per-turn proxy cannot intercept its native tool call. For enforced confirmation, use the guarded Workflow sequence below instead of exposing the raw write. Compile the Draft and send a conversation to check actual selection, inputs and response. The full attachment commands are in Attach a connected CRM tool to an agent below.
Send “Can I arrange a demo for 25 people?” with missing details, then complete and confirm the request. Inspect the selected tool and current CRM result before the agent acknowledges capture. Repeat with a rejected write: the agent must explain that the request was not saved.
For Capture response, use contact.id, lead.id or ticket.id for these built-in actions. These paths start inside native data; the standalone response uses output.data.*. Keep created-record IDs separate from your authenticated identity variable.
For a fixed confirmation/validation sequence, create hubspot_write_confirmed and hubspot_action_result_id in More → Variables, with empty defaults (Code uses the variable-creation pattern in Recognizing customers). Have the developer provide a variable for each confirmed action input, such as hubspot_confirmed_firstname / hubspot_confirmed_lastname / hubspot_confirmed_email for Contact capture; use each selected action’s exact field names. The backend validates these fields with nativeCRMInputs and sets the approval variable to yes only for that server-recorded request; it clears approval before other turns.
At Workflow entry, clear hubspot_action_result_id. Add a Condition requiring hubspot_write_confirmed is yes; its Else path returns to confirmation without a write. On the matching path, run the Integration step with every input provided from its confirmed field or authorized ID/routing variable. Demonstrate that each variable is populated before testing the action.
Capture the current action’s ID into hubspot_action_result_id, using the capture path listed in this setup. Follow the Integration step with a Condition checking that result is not empty. Only a current ID proceeds to the capability’s saved-field check; the other path reports failure or an unverified outcome and reconciles before retry. Integration steps have no separate Failure path. Include the result variable as a real reference in the agent’s instructions so it can distinguish the outcome.
Attach that Workflow to the agent with a Trigger for the customer job, keeping the raw action off Global/Playbook tool lists. The direct attachment example below uses conversational model guidance; its Trigger does not enforce this gate.
Code
For the guarded path, create the graph through Workflow creation and attach its returned ID through Create tool as type: "workflow". Keep the confirmation variable provided by the backend, outside model-collected inputs. Standalone backend execution can check approval before calling execute; that check does not intercept calls from a directly attached native tool.
Capture paths are relative to the tool’s current response, not the standalone output envelope. Captures can retain an earlier value after a failure or missing field; a retained ID alone is not a success check. Use the current result and the capability’s completion check before answering, and clear retained outputs before a new attempt when your workflow relies on them.
Code
Attach a connected CRM tool to an agent
Prepare catalog selection, input bindings and Draft compilation.
These examples add hubspot_create_contact to an agent. Choose another discovered toolName for a different built-in action. This is separate from testing an action independently.
- Add the catalog action using API or CLI below; keep its returned
integrationToolID. - Save
hubspot-attachment.jsonusing this payload, replacingYOUR_RETURNED_INTEGRATION_TOOL_IDwith that returned ID:
- Create the attachment, resolve
unresolvedReferences, compile the Draft and test an agent conversation. Publishing remains a separate reviewed step.
Save {"toolName":"hubspot_create_contact"} as hubspot-catalog.json, then add it:
Keep the returned ID and fill the attachment file above before continuing:
After substituting the returned ID in the attachment file:
Inspect tool selection and the saved CRM record before publishing the reviewed Environment. Compilation does not publish.
Reconnect or stop using the account
Manage the connection without changing saved customer records.
Open More → Integrations, manage the provider’s connection and use Disconnect only when you intend to stop tools using that slot. Authorize the intended replacement account through the browser and rerun one controlled action. Disconnecting does not delete contacts, leads, tickets or cases already created. Review provider-side app access separately. Do not use disconnect as an automatic response to an action or validation error.
Capturing enquiries
Save confirmed contact details and an explicit qualification outcome.
Collect only the details needed for the enquiry, apply your explicit qualification rules, then ask the customer to confirm the saved details and follow-up request. Qualification is your business rule; a CRM create action does not decide whether someone qualifies.
Create lead creates a contact through HubSpot’s Contacts API. Its execution handler does not set lifecyclestage; do not rely on its name to assign the lead stage or to create a separate Leads object. When stage matters, use Create contact with the administrator-approved lifecyclestage value. lead_source is the action’s exact field name; confirm that this property exists and is writable in your account before using it.
In the conversation: Set the create tool’s Trigger to saving a sales enquiry after qualification and confirmation. Let the agent collect name, email and the enquiry; provide the approved lifecycle value when using Create contact. Retain the current contact ID and acknowledge only the saved enquiry; on rejection, explain that it was not saved. Test an incomplete demo request, then a confirmed one: the first must collect details and the second must create one inspected contact.
Save the confirmed enquiry
These illustrative inputs write to the connected account. Replace them with confirmed test data.
Studio
Add the create contact tool
In Agent → Global tools → + → HubSpot, choose Create contact. Use an Integration step in a Workflow when the action must run after a fixed confirmation or qualification gate.
Set the confirmed inputs
Use the field names and worked values above. Bind customer and record identifiers to your authorized application values; omit unrelated optional fields.
Run and capture the result
Use Run to exercise the action. Inspect data.contact.id in the result and retain the record ID with Capture response. Open that record in HubSpot and compare the saved values before reporting success.
Code
Save this confirmed request as hubspot-action.json before running it:
Require success: true, error: null and truncated: false. Keep output.data.contact.id from the result. Voiceflow HTTP success alone does not establish a successful CRM write.
Open that same record in the CRM and compare the saved values. Retain its ID with the customer and request. After an ambiguous timeout, reconcile the CRM record before retrying creation; these actions are not an idempotent upsert.
The example stage lead is a default HubSpot internal value; use the actual property option approved for your portal. Required account-specific properties can reject an otherwise valid request. An existing email may conflict with contact creation; use your permitted existing-contact mapping and update path rather than repeatedly creating it. Neither action sends a follow-up email, assigns a sales representative, books a meeting or creates a deal.
Use Create lead with its actual schema
Keep the saved record and source property distinct from lifecycle assignment.
Select Create lead for a contact creation that uses its lead_source input. Its required fields are the same name/email trio above. Through Code, execute hubspot_create_lead with those inputs and an optional account-approved lead_source; retain output.data.lead.id. Verify that actual contact and properties in HubSpot. Do not add hs_lead_source or an unsupported lifecycle input to that action.
Recording follow-up
Create a ticket in the pipeline and ownership your team will act on.
Create a ticket when your team needs a recorded follow-up request. A HubSpot administrator must supply the intended pipeline ID, a stage ID belonging to that pipeline and an active permitted owner ID. Use their internal IDs, not display names. See ticket properties and pipelines.
The action requires subject and content. It also accepts hs_ticket_priority (LOW, MEDIUM, HIGH), hs_pipeline, hs_pipeline_stage and hubspot_owner_id. Omitted/empty stage becomes 1; pass an explicit valid stage for a nondefault pipeline. The handler sets source_type to FORM. It does not supply a contact association, so retain the customer-to-ticket mapping in your application rather than assuming the email or subject creates one.
In the conversation: Set Create ticket to run when the customer confirms a follow-up request. Let the agent collect the subject and request details; provide the administrator’s pipeline, stage and owner IDs. Use the current ticket ID for later work and confirm the recorded request, without promising an email or an accepted assignment. Test a confirmed request and a rejected write; the agent must acknowledge only the successful ticket.
Create the routed ticket
These illustrative inputs write to the connected account. Replace them with confirmed test data.
Studio
Add the create ticket tool
In Agent → Global tools → + → HubSpot, choose Create ticket. Use an Integration step in a Workflow when the action must run after a fixed confirmation or qualification gate.
Set the confirmed inputs
Use the field names and worked values above. Bind customer and record identifiers to your authorized application values; omit unrelated optional fields.
Run and capture the result
Use Run to exercise the action. Inspect data.ticket.id in the result and retain the record ID with Capture response. Open that record in HubSpot and compare the saved values before reporting success.
Code
Save this confirmed request as hubspot-action.json before running it:
Require success: true, error: null and truncated: false. Keep output.data.ticket.id from the result. Voiceflow HTTP success alone does not establish a successful CRM write.
Open that same record in the CRM and compare the saved values. Retain its ID with the customer and request. After an ambiguous timeout, reconcile the CRM record before retrying creation; these actions are not an idempotent upsert.
Confirm the same ticket’s pipeline, stage, owner and content in HubSpot. A saved ticket is a follow-up record, not proof of email delivery or that a person has accepted the work. Tell the customer only what was saved and the contact expectation your team has approved. Use Create and route follow-up for the complete category workflow.
Recognizing customers
Retrieve the contact your application has authorized for this customer.
For a standalone contact lookup, configure the API tool in this section. The built-in HubSpot catalog exposes creation actions, so this additional read workflow needs its own provider credential. You can use the built-in create tools without setting up this lookup.
Studio
Obtain the authorized customer mapping
Have your application developer map the signed-in customer to the correct HubSpot Contact ID and account. A typed email or record ID is not proof of access.
Keep the mapping protected
The developer must supply the authorized ID on every turn and resumed session, prevent client identity overrides and retain runtime credentials server-side. Alternatively, a backend tool must authorize each operation. Ask them to demonstrate a later-turn override test before exposing customer data.
Code
Enforce the customer-to-record relationship on your backend for every operation. Keep the Voiceflow session userID separate from the CRM record ID.
- Retain runtime session credentials on a trusted backend proxy; accept only permitted customer actions.
- Discard client-supplied variables, state, user IDs and session keys. Rebuild the CRM ID from the authenticated customer/tenant map on every forwarded turn and resumed session.
- Do not expose direct browser runtime access. Alternatively, enforce the same record authorization inside each backend tool.
An initial launch binding alone is insufficient: later runtime requests can replace session variables. A tool Trigger does not enforce authorization.
A CRM administrator must provision a separate API credential for this request. For HubSpot contact reads, grant crm.objects.contacts.read; add crm.objects.contacts.write only for the update below. Follow HubSpot app authentication.
In the conversation: Set the lookup’s Trigger to questions about the signed-in customer’s saved profile. Provide the Contact ID from the authenticated application; the agent must not collect it from chat. Use only approved fields from the current matching record; missing mappings or failed reads use general help. Test “What phone number do you have for me?” and a request for another customer: only the permitted record may inform the answer.
Prepare the contact lookup
Studio
Prepare the trusted inputs
In More → Secrets, create hubspot_api_token with the administrator’s test token. Creating a default also sets Main’s Published value, so use a test project; set an override for the intended Environment/version when needed. In More → Variables, create hubspot_contact_id with an empty default. Your backend proxy supplies the authorized record ID on every interaction and prevents direct client access to the runtime credentials. Have the application developer demonstrate a later-turn variable-override test before exposing this lookup to customers.
Configure the API request
Open Agent → Global tools → + → API. Create Find HubSpot customer, select GET, and enter https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}?properties=firstname,lastname,email,phone,lifecyclestage. Add Authorization: Bearer {token} and Accept: application/json.
Bind the credential and customer ID
Save the request and return to Agent → Global tools. Click the lookup tool, then the token row under Input variables. Set Default value to hubspot_api_token using the Secrets picker. Open the contact_id row and select hubspot_contact_id from Variables. Click outside to save. The contact_id row should show Value provided; reopen token to check its Secret reference.
Test permitted records
Run with one authorized test record. Inspect id and properties.firstname, properties.email, properties.phone and capture only the fields the customer may see. Test a missing mapping and a record belonging to someone else; neither may expose another customer. A provider 404 is not permission to create a replacement contact automatically.
Code
Use the Voiceflow credential and test Environment from Connecting CRM actions. Set CRM_CONTACT_ID to a record your backend has authorized. Use a fixed approved provider host; do not accept an arbitrary URL from the conversation.
Save hubspot-lookup.json with this definition:
In a dedicated test project, create the credential and identity variable before binding them. These calls use the same Voiceflow bearer header as above:
Secret creation writes the project default and Main’s Published value. Save secret.id; use Secret value configuration to set the intended Draft and Published overrides separately. The connection used by native CRM actions does not expose a token for this API request.
Save apiTool.id as API_TOOL_ID, then inspect inputs and execute:
Require success: true, error: null, truncated: false, provider output.status: 200 and the expected output.body record. Check id and properties.firstname, properties.email, properties.phone. An HTTP 200 from Voiceflow alone is not a successful contact read.
For an agent attachment, list variables[] above and match each name to its id. Save the following as hubspot-lookup-attachment.json, replacing all three IDs:
POST it to /v2/stable/tool with the same query and bearer header, or run vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json < hubspot-lookup-attachment.json. Resolve unresolvedReferences before testing. Creating an API tool alone does not attach it.
Your backend proxy supplies variables: {"hubspot_contact_id":"AUTHORIZED_CRM_CONTACT_ID"} on the initial launch and every subsequent turn, using the authenticated application session’s server-side mapping. Do not forward a browser-supplied mapping or runtime session key. The trustedCustomerTurn helper accepts only launch/text for this workflow, discards client overrides and rebuilds protected variables; its fixture tests exercise a later-turn override. Integrate it behind your existing application authentication, keep runtime credentials server-side, and send only its returned action/variables through the Chat interaction contract. Reject missing/untrusted mappings rather than forwarding the turn. Compile the Draft, run an authenticated test conversation, then configure Published credentials before publishing.
If credentials expire, refresh or replace them through the credential owner; do not retry with another customer’s record. Use HubSpot contact retrieval or Salesforce sObject Rows for the provider contract. This lookup does not return every account, deal or support case associated with that person.
Updating customer records
Change an agreed phone number on the existing contact.
The built-in HubSpot catalog does not include an Update contact action. Use this additional API-tool recipe when your workflow needs to change an existing contact.
Use the permitted contact ID from Recognizing customers. Ask the customer to confirm the new phone before changing it. This worked request changes only phone; it does not update arbitrary properties or move a lifecycle stage backward.
In the conversation: Let the agent invoke Update confirmed HubSpot phone, the gated Workflow below, when the customer asks to change their number. Let the agent collect the proposed number; the backend validates confirmation and supplies hubspot_confirmed_phone with the protected Contact ID. Report success only when the current readback matches; an uncertain write requires reconciliation before retry. Test an unconfirmed number and a confirmed change: the first must not write and the second must update the same Contact.
Save and read back the phone
Studio
Add the phone update request
Create a saved API request named Update HubSpot phone in Tools. Keep it off agent and Playbook tool lists; the gated Workflow below owns its execution. Choose PATCH and enter https://api.hubapi.com/crm/v3/objects/contacts/{contact_id}.
Bind identity and credentials
Use the lookup’s Bearer-token header and trusted Contact ID binding. The separate token needs crm.objects.contacts.write as well as read access. Set the JSON body to {"properties":{"phone":"{phone}"}}.
Validate, confirm and check the saved value
Create hubspot_confirmed_phone in More → Variables with an empty default. Have the developer supply it through trustedCustomerTurn only from a server-recorded confirmed change. In the Workflow’s API step, bind phone to that provided variable, alongside the protected Contact ID and Secret. Before execution, use your Workflow or backend to require confirmation and validate a leading + followed by 8–15 digits, such as +14165550123. Do not interpolate quotes, braces or unvalidated free text into the body.
Run once and inspect the contact ID and phone in the result. Use Find HubSpot customer on the same ID to compare the saved phone with the confirmed number.
Code
Use the API-token and identity prerequisites from Recognizing customers, with contact Write access. Save this as hubspot-update-phone.json:
Create it through /v2/stable/api-tool or vf api-tool create as above, saving its new apiTool.id as PHONE_TOOL_ID. List its input variables for the Workflow. Its API step provides token from {hubspot_api_token}, contact_id from {hubspot_contact_id} and phone from {hubspot_confirmed_phone}, each with required: false. Do not create a direct Global or Playbook attachment for this write. Use the actual phone input ID in apiToolInputVariableID. The saved lookup tool ID is a different resource.
Create hubspot_confirmed_phone with an empty default using the variable-creation pattern in the lookup. On every turn, your backend calls trustedCustomerTurn with the server-recorded confirmed phone change as its optional third argument; the helper validates the number and clears it when no change is prepared. Do not pass browser confirmation flags through. The agent must not supply the raw JSON phone input. For a standalone test, validate phone with ^\+[1-9][0-9]{7,14}$ before executing; reject other text. Save:
POST this body to /v1/stable/api-tool/$PHONE_TOOL_ID/execute using the Voiceflow bearer header and project/Environment query. Require success: true, no execution error/truncation, provider status 200, the expected output.body.id and output.body.properties.phone. Then execute the GET lookup again for that same record, including phone in the requested properties, to verify persistence.
The downloadable request builders validate record IDs and this phone format and construct JSON without interpolating customer text. Their local fixture tests demonstrate serialization; they do not verify a live account. Direct provider calls in that module use the separately provisioned provider token, not your Voiceflow bearer credential.
On a write timeout, read the same contact before deciding whether a retry is needed. A failed read does not mean the write failed. Lifecycle changes and account-specific fields need their own administrator-approved property mapping; the generic contact API’s breadth is not a list of prebuilt Voiceflow actions.
Use the confirmed-change Workflow
Expose Update confirmed HubSpot phone to the agent, keeping the raw PATCH request inside that Workflow. Its entry clears previous readback values and checks that the protected Contact ID and backend-confirmed phone are both nonempty. The result is not_run without confirmation, updated after matching readback, or unverified after failure/mismatch. A Trigger does not enforce these checks.
Studio
Create the guarded Workflow
Create a Workflow named Update confirmed HubSpot phone. Create hubspot_phone_update_result, hubspot_returned_contact_id and hubspot_returned_phone with empty defaults. At entry, use a Set step to set the result to not_run and clear both returned fields. Add a Condition with Match all: hubspot_contact_id is not empty and hubspot_confirmed_phone is not empty. Enable Else path; leave that branch returning without a write.
Write, read back and check the same record
On the matching path, add an API step selecting Update HubSpot phone, with the three provided inputs above. Keep Async execution off. Follow it with the saved lookup, binding the same Contact and Secret. Capture id into hubspot_returned_contact_id and properties.phone into hubspot_returned_phone. Enable Failure path on both API steps and connect each Failure branch to a Set step that records unverified.
Add a second Match all Condition comparing those returned fields with the protected Contact ID and confirmed phone. A match sets hubspot_phone_update_result to updated; Else path sets unverified. Let those final paths return to the agent; an End step would end the whole conversation.
Attach it and explain the result to the agent
Add the Workflow to the agent and set its Trigger to a signed-in customer’s phone-change request. In the agent’s instructions, insert hubspot_phone_update_result through the Variables picker and explain: updated confirms the change, not_run asks for confirmation, and unverified requires checking the saved record before retrying. The Trigger’s wording alone does not insert the current result into model context.
Test without confirmation, with a confirmed valid number, and with a readback failure. Inspect the taken path and the agent’s answer. Use the original confirmed number in the answer: scalar captures can normalize numeric-looking strings and remove the leading +.
Code
Alongside the existing Contact ID and confirmed-phone variables, create hubspot_phone_update_result, hubspot_returned_contact_id and hubspot_returned_phone using the lookup’s variable-creation pattern. Download the gated Workflow JSON and Workflow attachment. Replace their fictional resource IDs using the table in the disclosure below. The graph resets outputs, gates the write, connects both API failures and checks current readback before setting updated.
Add a real reference to {hubspot_phone_update_result} in the agent’s instructions, preserving its existing instructions. Explain the three outcomes above and the confirmation/reconciliation response. The Workflow attachment description controls selection; it does not interpolate this result. Compile the Draft and test the customer conversation with the backend’s trustedCustomerTurn boundary, including missing confirmation and a failed readback. The attachment/creation commands below prepare resources; they do not verify live CRM execution.
Create and attach the gated phone Workflow
Map returned resources, preserve instructions and compile the Draft.
Replace each fictional ID in the downloaded Workflow:
Save the mapped files as phone-workflow.json and phone-attachment.json.
Replace dddddddddddddddddddddddd in the attachment with returned workflow.id, then attach:
Append the result instruction to the retrieved Markdown, preserving other instructions. This command prepares a local update file; review it before applying:
These use POST /v1/stable/workflow, POST /v2/stable/tool and PATCH /v2/stable/agent with the same project/Environment query and bearer header. Resolve unresolvedReferences, including the result variable, before testing. Create an attachment once; remove an old ungated tool attachment while retaining its saved API request. Configure the intended Published Secret value before publishing separately.
Import help articles
Use approved public HubSpot articles as a Knowledge source.
Use approved public help articles from HubSpot as Knowledge. The URL-import recipe is separate from CRM authorization and customer records. A content owner must provide public article URLs and approve their audience; do not import private contacts, cases or conversations into a general agent’s Knowledge.
Import and verify an article
Studio
Choose the public source
Confirm the article is readable while signed out and contains the approved policy. In your project, open Knowledge base → Add data source → Web page(s) and paste its public URL. Import the page and wait for processing to complete.
Inspect and exercise the content
Open the imported article and compare it with the source. Enable Knowledge on the agent and use Run to ask two questions it answers and one it does not. Inspect the retrieved source and configured fallback. Assign an owner and refresh schedule; a listed URL does not establish indexing or continuing synchronization.
Code
Use the bearer credential and test Environment prepared above. Set ARTICLE_URL to the approved public article, then import it:
Inspect the returned document identifier, then list documents with GET /v1/stable/document using the same host, bearer header and query. Match the imported URL in documents[], retain its id and wait for status.type: "SUCCESS"; inspect an ERROR before retrying. PENDING or INITIALIZED is not completion.
Run a Knowledge diagnostic query for a known article question and compare its chunks with the source. Also run a Draft conversation to check the actual answer and fallback; diagnostic retrieval alone is not runtime acceptance. Publish the reviewed Environment and repeat in a fresh customer session.
Keep imported articles current
Reimporting the same URL can change content used by other Environments and Published agents, even when you select a test Environment. Use a dedicated test project for isolated recrawl experiments.
Studio
Choose a refresh schedule
Assign a content owner. In Knowledge base, select the URL source and set its Refresh rate to Never, Daily, Weekly or Monthly where available.
Replace and verify approved content
For an immediate update, reimport the same approved URL and confirm replacement. Recheck processing, article text and agent answers. For a new URL, import and verify it before deleting the retired source.
Remove a retired source
Select the retired Knowledge source and use Delete after checking which answers rely on it.
Code
For an immediate recrawl, repeat POST /v1/stable/document/url with the same approved url, the intended refreshRate, and overwrite=true in the query, alongside the same project and Environment. This deliberately replaces the existing same-URL document; wait for processing and compare content before relying on it. URL content cannot be replaced through the text-document update body.
For a changed URL, create and verify the new URL document first. List/read the old source to confirm its ID and dependencies, then DELETE /v1/stable/document/$RETIRED_DOCUMENT_ID?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT using the same bearer credential. Verify that the retired source is absent and the replacement answers the intended questions. Check other retrieval flows before deletion; it removes this source from the selected Draft’s Knowledge.
Use Importing data sources for the shared refresh controls and URL document creation for the exact reimport contract. This recipe imports a public URL; it does not connect a managed CRM article source or synchronize private CRM data.
Human agent hand-off
Connect the customer conversation to a Service Hub teammate.
Keep the customer in Voiceflow Chat while a Service Hub teammate replies through a developer-hosted relay. This connection is separate from the built-in CRM record tools.
Prepare the support workspace
Studio
Ask your HubSpot administrator and integration developer to prepare a tested Service Hub relay before configuring Voiceflow. Share the Code setup with them, then obtain:
- The deployed HTTPS Base URL and Auth header name/value.
- A separate callback Webhook secret of at least 32 characters.
- An approved Queue ID mapped to the intended support destination.
Have them demonstrate a customer message, a human reply and conversation closure in that destination. The CRM tool connection does not provide this messaging relay.
Code
Register the Custom Channel
Have the HubSpot administrator create an OAuth app with Custom Channels access. Register the channel and its outgoing-message webhook, then connect a channel account to the approved inbox. Select integration-managed threading (INTEGRATION_THREAD_ID).
Grant the app these scopes:
conversations.custom_channels.readandconversations.custom_channels.writefor channel messages.conversations.readfor thread and actor reads.conversations.writefor thread closure.
Follow Custom Channels setup and the current official OpenAPI contract. The CRM OAuth connection does not register these resources.
Keep the provider identifiers
Obtain the channel ID, string channel-account ID, inbox/destination and installed app token. Store the relay connection ID separately from the returned HubSpot thread ID.
Approve human support senders
Have a known teammate send a public test reply. Retain its senders[].actorId, then GET /conversations/v3/conversations/actors/{actorId} using conversations.read.
Ask the administrator to confirm the actor belongs to an approved human support user and store that ID in the relay allowlist. Account-agent actors use A-; Customer Agent actors use L-. Verify the actor and account rather than accepting a prefix alone. Deny unknown or automated actors until reviewed. See actor lookup.
Prepare and test the relay service
Prepare Node.js 22 or later, HTTPS hosting, durable tenant-scoped storage, a per-conversation queue and an outbox. Download server.mjs, protocol.mjs and test.mjs from the common starter, including its Chatwoot module required by that test bundle. Run node --test test.mjs locally. These tests exercise fixtures, not HubSpot Service Hub.
Configure secrets and callbacks
Implement the provider mapping in the disclosure below and authenticated event ingestion. The shared starter’s mock mode is not a HubSpot Service Hub adapter.
Store these values outside source control:
HANDOFF_TOKEN,EVENT_TOKENandWEBHOOK_SECRET.VOICEFLOW_PROJECT_IDandVOICEFLOW_WEBHOOK_URL.
Voiceflow receives signed callbacks at https://general-runtime.voiceflow.com/handoff/webhook/custom. Provider notifications go to your service’s own receiver. The service must implement the shared create, customer-message and end operations; see the connection contract.
Connect and route the handoff
Studio
Connect the deployed relay
In Agent studio, open More → Integrations → Custom Handoff → Connect. Enter the supplied Base URL, Auth header name, Auth header value and Webhook secret.
Map the customer and destination
Create an escalation Workflow and add a Handoff step. Choose Custom Handoff, map the verified customer identity, name and email, and set the supplied Queue ID. The developer must map this key to the correct Service Hub destination.
Choose context and continuation
Set Handoff context to Full transcript, a Custom summary or None. Populate a custom summary variable before the step. Send only information that support staff may see.
- Enable Failure path and connect an unavailable-support fallback.
- Enable Return path and connect the desired continuation. An enabled, unconnected return resumes the parent agent; a disabled return ends the session.
Make escalation reachable
Attach the Workflow to the agent and describe when it should run. Publish to a test Environment and point a fresh Voiceflow Chat widget session at it before the checks below.
Code
Connect the deployed relay through the direct Custom Handoff configuration API. Use the Voiceflow credential with integration-create and Environment-update access; provider credentials and relay tokens are separate.
Connect the relay
POST /v1/stable/integration/custom_handoff?projectID=$PROJECT_ID with integration: "custom_handoff" and credentials containing baseUrl, authHeaderName, authHeaderValue and webhookSecret. Use the relay URL, outbound header and separate callback secret above. This writes the project’s default connection; it does not select a Draft slot. List integrations and check custom_handoff.connected without treating it as delivery acceptance.
Create the escalation Workflow
Create a fallback message and an escalation Workflow in the test Environment. Use a Handoff step with config.provider: "custom", trusted endUserId, userEmail, customerName, userLanguage and your mapped queueId; set handoffContext, returnPath and failPath, and connect the failure port. The complete configuration artifact supplies the schema and resource creation order.
Attach and compile the Workflow
Read the agent’s current workflows and instructions, append the new escalation without deleting existing entries, and PATCH only the intended fields. Creating a Workflow does not make it reachable. Compile and test before publishing to the test Environment.
Implement the customer Chat client
Implement the Chat handoff client: register Socket.IO listeners before connecting; resume the existing user, Environment and sessionKey with client.start; wait for client.started with newSessionRequired: false. Render action.trace handoff events and send customer text with action.send / action.type: "live-agent-handoff". An HTTP streaming response alone does not receive asynchronous human replies.
The shared contracts remain in Developers; this manual owns the HubSpot Service Hub mapping. Verify the published customer channel before routing real customers.
Verify the complete conversation
With a test customer and a Service Hub teammate:
- Escalate once. Confirm one conversation appears with the correct customer, destination and permitted context.
- Send a customer message and a public human reply. Each must arrive once in the other interface.
- Add a private note and an automated reply. Neither may appear as a human response. This recipe supports text only; files must be rejected rather than silently dropped.
- Send a final human reply and close immediately. The reply must arrive before the configured Return path runs.
- Have the integration developer replay an event and test an unknown sender. Confirm that neither produces duplicate or unapproved customer messages.
- Have the developer make the test relay unavailable while you verify the Failure path.
A saved connection or a simulated reply is not proof that the published customer channel works.
Code
Implement the HubSpot relay mapping
Translate customer messages, human replies and closure for the configured provider.
Implement create(request, connectionId) and subsequent customer message calls with POST /conversations/v3/custom-channels/{channelId}/messages at https://api.hubapi.com, using the installed app’s Bearer token. Use the stable relay connection ID as integrationThreadId; keep the provider’s returned conversationsThreadId separately. The current request envelope is:
Replace every example identity/ID and the timestamp. Sender and recipient delivery types must match the channel’s configured capabilities. Reuse the same idempotency ID only for a retry of that message; create a new one for new content. Return the relay connection ID to Voiceflow, not the HubSpot thread ID. Keep escalation context separate from public customer text.
Receive human replies
Receive OUTGOING_CHANNEL_MESSAGE_CREATED at the registered webhook. Verify the request against the app’s client secret using the algorithm for X-HubSpot-Signature-Version and the raw request bytes; follow HubSpot request validation. Resolve channelIntegrationThreadId and the channel/account to the active mapping. Where the notification provides an ID, retrieve that message using the Custom Channels message GET before deciding what to deliver.
Accept only an actual public outgoing MESSAGE whose sender’s actor ID is in your approved human-support actor allowlist. Reject missing/unknown actors, customer echoes, notes, system/integration senders and Breeze/other automated senders; direction alone is insufficient. Deduplicate the provider message ID. Send a normalized message.received with the relay conversation ID, provider event ID/time, public text and human agent.name through the signed callback protocol. Persist and queue before acknowledging the provider.
Close without losing the final reply
Implement end by PATCHing /conversations/v3/conversations/threads/{threadId} with {"status":"CLOSED"}. For human-side closure, a bounded worker can read the same thread and detect CLOSED. Serialize polling and message ingestion for the thread: drain/reconcile pending outgoing messages before sending one conversation.ended, then stop the worker. Polling independently and closing first can lose the human’s final reply. Do not invent a Custom Channels closure webhook.
Serialize work per active conversation and keep tenant-scoped mappings until delivery completes. Persist messages before acknowledging the provider, use an outbox and bounded retries, and reconcile pending replies before closure. Deduplication alone does not preserve message order. After an ambiguous create timeout, reconcile the existing conversation instead of creating another session.
Replies or closure are missing
Trace the active session and event receiver before reconnecting accounts.
Studio
- Check that the test widget uses the intended Published Environment and that the Handoff step has the approved Queue ID and Return/Failure paths.
- Record the test time, conversation reference and which message or return was missing. Give that evidence to the integration developer.
- Ask the developer to trace provider delivery and relay callbacks before reconnecting the account. Use Handoff troubleshooting for shared runtime recovery.
Code
Check provider delivery/subscription logs, tenant and conversation/session mapping, human-sender filtering, callback signature and the customer client’s resumed session in that order. A 401 requires credential/signature repair; rate limits require bounded backoff. Keep provider and Voiceflow callback secrets distinct. If the provider accepted a write but the response was lost, reconcile it before retrying. Use Handoff troubleshooting for shared runtime recovery.