Hedy API

¿Qué es la Hedy API?

La Hedy API proporciona acceso programático a sus datos de reuniones, transcripciones, resúmenes e información generada por IA. Ya sea que esté construyendo integraciones personalizadas, automatizando flujos de trabajo o conectándose con herramientas como Zapier, la API le da el poder de extender las capacidades de Hedy más allá de la aplicación. Todas las funciones de la API requieren una suscripción Pro con Cloud Sync habilitado. Si quiere que un asistente de IA trabaje con estos datos conversacionalmente en lugar de escribir código, también puede conectar Hedy con asistentes de IA usando MCP.

Comenzar con la API

1. Abra la aplicación Hedy y navegue a Account Settings

2. Desplácese hasta la sección Acceso a la API

3. Haga clic en Generate New API Key (se requiere suscripción Pro)

4. Copie su API key y guárdela de forma segura; no podrá verla de nuevo

5. Visite nuestra documentación de la API en SwaggerHub para información detallada sobre los endpoints, o acceda a la especificación OpenAPI sin procesar en https://api.hedy.bot/docs

Nota de seguridad: Su API key proporciona acceso completo a sus datos de Hedy. Manténgala segura y nunca la comparta públicamente ni la incluya en el control de versiones.

URLs de endpoints por región

La Hedy API se ejecuta en dos regiones para mantener los datos de usuario en la jurisdicción correcta. Use la URL base que coincida con la región en la que se creó su cuenta:

• Cuentas de EE.UU.: https://api.hedy.bot

• Cuentas de la UE: https://eu-api.hedy.bot

Ambas regiones ejecutan código idéntico y exponen los mismos endpoints — no hay diferencia de funcionalidades. Su API key está vinculada a la región de su cuenta, por lo que las llamadas a la URL base incorrecta fallarán la autenticación. Si no está seguro de qué región usa su cuenta, abra Hedy y vaya a Configuración → Privacidad y sistema → Preferencias de privacidad; el ícono de bandera muestra dónde se almacenan sus datos.

Los ejemplos de este artículo usan https://api.hedy.bot. Si su cuenta está en la UE, reemplácela por https://eu-api.hedy.bot en todas partes.

Capacidades de la API

La Hedy API ofrece acceso integral a su inteligencia de reuniones:

• Sesiones: Liste y recupere sus sesiones de reuniones, incluyendo transcripciones completas, resúmenes de IA y puntos clave

• Destacados: Recupere momentos importantes de sus reuniones con información generada por IA

• Temas: Cree, actualice, elimine y organice sesiones por temas con instrucciones de contexto personalizadas

• Tareas pendientes: Recupere y gestione elementos de acción en todas las sesiones

• Contextos de sesión: Cree y gestione instrucciones reutilizables que guían cómo Hedy analiza sus reuniones

• Vocabulario personalizado: Consulte y reemplace la lista de vocabulario de la cuenta que mejora la transcripción de nombres y términos técnicos

• Webhooks: Configure y gestione endpoints de webhook a través de la API para notificaciones de eventos en tiempo real

• Información del usuario: Recupere los detalles de su cuenta a través del endpoint /me

Autenticación

Todas las solicitudes a la API requieren autenticación usando su API key. Inclúyala en el encabezado de autorización:

Authorization: Bearer YOUR_API_KEY

Webhooks

Configure webhooks para recibir notificaciones en tiempo real cuando ocurran eventos en su cuenta de Hedy:

1. En la sección de API Access, haga clic en Manage Webhooks

2. Haga clic en el botón + para agregar un nuevo webhook

3. Ingrese la URL de su endpoint HTTPS

4. Seleccione los eventos que desea recibir:

   • session.created - Cuando comienza una nueva sesión

   • session.ended - Cuando una sesión completa el procesamiento

   • session.exported - Cuando el usuario exporta manualmente una sesión

   • highlight.created - Cuando se agrega un nuevo destacado

   • todo.exported - Cuando se exportan tareas pendientes de una sesión

5. Guarde su webhook y anote el secreto de firma para la verificación de la carga útil

También puede gestionar webhooks programáticamente a través de la API usando GET, POST y DELETE en el endpoint /webhooks. Cada cuenta puede tener hasta 50 webhooks.

