> For the complete documentation index, see [llms.txt](https://docs.screendesk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.screendesk.io/helpdesk-integrations/hubspot/chatbots-and-agents.md).

# Chatbots and Breeze

Let a HubSpot rule-based chatbot or Breeze Customer Agent send a recording link and check when the customer has submitted it.

A HubSpot chatbot or Breeze Customer Agent can offer a **Record your screen** link during a chat, then check that the customer submitted the recording when they come back. The recording is saved in Screendesk and added as a note on the customer's HubSpot contact.

{% embed url="<https://app.screendesk.io/recordings/4352a2b9-74ea-4d52-8522-dd8ea684cbcb>" %}

1. The bot sends Screendesk the customer's contact or email. Screendesk returns a recording link.
2. The bot shows it as **Record your screen**. The customer records in a new tab and submits.
3. When the customer says they're done, the bot checks the request and confirms only once Screendesk reports `received`.

**You need:**

* HubSpot connected to the workspace (see [Install and set up](https://docs.screendesk.io/helpdesk-integrations/hubspot/install-and-set-up.md)), and a Screendesk admin to create the token.
* An identified customer: the email must match exactly one existing HubSpot contact. Screendesk doesn't create contacts.
* For a rule-based chatbot: HubSpot **Data Hub Professional or Enterprise**, which the **Run a code snippet** action requires.
* For Breeze: a HubSpot subscription with Customer Agent actions and permission to edit the agent. See [HubSpot's requirements](https://knowledge.hubspot.com/customer-agent/set-up-actions-for-the-customer-agent).

## 1. Create the chatbot token

1. In Screendesk, open **Settings → Integrations** and click **Configure** on the HubSpot card.
2. Under **Let customers record on their own**, click **Create chatbot token** in the **Chatbot and Breeze token** row.
3. Click **Copy** and add it to HubSpot right away (step 2 or 3 below). It's only shown once.

   <figure><img src="https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FoUBTMQBvINZaALTIuufn%2Fdocs-dialog-hubspot-token.png?alt=media" alt="The chatbot token in the HubSpot settings, shown once"><figcaption></figcaption></figure>

The token can only create recording requests and check them. It isn't a general API token, and a regular Screendesk API token won't work in its place. Keep it in HubSpot's server-side settings, never in a chat message, a URL or website code.

Each workspace has one token:

* **Replace token** issues a new one and stops the old one at once, along with its unfinished recording links. Update HubSpot straight after.
* **Revoke token** stops it. Actions that use it fail until you create a new one.
* The token also stops working if the admin who created it leaves the workspace or becomes **Watch only**. Another admin can replace it.

## 2. Rule-based chatbot

1. In HubSpot, open **Service → Chatflows** and edit your chatbot.
2. After the step where the customer describes the problem and gives their email, click **+** and choose **Run a code snippet**. HubSpot doesn't offer it directly after the welcome message: add a question first.
3. Name it, for example **Request a Screendesk recording**, and select **Node 24.x**.
4. Paste the code below. If the editor offers secrets, add the token as `SCREENDESK_HUBSPOT_BOT_TOKEN`. Otherwise replace `REPLACE_WITH_HUBSPOT_CHATBOT_TOKEN` with the token, in this editor only.
5. Save, and connect the action's next step to your usual troubleshooting or human handoff. The bot moves on once the recording is received, skipped or expired, or if Screendesk can't be reached.
6. Preview with a test contact whose email you control (HubSpot previews perform real actions):
   1. Reach the action and check that **Record your screen** appears.
   2. Click **I've sent my recording** before recording. The bot should keep waiting.
   3. Open the link, submit a short recording, return and click **I've sent my recording** again. The bot should confirm.
   4. Check the test contact's timeline for the Screendesk note.
   5. Run it again with **Continue without a recording** and check that support continues.

```javascript
// HubSpot chatflow "Run a code snippet", Node.js 24.
// Configure this only in HubSpot's server-side editor. Never ship the token in
// your website, chat widget JavaScript, a URL, or the message sent to a visitor.
const axios = require('axios');
const BASE_URL = 'https://app.screendesk.io';
const BOT_TOKEN = process.env.SCREENDESK_HUBSPOT_BOT_TOKEN || 'REPLACE_WITH_HUBSPOT_CHATBOT_TOKEN';
const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (character) => ({
  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
})[character]);

exports.main = async (event, callback) => {
  const state = event.customState || event.session?.customState || {};
  const requestId = state.screendeskRequestId;
  const reply = event.userMessage?.message;
  const cancelled = reply === 'Continue without a recording' || reply === 'skip_recording';
  if (cancelled) {
    callback({ botMessage: 'No problem. Let’s continue here.', responseExpected: false, customState: state });
    return;
  }

  try {
    if (BOT_TOKEN === 'REPLACE_WITH_HUBSPOT_CHATBOT_TOKEN') throw new Error('Missing configuration');
    const options = { headers: { Authorization: `Bearer ${BOT_TOKEN}` }, timeout: 15000 };
    const endpoint = `${BASE_URL}/api/v2/hubspot/recording_requests`;
    const response = requestId
      ? await axios.get(`${endpoint}/${encodeURIComponent(requestId)}`, options)
      : await axios.post(endpoint, {
        contact_id: event.session?.vid,
        customer_email: event.session?.properties?.CONTACT?.email?.value
      }, options);
    const result = response.data;
    const nextState = { ...state, screendeskRequestId: result.request_id };

    if (result.status === 'received') {
      callback({
        botMessage: 'Thanks, your recording has been received. Let’s continue here.',
        responseExpected: false,
        customState: nextState
      });
    } else if (result.status === 'expired') {
      callback({
        botMessage: 'That recording link has expired. Please ask our support team for a new one.',
        responseExpected: false,
        customState: nextState
      });
    } else {
      callback({
        botMessage: `<a href="${escapeHtml(result.recording_url)}" target="_blank" rel="noopener noreferrer">Record your screen</a><br>Return to this chat after sending your recording.`,
        quickReplies: [
          { value: 'recording_sent', label: 'I’ve sent my recording' },
          { value: 'skip_recording', label: 'Continue without a recording' }
        ],
        responseExpected: true,
        customState: nextState
      });
    }
  } catch {
    callback({
      botMessage: 'I couldn’t check the recording right now. We can continue with your support request here.',
      responseExpected: false,
      customState: state
    });
  }
};
```

If you change the code, keep two things:

* `screendeskRequestId` in `customState`. Without it, the customer's next reply creates a new request instead of checking the one they were shown.
* The HTML link. HubSpot's chat widget shows Markdown links such as `[Record your screen](...)` as plain text.

## 3. Breeze Customer Agent

You add two custom API actions in HubSpot: one sends the link, the other checks it. Open **Customer Agent → Train → Actions** (under **Service** or **Agent Hub**, depending on your navigation) and add a custom API action.

### Action 1: request a recording

1. Under **Describe the action**, enter:

   | Field                   | Value                                                                                                                              |
   | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
   | Name                    | `Screendesk — request a recording`                                                                                                 |
   | Description             | `Offer a secure Screendesk recording link when a customer needs to show a visual issue. Use their verified HubSpot contact email.` |
   | Action protection level | **Verify email**                                                                                                                   |
   | Trigger phrases         | `I want to send a screen recording`, `Can I show you the problem?`                                                                 |

   <figure><img src="https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FJM6yD6KC0rNYN0pzy7Ce%2Fhubspot-breeze-request-describe.png?alt=media" alt="Request action with Verify email protection and trigger phrases"><figcaption></figcaption></figure>
2. Under **Define required inputs**, add `Customer email` with the instructions: `The verified contact email of this customer. Use the email already known in this conversation; never invent an email.`
3. Under **Configure API**, set:

   | Field          | Value                                                         |
   | -------------- | ------------------------------------------------------------- |
   | Method         | **POST**                                                      |
   | Endpoint       | `https://app.screendesk.io/api/v2/hubspot/recording_requests` |
   | Authentication | **API Key**                                                   |
   | Body parameter | Key `customer_email`, property **Customer email**             |

   If HubSpot shows `https://` beside the endpoint field, leave it out of what you type.
4. Open the secret manager beside the API Key selector, add a secret named `SCREENDESK_HUBSPOT_BOT_TOKEN`, paste the token as its value and select it. Don't add `Bearer` in front: HubSpot sends the value as it is.

   <figure><img src="https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2Fdtd4bCBLVmTGXIeZWQeQ%2Fhubspot-breeze-request-api.png?alt=media" alt="Request action using the token secret and mapping customer_email"><figcaption></figcaption></figure>
5. Paste these **Response instructions**:

   ```
   Present recording_url as a clickable hyperlink with the visible label "Record your screen". Use Markdown link syntax: [Record your screen](recording_url), substituting the exact URL returned by the API as the destination, including every query parameter.

   Do not display the raw URL, shorten it, or invent a different destination. Tell the customer to open the link, send their recording, and return to this chat. Keep the exact link destination in the conversation for the completion-check action.

   Do not claim a recording was received yet. Do not expose credentials or internal fields. On API error, continue support or hand off to a person.
   ```

### Action 2: check the recording was received

1. Add a second custom API action:

   | Field                   | Value                                                                                                                               |
   | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
   | Name                    | `Screendesk — check recording received`                                                                                             |
   | Description             | `Check the exact Screendesk recording link already offered in this conversation when the customer says they have sent their video.` |
   | Action protection level | **Verify email**                                                                                                                    |
   | Trigger phrases         | `I have sent my recording`, `Did you receive my screen recording?`                                                                  |
2. Add the required input `Recording link` with the instructions: `Use the exact Screendesk recording URL already offered in this conversation. Do not ask the customer for an internal request ID or guess a link.`
3. Under **Configure API**, set:

   | Field           | Value                                                                |
   | --------------- | -------------------------------------------------------------------- |
   | Method          | **GET**                                                              |
   | Endpoint        | `https://app.screendesk.io/api/v2/hubspot/recording_requests/status` |
   | Authentication  | **API Key**, the same `SCREENDESK_HUBSPOT_BOT_TOKEN` secret          |
   | Query parameter | Key `recording_url`, property **Recording link**                     |

   Use a query parameter here, not a body parameter.

   <figure><img src="https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FYUwmGN6jqDoeOku1oFRh%2Fhubspot-breeze-completion-api.png?alt=media" alt="Completion action mapping recording_url as a query parameter"><figcaption></figcaption></figure>
4. Paste these **Response instructions**:

   ```
   Only acknowledge receipt when status is received. If pending, ask the customer to finish uploading and return. If expired, offer to request a new recording link.

   Never claim to have watched or understood the video. Never claim delivery to HubSpot unless delivery_status is delivered. Do not display staff report URLs or internal fields.
   ```

### Test both actions

1. In the request action, click **Test API** with a test contact's email. Expect **201**, `status: pending` and a `recording_url`.
2. In the check action, test with that exact URL as **Recording link**. Expect **200** and `pending`.
3. Open the URL, submit a short recording, and test the check action again. Expect `received`, then check the contact's timeline for the note.
4. Open each action's own **Preview** tab, next to **Setup**, with a contact whose email you control. HubSpot's general agent tester may not offer unpublished actions. Ask to send a recording, complete the email verification, submit, and say you've sent it.
5. Before you deploy, check that one conversation uses both actions, and that the agent reuses the earlier link instead of asking the customer to paste it.

## Where the recording goes

Both setups above put the note on the customer's **contact** timeline. They don't guess the contact's latest ticket. If your integration knows the right ticket, send its `ticket_id` when creating the request: the note then goes on that ticket and, with **Mark the tickets** on, the ticket's **Screendesk activity** property gets **Recording received** (see [Analytics](https://docs.screendesk.io/helpdesk-integrations/hubspot/analytics.md)).

The check returns two fields:

* `status`: `pending` (not submitted yet), `received` (saved in Screendesk) or `expired` (unused after 24 hours).
* `delivery_status`: whether the HubSpot note has been added: `not_started`, `pending`, `delivered` or `failed`. `received` with `pending` delivery is normal for a moment; don't ask the customer to record again.

## If it doesn't work

* **401**: the action isn't using the chatbot token. Check that it's the current token (not a Screendesk API token or a HubSpot key), that `Bearer` isn't added in Breeze, and that it wasn't replaced or revoked.
* **409**: the workspace isn't connected to HubSpot.
* **422, "must match one HubSpot contact"**: the email doesn't match exactly one contact. Collect or verify the email before the recording step.
* **The bot stays pending**: the customer stopped recording but didn't submit, or the check is using a different link. In the rule-based bot, keep `screendeskRequestId` in `customState`.
* **The link has expired or no longer opens**: links last 24 hours and stop when the token is replaced or revoked. Create a new request; don't edit the URL.
* **Breeze asks the customer to verify their email**: expected with **Verify email** protection.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.screendesk.io/helpdesk-integrations/hubspot/chatbots-and-agents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
