# HubSpot

Conecta HubSpot para que el agente reconozca a quien llama por su teléfono, cree contactos y tratos, y registre cada llamada como nota

> Full REST + WebSocket API reference: https://api.happ.tools/reference

HubSpot se conecta con una Service Key que creas en tu cuenta de HubSpot. Una vez vinculada, el agente saluda por su nombre a los clientes conocidos teniendo a mano su último trato, crea un contacto y un trato cuando alguien deja una solicitud, y escribe el resultado de cada llamada en la ficha del cliente.

## Qué puede hacer el agente [#what-the-assistant-can-do]

* **Reconocer a quien llama**: al inicio de una llamada busca el número de teléfono en HubSpot y obtiene el nombre, email y empresa del contacto, y su último trato (nombre, etapa, importe).
* **Crear un trato**: encuentra el contacto por teléfono o crea uno nuevo, y luego crea un trato en el pipeline y la etapa que elijas. La solicitud, la dirección de entrega, los productos y el anuncio que trajo al cliente van al trato como nota.
* **Registrar llamadas**: tras cada llamada añade una nota al contacto y a su trato: dirección, duración, resultado, resumen, el enlace a la grabación y, si quieres, la transcripción completa.

## Antes de empezar [#before-you-start]

* **Cuenta de HubSpot** en la que puedas gestionar claves (Super Admin, o un usuario con permiso para crear claves).
* **Espacio de trabajo de HAPP** con al menos un agente.
* **HubSpot activado para tu espacio de trabajo**: la integración se activa por empresa. Pide al soporte de HAPP que la active.

## Crear una Service Key [#create-a-service-key]

1. En HubSpot abre **Development > Keys > Service keys** y haz clic en **Create service key**.
2. Ponle el nombre `HAPP` y añade los scopes:
   * `crm.objects.contacts.read`, `crm.objects.contacts.write`
   * `crm.objects.deals.read`, `crm.objects.deals.write`
   * `crm.objects.owners.read`
3. Crea la clave y cópiala.

También sirve un token de una private app existente (**Settings > Integrations > Private apps**) con los mismos scopes. HubSpot deja de crear private apps nuevas en octubre de 2026, así que usa una Service Key para las conexiones nuevas.

## Conectar [#connect]

1. En HAPP abre **Integraciones** y busca HubSpot en **Añadir un CRM**.
2. Haz clic en **Conectar**, pega la clave y confirma.
3. HubSpot aparece en **Mis integraciones** como "HubSpot \<ID de cuenta>".

## Configuración [#settings]

Abre el icono de engranaje de la tarjeta en la pestaña **Integraciones** del agente.

* **Buscar**: reconocer a quien llama por su teléfono.
* **Crear**: tratos. Elige el **pipeline**, la **etapa** y el **responsable**; sin ellos, el trato va a tu primer pipeline, primera etapa.
* **Notas de llamada**: una nota tras cada llamada. **Transcripción completa** añade el texto de la conversación.

## Límites [#limits]

* HubSpot guarda los números de teléfono tal como se escribieron; el agente compara los últimos 9 dígitos, así que `050 111 22 33` y `+380501112233` son el mismo cliente.
* Un número que no está en HubSpot no recibe nota de llamada: no hay registro al que adjuntarla.
* Si el email del cliente ya pertenece a otro contacto, el trato se adjunta a ese contacto.

## Solución de problemas [#troubleshooting]

| Problema                         | Causa                                                  | Solución                                                                      |
| -------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| "HubSpot rejected the token"     | La clave se eliminó, se rotó o se escribió mal         | Crea una clave nueva y vuelve a hacer clic en **Conectar**.                   |
| "HubSpot token lacks scopes: …"  | A la clave le falta uno de los scopes de arriba        | Añade los scopes indicados a la clave (o crea una nueva) y vuelve a conectar. |
| "HubSpot API rate limit reached" | Demasiadas peticiones a la vez                         | No hay que hacer nada: la siguiente petición pasa.                            |
| La lista de pipelines está vacía | No hay ningún pipeline de tratos con etapas en HubSpot | Crea un pipeline de tratos en HubSpot.                                        |

## Desconectar [#disconnect]

Desconecta la tarjeta en HAPP y elimina la clave en **Development > Keys > Service keys**. Los contactos, tratos y notas que ya están en HubSpot se mantienen.

## Siguiente [#next]

* [CRM](/docs/integrations/crm): todas las integraciones de CRM
* [Herramientas](/docs/agents/tools): lo que el agente llama durante las conversaciones