Verificación de firma de webhook

Cada entrega de webhook incluye una firma en el encabezado X-Hedy-Signature para que pueda verificar que proviene de Hedy. La firma es un hash HMAC-SHA256 del cuerpo sin procesar de la solicitud, firmado con el secreto de firma de su webhook. Verifique la firma en su servidor antes de procesar la carga útil para garantizar la autenticidad. Cada entrega también incluye un encabezado X-Hedy-Event que indica el tipo de evento (ej. session.ended).

Contextos de sesión

Los contextos de sesión le permiten crear conjuntos reutilizables de instrucciones personalizadas que le dicen a Hedy cómo analizar sus reuniones. Por ejemplo, puede crear un contexto para “Llamadas de ventas” que se enfoque en elementos de acción y objeciones de clientes, o uno para “Reuniones de standup” que rastree bloqueos y actualizaciones.

Use la API para gestionar sus contextos de sesión:

• GET /contexts - Lista todos sus contextos de sesión

• GET /contexts/{id} - Obtener un contexto específico por ID

• POST /contexts - Crear un nuevo contexto (título y contenido)

• PATCH /contexts/{id} - Actualizar un contexto existente

• DELETE /contexts/{id} - Eliminar un contexto

Establezca un contexto como predeterminado y se aplicará automáticamente a todas las nuevas sesiones. Las cuentas del nivel gratuito están limitadas a 1 contexto de sesión.

Gestión de temas a través de la API

Los temas le ayudan a organizar sus sesiones en categorías. La API soporta la gestión completa de temas:

• GET /topics - Lista todos los temas con información generada por IA y conteos de sesiones

• GET /topics/{id} - Obtener los detalles de un tema específico

• POST /topics - Crear un nuevo tema con nombre, descripción, color, ícono y tipo de sesión predeterminado

• PATCH /topics/{id} - Actualizar las propiedades de un tema, su contexto personalizado o el tipo de sesión predeterminado

• DELETE /topics/{id} - Eliminar un tema (las sesiones se desvinculan, no se eliminan)

• GET /topics/{id}/sessions - Listar todas las sesiones dentro de un tema

Los temas pueden incluir un campo topicContext con instrucciones personalizadas (hasta 20,000 caracteres) que guían cómo Hedy analiza las sesiones asignadas a ese tema. Esas instrucciones se adjuntan automáticamente a cualquier sesión iniciada bajo el tema, incluidas las sugerencias en vivo durante la sesión, por lo que preparar un tema a través de la API es suficiente para preparar la sesión.

Los temas también aceptan un campo dominantSessionType, que establece el tipo de sesión que usará una sesión iniciada bajo ese tema. Esto resulta útil cuando crea temas programáticamente y no quiere que todos recurran al tipo predeterminado. El campo también funciona como una estadística derivada: una vez que un tema tiene sesiones, Hedy lo recalcula a partir de los tipos que realmente utilizó, por lo que un valor que escriba actúa como punto de partida y no como una configuración permanente. Establecerlo en un tema que ya tiene sesiones funciona como una anulación puntual para la siguiente sesión. La referencia de la API enumera los valores de tipo de sesión aceptados.

Vocabulario personalizado

El vocabulario personalizado enseña a Hedy los nombres, acrónimos y términos técnicos específicos de su trabajo, lo que mejora la precisión con la que se transcriben. La lista se almacena en su cuenta y se aplica a todas las sesiones.

• GET /vocabulary - Recuperar la lista actual de términos y si el vocabulario está habilitado

• PUT /vocabulary - Reemplazar la lista completa de términos

PUT reemplaza la lista completa en lugar de añadir elementos, por lo que se elimina cualquier término almacenado que no incluya. Envíe hasta 100 términos, cada uno de entre 2 y 50 caracteres. Los términos deben ser únicos (se ignoran las mayúsculas y minúsculas al compararlos) y no pueden contener corchetes angulares, llaves, corchetes, barras invertidas, barras verticales, acentos graves ni tildes.

El indicador enabled se puede leer y modificar. Si lo omite al reemplazar los términos, el valor almacenado no cambia. Esto es importante si automatiza las actualizaciones del vocabulario: leer primero el indicador le permite saber si los términos que escriba se utilizarán realmente, en vez de permanecer en una cuenta donde el vocabulario está desactivado.

