> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Chat Widget

> Route web chat conversations from the AI Chat Widget into the HubSpot conversations inbox as live chats.

Widget conversations route through HubSpot's conversations inbox. When the AI hands off a chat, your rep picks it up as a live conversation in HubSpot — full transcript attached, no context lost.

## Pre-requisites

<Warning>
  **Install the AI Chat Widget on your site first.** HubSpot handoff has nothing to route until the widget is live — start with [Install Widget](/widget/install-widget) and come back here.
</Warning>

* **Widget installed and reachable** — see [Install Widget](/widget/install-widget).
* **HubSpot connected** — see [Connect HubSpot](/integrations/hubspot/connect).

## How conversations land in HubSpot

```mermaid theme={"dark"}
flowchart LR
  A[Visitor opens widget] --> B[AI answers]
  B --> C{AI can resolve?}
  C -- Yes --> D[Visitor closes the chat]
  C -- No --> E[Handoff]
  E --> F[HubSpot conversation + ticket]
  F --> G[Rep replies — lands in the widget]
```

## Setting up

<Steps>
  <Step title="Confirm the widget is live">
    Open the page where you embedded the widget and send a test message. The AI should respond. If the widget doesn't load, walk through [Install Widget](/widget/install-widget) first.
  </Step>

  <Step title="Confirm HubSpot is connected">
    In [**Settings → Integrations**](https://platform.open.cx/settings/integrations), open **HubSpot**. The status should show the integration is connected, preferably via **OAuth Public App**.
  </Step>

  <Step title="Trigger a test handoff">
    Send a message like *"I want to talk to a human"* in the widget. The AI should hand off the conversation.
  </Step>

  <Step title="Verify in HubSpot">
    Open your HubSpot conversations inbox. The conversation should appear with the full AI transcript, and an internal handoff comment should be posted with the AI summary, sentiment, and language. A ticket is created alongside and associated with the conversation. Reply from HubSpot and confirm the message lands in the visitor's widget.
  </Step>
</Steps>

## What the rep sees

* A **conversation in the HubSpot inbox** with the full AI-to-visitor transcript.
* A **HubSpot ticket** associated with the conversation, carrying the conversation summary.
* The contact's details (name, email if provided, any prior history) linked to the conversation.
* An internal **handoff comment** with the AI's escalation reason, sentiment, and language.
* Replies typed in HubSpot land in the visitor's widget within a couple of seconds.

## Channel-specific details

<AccordionGroup>
  <Accordion title="Authenticated vs anonymous visitors" icon="shield-check">
    When the widget passes a verified email via [widget authentication](/widget/authentication), OpenCX links the conversation to an existing HubSpot contact. Anonymous visitors get a new contact created from whatever information they provide during the chat.
  </Accordion>

  <Accordion title="File uploads" icon="paperclip">
    Files uploaded in the widget appear as attachments on the HubSpot conversation. File-size limits follow HubSpot's plan limits.
  </Accordion>

  <Accordion title="Widget custom components" icon="bolt">
    When an AI action returns data rendered by a [custom component](/widget/custom-components), the visitor sees the richer UI. Your rep sees the underlying text in HubSpot — write copy that reads well in both surfaces.
  </Accordion>

  <Accordion title="CSAT after the chat ends" icon="star">
    If your workflow triggers a satisfaction survey, the rating and comment land on the OpenCX session, not on a HubSpot feedback object.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="AI Chat Widget" icon="messages" href="/widget/introduction">
    The channel itself — install, configure, authenticate.
  </Card>

  <Card title="Connect HubSpot" icon="plug" href="/integrations/hubspot/connect">
    OAuth setup, AI sender, workflow actions.
  </Card>

  <Card title="HubSpot Overview" icon="hubspot" href="/integrations/hubspot/overview">
    What else HubSpot lights up across every channel.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/hubspot/troubleshooting">
    Widget handoff not appearing, missing rep replies.
  </Card>
</CardGroup>