> 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/breeze-customer-agent.md).

# Breeze Customer Agent

Configure two Breeze Customer Agent actions to request a recording and confirm when it has been received.

{% hint style="info" %}
**Development preview.** The actions shown here are saved as drafts in a HubSpot test account for the upcoming integration. They have not been deployed to customers. The real API request, upload, completion check, and contact note were verified. The request action also passed email verification, displayed a clickable labeled link, and opened a recorder that submitted a real browser recording. The two actions remain separate drafts; automatic handoff between them in one conversation is still a release check.
{% endhint %}

Configure two actions: **Request a recording** and **Check recording received**. Keeping the steps separate lets Breeze offer a recording when appropriate and check its status only when the customer returns.

## Before you start

Create a [dedicated HubSpot chatbot token](/helpdesk-integrations/hubspot/chatbot-token.md) for the connected Screendesk workspace. You do not need to enable general Screendesk API access.

Your HubSpot account must be eligible for Customer Agent actions, and the person configuring them needs Customer Agent editing permissions. Production usage follows HubSpot's subscription and Credits requirements. See [HubSpot's current action requirements](https://knowledge.hubspot.com/customer-agent/set-up-actions-for-the-customer-agent).

Use a test contact whose email address you control when checking the complete conversational flow. A sample contact can be used for API input tests, but should not receive a real verification email.

## 1. Open the actions area

In HubSpot, open **Customer Agent → Train → Actions**. Depending on your navigation, Customer Agent may be under **Service** or **Agent Hub**. Add a custom API action.

![Two Screendesk actions saved as drafts in HubSpot Customer Agent](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FSP4rkaW7etwI28Fg0WPG%2Fbreeze-drafts.png?alt=media)

*The test account has separate request and completion-check actions. Both remain drafts.*

## 2. Describe the recording-request action

Use these values in **Describe the action**:

| 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**                                                                                                                   |
| Example trigger         | `I want to send a screen recording`                                                                                                |
| Another trigger         | `Can I show you the problem?`                                                                                                      |

Choose the intended audience segments for your agent. The test screenshots use **All**, which you should review for your own rollout.

![Breeze request action with Verify email protection and example trigger phrases](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FVYknimqe9X7MvFN8Vxgn%2Fbreeze-request-identity.png?alt=media)

HubSpot controls the identity-verification step. If the visitor is not already recognized as verified, the agent may ask for an email and send a verification link before running the action. Do not remove this protection simply to make a preview pass.

## 3. Define the request input

Under **Define required inputs**, add:

| Field        | Value                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Input name   | `Customer email`                                                                                                        |
| Instructions | `The verified contact email of this customer. Use the email already known in this conversation; never invent an email.` |

The email must match one existing contact in the HubSpot account connected to this Screendesk workspace. This action does not create a contact automatically. A different email or duplicate match cannot be used to guess a destination.

## 4. Configure the request API

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

Use the public Screendesk address shown above. Confirm that the chatbot preview is enabled for your workspace before testing.

HubSpot may show `https://` separately beside the endpoint input. Enter the hostname and path in that case, so you do not produce `https://https://…`.

Save the dedicated token in HubSpot's encrypted secret manager and select it. The secret value is the token alone, without a `Bearer` prefix. Use the **Property parameters** row to map the customer's input; do not place a fixed test email in **Static parameters**.

![Breeze request API mapping customer\_email to Customer email and using the dedicated secret](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FJw16UCawCC6MfcCmthy0%2Fbreeze-request-authentication.jpg?alt=media)

## 5. Set the request response instructions

Paste these instructions in **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.
```

![Saved Breeze response instructions requesting a labeled Record your screen link](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FJcYqYTOsES7hgkvQMpVt%2Fbreeze-wrapped-link-instructions.png?alt=media)

*These instructions produced a labeled link in the real action preview after email verification. The HTML format used by the rule-based chatbot is a separate implementation.*

![Breeze preview showing a clickable Record your screen link after email verification](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2F21xfvPldYFJd5vrBCPfo%2Fbreeze-verified-recording-link.jpg?alt=media)

*The action completed successfully and the link opened the customer recorder. Its signed destination remains behind the readable label.*

## 6. Add the completion-check action

Return to **Actions** and 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**                                                                                                                    |
| Example trigger         | `I have sent my recording`                                                                                                          |
| Another trigger         | `Did you receive my screen recording?`                                                                                              |

Add this required input:

| Field        | Value                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Input name   | `Recording link`                                                                                                                                   |
| 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.` |

![Completion action input using the previously offered recording link](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2Fq8IssCHVKBUp1NlobSFS%2Fbreeze-completion-input.jpg?alt=media)

This is the URL behind **Record your screen** in the earlier agent message. The customer should not need to find a request ID or paste a staff-only report URL. Verify in the conversation preview that Breeze retrieves the earlier destination correctly.

## 7. Configure the completion API

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

Use **Query parameters** here, not body parameters. Screendesk reads the request reference from the supplied URL and checks it within the current workspace and token; it does not fetch that URL as an external resource.

![Completion action mapping recording\_url to Recording link as a query parameter](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FzmoUfj3rESeuNixjmNrO%2Fbreeze-completion-query.jpg?alt=media)

## 8. Set the completion 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.
```

An appropriate acknowledgment is: “Thanks, your recording has been received. Let's continue here.” Receipt confirms a saved upload; it does not mean the agent has analyzed the recording.

## 9. Test the API mapping

Use **Test API** in each action before testing the whole conversation:

1. In the request action, provide a real test contact's email and send the request.
2. Expect HTTP **201**, `status: pending`, and a `recording_url`.
3. In the completion action, use that exact URL as **Recording link**.
4. Before upload, expect HTTP **200** and `status: pending`.
5. Open the returned URL, submit a short test recording, and run the completion test again.
6. Expect `status: received`. HubSpot delivery may initially be `pending`; wait for `delivered` and check the test contact's timeline.

These API steps were completed against the real HubSpot test account, including an uploaded recording and an independently checked contact note. Keep the signed recording URL out of public screenshots while testing.

## 10. Test the conversation and review deployment

Open the action's own **Preview** tab, next to **Setup**, with a contact whose email you control. In our test, the general agent tester did not make the unpublished actions available even with **All Drafts** selected; the dedicated action preview did. Ask to send a recording, complete any identity-verification step, submit the recording, and tell the agent that you have sent it.

Check that the agent chooses the correct action, offers the exact recording URL under the readable label, reuses that destination for completion, and does not confirm receipt too early. Also test skipping, expiry, and temporary failure using the [testing guide](/helpdesk-integrations/hubspot/chatbot-testing-and-troubleshooting.md).

The request preview completed email verification, generated the labeled link, and accepted a real nine-second browser recording. The upload returned successful creation and finalization responses, and its note was independently verified on the intended HubSpot contact.

![Customer recorder confirming that the recording was submitted](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FKGeqJdB9ZjNp4zqV8wEB%2Fbreeze-recording-submitted.jpg?alt=media)

The completion action also passed its own conversational preview after a fresh email-verification flow. Given the original recording link, it invoked the API and confirmed receipt.

![Breeze confirming that the screen recording was received successfully](https://3820804400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfW6XSzJSKsNyZnOkSJPt%2Fuploads%2FemOhM8EGMZJVkRZnk0oU%2Fbreeze-receipt-confirmed.jpg?alt=media)

The two actions remain drafts and were tested separately. Before deployment, verify that a single conversation can invoke both actions and reuse the earlier link without asking the customer to paste it. Deployment should follow only after the Screendesk release and these conversation checks are complete.


---

# 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/breeze-customer-agent.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.