Como una sola llamada sustituye toda la lista, puede reescribir el vocabulario antes de cada reunión para que coincida con los nombres y la terminología que esa reunión necesita, en lugar de mantener una sola lista larga y combinada.

Casos de uso comunes

• Integración con gestión de proyectos: Cree automáticamente tareas en su herramienta de PM a partir de elementos de acción de reuniones

• Gestión del conocimiento: Indexe el contenido de reuniones en la base de conocimiento de su empresa

• Integración con CRM: Actualice registros de clientes con información de reuniones

• Paneles de analítica: Construya informes personalizados sobre patrones de reuniones y productividad

• Automatización de flujos de trabajo: Active acciones basadas en el contenido o finalización de reuniones

• Integración con Zapier: Conecte Hedy a miles de aplicaciones usando Zapier (agregue ?format=zapier a los endpoints para respuestas de arreglo plano compatibles con Zapier)

Límites y mejores prácticas de la API

• Límites de velocidad: 200 solicitudes por minuto por API key

• Paginación: Use el parámetro limit (predeterminado 50, máximo 100) y el parámetro de cursor after para paginar los resultados

• Almacene en caché las respuestas cuando sea posible para reducir las llamadas a la API

• Maneje los errores con gracia usando retroceso exponencial

• Use webhooks para actualizaciones en tiempo real en lugar de sondeo

Exportación automática de tareas pendientes

Habilite la exportación automática de tareas pendientes para enviar elementos de acción a sus sistemas integrados:

1. En la sección de API Access, active Auto Export Todos

2. Las tareas pendientes se enviarán automáticamente a sus endpoints de webhook configurados

3. Cada tarea pendiente incluye contexto, sugerencias de asignación y referencia de la reunión

Ejemplos de código

Aquí tiene un ejemplo simple para obtener sus sesiones recientes:

curl -X GET "https://api.hedy.bot/sessions?limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

Para más ejemplos y la referencia completa de endpoints, visite nuestra documentación de la API.

Solución de problemas

Error 401 Unauthorized

• Verifique que su API key sea correcta y tenga el formato adecuado

• Asegúrese de tener una suscripción Pro activa

• Compruebe que Cloud Sync esté habilitado en su cuenta

• Confirme que la API key no haya sido regenerada (las claves antiguas se invalidan)

Respuesta vacía o datos faltantes

• Asegúrese de que Cloud Sync esté habilitado; la API solo accede a datos sincronizados en la nube

• Espere unos minutos después de una sesión para que los datos se sincronicen

• Verifique sus filtros de fecha y parámetros de paginación

• Compruebe que está usando el endpoint correcto para su tipo de datos

El webhook no recibe eventos

• Confirme que la URL de su endpoint use HTTPS (requerido)

• Verifique que su servidor responda con estado 200 OK

• Compruebe el encabezado X-Hedy-Signature si está implementando verificación de firma

• Pruebe su webhook usando el botón “Test Webhook”

• Verifique que las reglas del firewall no estén bloqueando los servidores de Hedy

Límite de velocidad excedido

• Implemente almacenamiento en caché para reducir llamadas redundantes a la API

• Use webhooks para actualizaciones en tiempo real en lugar de sondeo

• Agrupe operaciones cuando sea posible

• Contacte al soporte si necesita límites más altos

Consejo profesional: Use webhooks en lugar de sondeo para actualizaciones en tiempo real. Esto es más eficiente y proporciona notificaciones instantáneas cuando sus datos cambian.

Privacidad y seguridad

La seguridad de sus datos es nuestra prioridad:

• Toda la comunicación de la API usa encriptación HTTPS

• Las API keys se pueden regenerar en cualquier momento (invalida la clave anterior)

• Las cargas útiles de webhook se firman con HMAC-SHA256 para verificación

• Los datos solo son accesibles con autenticación válida

• Todos los endpoints aplican encabezados de seguridad estrictos

Obtener ayuda

Para preguntas específicas sobre la API:

• Consulte la documentación de la API para detalles de endpoints y esquemas

• Lea nuestra publicación de blog sobre la API para ejemplos y casos de uso

• Únase a nuestra comunidad de Slack para soporte y compartir sus integraciones