Referencia de la API v1
Referencia de integración REST + Webhooks (versión 2026-06-15)
Guía rápida de integración de CRM
La vía más rápida para conectar un CRM a Heilo. La referencia completa de la API está más abajo.
Integre con un enfoque webhook-first: el evento call.completed es la fuente de datos principal (lleva el enlace de la grabación y la transcripción procesada). REST /calls es un complemento: introspección y lectura de metadatos seleccionados.
- Exponga un endpoint de webhook en su CRM o middleware (sin código: use Zapier/Make; vea la guía más abajo).
- Añada una suscripción en Heilo (Ajustes → Integraciones) para call.completed (opcionalmente también call.outbound.attempted).
- Reciba call.completed y verifique la firma (cabecera Heilo-Signature, HMAC; vea más abajo).
- Deduplique por event_id (cabecera heilo-event-id); data.call_id agrupa los eventos de la misma llamada.
- Mapee los campos a su CRM: busque/cree un contacto por teléfono, cree un lead/negocio y adjunte una actividad/nota (resumen + enlace de la grabación).
¿Sin código? La guía de conexión sin código (Zapier/Make) lo explica paso a paso.
Autenticación
La API pública usa tokens Bearer. Genere una clave API desde la tarjeta «Claves API» de la página de Integraciones y envíela en la cabecera:
Authorization: Bearer hk_live_AbC1MnPq...
Heilo tiene tres modos de autenticación:
- Bearer (claves API hk_live_…): para la API pública. Sin CSRF, sin cookies.
- Cookies de sesión: para la aplicación web (heilo.io). NO las use para la API pública.
- HMAC-SHA256: para los Webhooks que Heilo envía a SU endpoint (usted verifica la cabecera de firma).
| Permiso (scope) | Significado |
|---|---|
| read.calls | Lectura de llamadas: GET /api/v1/calls, GET /api/v1/calls/:id |
| read.recordings | Emite un enlace al audio de una llamada mediante `GET /calls/:id/recording-url`. Separado de `read.calls` porque el audio es un consentimiento distinto del de los metadatos: una clave existente no lo adquiere, se crea una nueva con acceso explícito a grabaciones. |
| read.transcripts | Añade el texto de la transcripción a `GET /calls/:id`: `transcript_original`, `transcript_edited` y `transcript_edited_at`. Separado de `read.calls` porque las palabras de una conversación son un consentimiento distinto al de los metadatos — una clave existente no lo recibe, hay que crear una clave nueva con acceso explícito a las transcripciones. Sin él esos campos no aparecen y la llamada sigue respondiendo 200. Requiere además `read.calls`: una clave solo con `read.transcripts` recibe 403, y crearla se rechaza con 400. |
| write.calls, read.contacts, write.contacts, manage.webhooks, manage.api_keys | Reservados para endpoints de API previstos. No se puede crear una clave nueva con ellos (400 BAD_REQUEST). Una clave antigua aún puede tener alguno, y no concede nada. |
El campo environment en la respuesta de /me tiene hoy siempre el valor live. Las claves de prueba están previstas.
URL base y versión
Todos los endpoints públicos están bajo /api/v1/. Producción:
https://www.heilo.io/api/v1
Versión actual
v1 · 2026-06-15
La fecha es el identificador de versión de la API (con fecha), no la fecha de hoy.
Status
Beta
La API de Heilo usa una versión con fecha. Solo los cambios incompatibles incrementan la versión principal (v1 → v2). Añadir campos o endpoints no rompe la compatibilidad, ni tampoco añadir campos a los payloads de webhook.
Compatible con versiones anteriores: nuevos campos de respuesta, nuevos campos en los payloads de webhook, nuevos event_types, nuevos endpoints. Cambio incompatible = nueva versión principal (v2). La versión antigua se mantiene un mínimo de 12 meses tras el anuncio de v2.
Límites de tasa
Límites por hora por clave y por usuario (suma de todas las claves). Se reinician en la hora UTC. Cada solicitud cuenta, independientemente del estado de la respuesta.
Por clave
1000 req/h
Por cuenta (suma de las claves)
5000 req/h
Cada respuesta correcta incluye X-RateLimit-Limit (el límite horario de la clave), X-RateLimit-Remaining (las solicitudes que le quedan a la clave en esta hora) y X-RateLimit-Reset (cuándo se reinicia el contador, ISO 8601). Al superarlo devolvemos 429 con la cabecera Retry-After (segundos hasta el reinicio):
HTTP/1.1 429 Too Many Requests Retry-After: 1842 X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 2026-06-03T13:00:00Z
Errores
Todos los errores devuelven una estructura JSON uniforme con error.code (estable) y error.message (legible por humanos, puede cambiar). Registre el code, no el message.
{
"success": false,
"error": { "code": "RATE_LIMITED", "message": "Per-key rate limit 1000/h exceeded" },
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}{
"success": false,
"error": { "code": "BAD_REQUEST", "message": "Validation failed", "details": { "errors": [{ "path": "scopes", "message": "Required" }] } },
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}| HTTP | code | Significado |
|---|---|---|
| 400 | BAD_REQUEST | Parámetros de consulta o de cuerpo mal formados (validación genérica) |
| 401 | UNAUTHORIZED | Token Bearer ausente o no válido |
| 402 | SUBSCRIPTION_INACTIVE | Suscripción inactiva: renueve la facturación para reactivar la clave |
| 403 | FORBIDDEN | La clave no tiene el scope requerido |
| 404 | NOT_FOUND | El recurso no existe o está fuera de la organización de la clave API. |
| 400 | VALIDATION_ERROR | Un parámetro no pasó una comprobación (p. ej. phone no es un número de teléfono) |
| 429 | RATE_LIMITED | Límite por hora superado (consulte Retry-After) |
| 500 | DATABASE_ERROR | Error de servidor / base de datos: es seguro reintentar con backoff |
| 503 | MAINTENANCE | API pública desactivada temporalmente (kill switch) |
| 503 | SERVICE_UNAVAILABLE | Una parte del servicio que necesita la llamada no está disponible (por ejemplo, ahora no se pueden generar enlaces de grabación) — reintenta con espera creciente |
| 503 | WEBHOOK_ACTIVATION_LOCKED | Activar suscripciones de webhook está en pausa por una migración; las suscripciones existentes siguen funcionando — inténtalo más tarde |
| 422 | SUBSCRIPTION_LIMIT | La organización alcanzó su límite de suscripciones de webhook (HTTP 422) — elimina primero una que no uses |
El código SUBSCRIPTION_INACTIVE aparece en dos situaciones: HTTP 402, la suscripción de Heilo ha caducado (pago), y HTTP 409, la suscripción del webhook está pausada (p. ej., con la acción de prueba); en ese caso, haga clic primero en «Volver a verificar».
Un error también puede incluir error.details con detalles, por ejemplo los campos que fallaron en una validación; el campo puede faltar. Lo estable es el código.
Cada endpoint de /api/v1 requiere Bearer. El /me siguiente sirve para la introspección de la clave; la lectura de llamadas está en la sección «Llamadas». Al integrar un CRM, trate los webhooks como la fuente de datos principal: REST sirve para la introspección y para leer metadatos seleccionados.
Introspección de la clave API: devuelve el id de la clave, user_id, scopes y el límite de tasa. Útil para la «prueba de conexión» de Zapier/Make.
Caso de uso: prueba de conexión de Zapier durante la configuración de una integración personalizada. Una respuesta 200 demuestra que la clave y la red funcionan.
curl https://www.heilo.io/api/v1/me \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"api_key_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
"user_id": "5f4e3d2c-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"organization_id": "7a8b9c0d-1e2f-4a3b-9c8d-7e6f5a4b3c2d",
"scopes": ["read.calls", "read.recordings"],
"rate_limit_per_hour": 1000,
"environment": "live"
},
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}Endpoints de lectura para llamadas. Requieren el scope read.calls.
Lista las llamadas de la organización. Paginación (page/limit≤100), filtros: direction, status, rango de fechas (dateFrom/dateTo). Devuelve has_more.
La lista va de la más reciente a la más antigua (created_at descendente) y se pagina por número de página, así que una llamada que llega mientras paginas desplaza las filas. Elimina duplicados por call_id y vuelve a leer la primera página para ponerte al día. No es una exportación del historial completo.
Parámetros de consulta
| Parámetro | Tipo | Valores |
|---|---|---|
| page | int | desde 1 (por defecto 1) |
| limit | int | 1–100 (por defecto 20) |
| direction | enum | inbound | outbound |
| status | enum | new | to_call | contacted | qualified |
| dateFrom / dateTo | string | fecha YYYY-MM-DD o fecha y hora en UTC, p. ej. 2026-06-03T12:34:56Z (un desfase como +02:00 devuelve 400). Una fecha sola en dateTo abarca todo ese día en UTC, así que dateTo=2026-06-03 incluye las llamadas del 3 de junio; una fecha con hora es un instante exacto, incluido |
| phone | string | el número del cliente de la llamada, con el prefijo del país; los espacios, guiones y el + inicial son opcionales, p. ej. +48 600 100 200 |
curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"items": [
{
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+48600100200",
"customer_phone_e164": "+48600100200",
"customer_phone_national": "600 100 200",
"company_phone_e164": "+48222630000",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"caller_name": "Jan Kowalski",
"duration": 87,
"crm_status": "new",
"review_status": null,
"outcome": "quote_to_send",
"outcome_source": "ai",
"outbound_lifecycle": null,
"transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "...", "followup_email": null },
"created_at": "2026-06-03T12:34:56Z"
}
],
"has_more": false,
"page": 1,
"limit": 20
},
"meta": { "timestamp": "2026-06-03T12:34:56Z" }
}Obtiene una sola llamada por id. 404 si no pertenece a la organización de la clave o si se eliminó.
En este endpoint el objeto de análisis transcript_processed incluye summary, service_needed, caller_name y followup_email, y también subject, lead_score (1–10, estimación del modelo), detected_language y client_city: los mismos valores que envía el webhook call.completed. Un campo que el análisis no produjo vale null. has_recording indica si hay audio guardado; el audio en sí se obtiene con GET /calls/:id/recording-url y el scope read.recordings.
Con el scope read.transcripts la respuesta incluye además transcript_original (null cuando la llamada no tiene una transcripción utilizable: aún en proceso, fallida o sin voz), transcript_edited y transcript_edited_at (null cuando nadie la editó). Sin el scope esos tres campos no aparecen (no son null) y la respuesta sigue siendo 200.
La respuesta incluye además user_notes: las entradas que las personas escribieron sobre la llamada en Heilo («Apuntes de la llamada»), de la más antigua a la más reciente, como máximo 200, y un array vacío cuando no hay ninguna. El endpoint de lista GET /calls no las incluye. El ejemplo está abreviado; los demás campos son los mismos que en la lista. Para enterarse de los cambios en las entradas, suscríbase a call.user_notes.changed.
curl https://www.heilo.io/api/v1/calls/<id> \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"duration": 87,
"outcome": "quote_to_send",
"outcome_source": "ai",
"created_at": "2026-06-03T12:34:56Z",
"transcript_processed": {
"caller_name": "Anna Nowak",
"summary": "Asks for a quote for a bathroom renovation.",
"service_needed": "bathroom renovation",
"followup_email": null,
"subject": "Bathroom renovation quote",
"lead_score": 7,
"detected_language": "en",
"client_city": "Gdańsk"
},
"has_recording": true,
"user_notes": [
{
"id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"body": "Klient prosi o telefon po 10:00.",
"source": "live",
"author": {
"id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"name": "Anna Nowak"
},
"noted_at": "2026-09-08T10:01:12Z",
"recording_offset_seconds": 72,
"created_at": "2026-09-08T10:01:12Z",
"updated_at": "2026-09-08T10:01:12Z"
}
]
},
"meta": {
"timestamp": "2026-06-03T12:34:56Z"
}
}Un enlace recién firmado al audio de la llamada, válido 15 minutos. Es un permiso de descarga con fecha límite, no una referencia duradera: guarda el `call_id` y vuelve a pedirlo, porque un enlace guardado en un campo del CRM deja de servir en menos de una hora. El enlace del webhook `call.recording.ready` está firmado siete días — este endpoint es la forma de llegar al audio después.
- 200 — el enlace y el momento en que deja de funcionar.
- 409 `RECORDING_NOT_READY` — la llamada es tuya y el audio aún no ha llegado. Vuelve a preguntar en breve.
- 409 `RECORDING_WITHHELD` — la llamada está en la papelera o programada para borrarse. El cliente puede restaurar una llamada de la papelera durante 30 días, así que sigue preguntando en lugar de dar la grabación por perdida; una llamada con grabación se borra 30 días después de moverla a la papelera. Un borrado programado no se puede deshacer: deja de usar la grabación. En ambos casos recibirás 410 una vez borrada.
- 410 `RECORDING_DELETED` — la grabación se borró (retención, la papelera a los 30 días o una solicitud de borrado) y no se puede recuperar. Deja de preguntar y deja de encolar.
- 410 `RECORDING_NOT_CAPTURED` — esta llamada saliente nunca se grabó y nunca existirá una grabación para ella: la puerta de captura la rechazó al iniciarse, se ejecutó en modo no_recording o terminó sin conversación. Deja de preguntar; no hay motivo para reintentarlo. Una llamada entrante cuya grabación se rechazó sigue respondiendo 409, porque todavía puede llegar una grabación.
La respuesta se sirve con `Cache-Control: no-store`, porque el cuerpo lleva una credencial. El permiso se vuelve a comprobar al descargar el archivo, no solo al emitir el enlace, así que una llamada borrada entretanto deja de ser legible de inmediato.
curl https://www.heilo.io/api/v1/calls/<id>/recording-url \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"success": true,
"data": {
"url": "https://www.heilo.io/api/v1/calls/<id>/recording.mp3?token=...&exp=...",
"expires_at": "2026-09-15T12:15:00.000Z"
}
}Ni la lista de llamadas ni el detalle devuelven un archivo o enlace de grabación; el detalle solo indica si existe una (has_recording). El enlace a la grabación llega en un webhook y, cuando caduca, desde `GET /calls/:id/recording-url`. Las grabaciones pueden borrarse según las reglas de retención y el RGPD.
Qué trae REST y qué solo trae un webhook
Los dos canales no llevan lo mismo, y la diferencia decide cuál eliges. REST es duradero: puedes leer una llamada en cualquier momento. Un webhook es más rico, pero llega una vez y parte de lo que lleva caduca.
| Datos | REST | Webhook |
|---|---|---|
| Metadatos de la llamada: dirección, números, duración, fecha | sí | sí |
| Estado en el CRM y estado de revisión | sí | no |
| Resultado de la llamada y quién lo estableció | sí | sí |
| Apuntes de la llamada (REST: solo en GET /calls/:id) | sí | sí |
| Resumen, nombre de quien llama, necesidad del cliente | sí | sí |
| El resto del análisis: ciudad, dirección, puntuación del lead, fecha preferida, idioma | parcial: GET /calls/:id trae ciudad, puntuación del lead e idioma; dirección y fecha preferida solo vienen del webhook | sí |
| La transcripción literal | sí, GET /calls/:id con read.transcripts | sí |
| Enlace a la grabación | sí, vía /calls/:id/recording-url | sí, válido 7 días |
De ahí la regla práctica: el webhook lleva todo en el momento en que se procesa la llamada, y REST da después el detalle de una sola llamada, con el análisis ampliado y, con read.transcripts, la transcripción. La grabación se recupera aparte — pide a /calls/:id/recording-url un enlace nuevo de 15 minutos en lugar de guardar el de siete días del payload.
Especificación y una petición real
Las mismas cuatro operaciones, escritas para máquinas: OpenAPI 3.1. Impórtalo en Postman o Insomnia, o genera un cliente en tu lenguaje.
Especificación y una petición real
Envía una petición desde aquí y comprueba tu clave antes de escribir código.
Esto llama a la API real con tu clave real y devuelve tus propios datos. La clave se queda en esta pestaña — nunca la guardamos.
Webhooks salientes
Heilo envía eventos JSON firmados a tu endpoint. Crea suscripciones en la tarjeta Suscripciones de webhooks. La activación usa un handshake separado sin firma, webhook.subscription.verify, que nunca debe crear registros de negocio.
La dirección del endpoint debe ser https, accesible públicamente y no puede apuntar a una dirección privada o interna (localhost, 10.x, 192.168.x y similares). Para probar desde tu propio equipo, exponla mediante un túnel público. Los endpoints se crean solo en Ajustes → Integraciones; ninguna llamada de API crea uno.
POST <your URL>
content-type: application/json
heilo-signature: t=1717423396,v1=4f3a...
heilo-event-id: 1bf3a5e2-...
heilo-event-type: call.completed
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-...",
"event_type": "call.completed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-06-03T12:34:56Z",
"data": { /* see the setup guide for the full schema */ }
}Política de reintentos y pausa:
- Los errores transitorios permiten hasta 5 intentos en total: después de 2 min, 5 min, 30 min y 2 h, con variación aleatoria (jitter) en los reintentos posteriores. Tras el quinto fallo, la entrega termina como dead-letter.
- Los errores permanentes (HTTP 401/403/422) pausan la suscripción de inmediato, sin reintentos.
- 50 fallos transitorios consecutivos, o 2 HTTP 410 Gone consecutivos (p. ej. un escenario de Make eliminado), también pausan la suscripción.
- Reanude una suscripción pausada con «Volver a verificar»: un nuevo handshake reactiva el envío. No envía los eventos que ya esperaban en la cola cuando se pausó: quedan en dead-letter y hay que reenviarlos con «Reenviar» en el Registro de entregas.
Si Heilo pausa una suscripción automáticamente porque su dirección falla una y otra vez, enviamos un correo a la persona que la gestiona, normalmente quien la creó. Si esa cuenta ya no existe, el correo lo reciben los propietarios de la organización. Puede reenviar los eventos en dead-letter con el botón «Reenviar» del Registro de entregas, una vez que la suscripción supere la nueva verificación.
Una respuesta 2xx confirma la recepción HTTP, no el fin de una automatización ni la escritura en el CRM. Las entregas pueden repetirse o llegar desordenadas. Heilo reconcilia lagunas recientes dentro de una ventana limitada, no todo el historial. Revisa por separado las entregas y el CRM.
Modos de verificación
El handshake sin firma contiene solo event_type = webhook.subscription.verify y challenge. Responde únicamente para confirmar el endpoint; no proceses datos de negocio. Ambos modos usan esta petición:
{
"event_type": "webhook.subscription.verify",
"challenge": "example-verification-token"
}Modo permissive (predeterminado)
Cualquier respuesta 2xx activa la suscripción; se ignora su contenido. Es el modo predeterminado para un receptor no-code.
Modo strict (opcional)
Responde con 2xx y JSON con exactamente el valor challenge recibido de Heilo:
{"challenge":"<echo of the challenge field from Heilo's POST>"}Elige el modo al crear la suscripción. Cambiarlo exige eliminarla y crearla de nuevo. Las rutas de gestión requieren una sesión autenticada y protección CSRF; no están disponibles con una clave API.
Límites: máximo 20 suscripciones activas por organización (configurable por variable de entorno). Una suscripción se pausa automáticamente tras 50 fallos transitorios consecutivos o 2 HTTP 410 consecutivos, e inmediatamente con HTTP 401/403/422.
Verificación HMAC (signing_secret)
Los eventos firmados, incluido el webhook.test manual, usan Heilo-Signature con HMAC-SHA256 sobre timestamp + punto + bytes originales de la petición. Verifica la firma antes de analizar el JSON de negocio. Solo el handshake de verificación no lleva firma.
signed_string = "<unix_timestamp>.<raw_request_body>" signature = HMAC-SHA256(signing_secret, signed_string).hex() header = "t=<unix_timestamp>,v1=<signature>"
import { createHmac, timingSafeEqual } from 'node:crypto';
// Pass the exact received Buffer (e.g. Express raw parser), never JSON.stringify(req.body).
// signingSecrets: every secret you currently trust, tried in constant time each.
// During a secret rotation pass [newSecret, oldSecret]; remove the old one once
// Heilo's grace window ends. Heilo itself always sends exactly ONE v1 signature —
// this list is what lets your receiver accept it under either secret while both
// are live, never a second signature to parse.
function verifyHeiloSignature(rawBody, header, signingSecrets) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
if (!match) return false;
const timestamp = Number(match[1]);
const now = Math.floor(Date.now() / 1000);
// Receiver policy: at most 10 minutes old or 5 minutes ahead (clock skew).
if (!Number.isSafeInteger(timestamp) || now - timestamp > 600 || timestamp - now > 300) return false;
// One string is accepted too. Empty entries are dropped: an HMAC key of ''
// is valid, so a blanked env var (OLD_SECRET=) would let anyone sign events.
const secrets = [].concat(signingSecrets).filter((s) => typeof s === 'string' && s.length > 0);
if (secrets.length === 0) return false;
const actual = Buffer.from(match[2], 'hex');
return secrets.some((signingSecret) => {
const expected = createHmac('sha256', signingSecret)
.update(match[1] + '.')
.update(rawBody)
.digest();
return actual.length === expected.length && timingSafeEqual(actual, expected);
});
}
function receiveHeiloWebhook(rawBody, signatureHeader, signingSecrets) {
if (!signatureHeader) {
// The ONLY unsigned exception confirms the endpoint; never enqueue it for CRM writes.
const probe = JSON.parse(rawBody.toString('utf8'));
if (probe && typeof probe === 'object' && !Array.isArray(probe)
&& Object.keys(probe).length === 2
&& probe.event_type === 'webhook.subscription.verify'
&& typeof probe.challenge === 'string') {
return { kind: 'verification', response: { challenge: probe.challenge } };
}
throw new Error('Missing Heilo-Signature');
}
if (!verifyHeiloSignature(rawBody, signatureHeader, signingSecrets)) throw new Error('Invalid Heilo-Signature');
return { kind: 'event', event: JSON.parse(rawBody.toString('utf8')) };
}
// HTTP adapter: limit body size; map verification to 200 JSON response.
// Signature errors -> 401 (pauses delivery; fix the secret, then Reverify). JSON errors -> 400.
// For kind=event: validate the envelope and chosen event_type, ignore webhook.test
// in business flows, then durably deduplicate/enqueue by event_id BEFORE returning 2xx.
// Enqueue failure: return 503. An HTTP acknowledgement is not proof of a CRM write.Estos ejemplos aceptan firmas de hasta 600 segundos (10 minutos) de antigüedad y 300 segundos (5 minutos) en el futuro, igual que el verificador actual de Heilo. Sincroniza los relojes. El control de tiempo limita la ventana de repetición; sigue siendo necesario deduplicar por event_id.
El secreto de firma se muestra solo una vez, al crear la suscripción. ¿Lo perdió o sospecha una filtración? Abra la suscripción en Configuración → Integraciones → Webhooks y rótelo allí — vea «Rotación del secreto» más abajo. No hace falta eliminar la suscripción y volver a crearla.
Rotación del secreto
Heilo siempre envía exactamente una firma v1, nunca dos a la vez. La rotación funciona por orden de instalación, no enseñando a su receptor a analizar varias firmas.
- Prepare un secreto nuevo en la configuración de la suscripción. Se muestra una sola vez y espera hasta 24 horas para activarse.
- Instale el secreto nuevo JUNTO AL actual — su receptor debe aceptar una firma hecha con cualquiera de los dos.
- Opcionalmente envíe una prueba firmada con el secreto nuevo. Lleva la cabecera Heilo-Secret-Rotation-Id y un cuerpo webhook.test normal; una respuesta 2xx no prueba que su receptor comprobó la firma — confírmelo en su propio registro.
- Active la rotación.
- Mantenga instalado el secreto anterior 1 hora después de la activación y luego elimínelo.
Heilo no cambia nada en su receptor. Durante ese periodo es su receptor el que debe aceptar una firma hecha con cualquiera de los dos secretos.
Emergencia: el secreto se filtró
Una rotación de emergencia pausa el envío de inmediato. Instale SOLO el secreto nuevo — trate el anterior como comprometido — y luego actívelo; no hay ventana de gracia. Reanude el envío después con «Volver a verificar». Las entregas que ya estaban en cola al pausar se omiten; reenvíelas desde el registro de entregas.
¿Perdió el secreto sin filtración? Una rotación estándar también funciona — no hace falta eliminar la suscripción.
Tipos de evento
Elija los event_types al crear una suscripción. Cada evento tiene un event_id único (UUID v5) y se deduplica por suscripción.
webhook.test lo envía la acción manual Probar y tiene data._test = true. Pasa por la misma cola de entregas que los eventos reales, así que puede llegar un momento después del clic, y su resultado aparece como estado en el registro de entregas. Úsalo para mapear campos y luego exclúyelo del procesamiento de negocio. El handshake de activación, aparte, es webhook.subscription.verify.
| event_type | Descripción |
|---|---|
| call.completed | Llamada completada, transcripción lista |
| call.missed | Llamada entrante terminada sin transcripción (perdida, sin mensaje o no grabada) |
| call.outbound.attempted | Intento de llamada saliente en estado final (conectada o fallida) |
| call.recording.ready | Archivo de grabación disponible para descargar |
| call.transcribed | Transcripción lista (separada de call.completed) |
| call.failed | Llamada fallida (ocupado/sin respuesta/error) |
| call.outbound.lifecycle_repaired | Corrección del ciclo de vida saliente: estado de la llamada reparado |
| call.deletion_scheduled | Llamada programada para eliminación (RGPD art. 17, retención) |
| call.recording.deleted | Grabación eliminada (RGPD) |
| call.followup_email.drafted | Borrador de correo de seguimiento listo |
| call.outcome.changed | Resultado de la llamada establecido o cambiado |
| call.user_notes.changed | Apuntes de la llamada añadidos, editados o eliminados |
| call.tracker.matched | Tracker coincidió |
| contact.created | Nuevo contacto creado |
| contact.updated | Contacto actualizado |
A continuación, el objeto data de cada evento. Los nombres de campo, tipos y valores enumerados forman parte del contrato de la API y no cambian de significado dentro de v1; con el tiempo pueden añadirse nuevos campos opcionales.
call.completed
Se envía tras procesar la grabación y la transcripción de una llamada completada. La fuente de datos principal para un CRM: payload completo (incluidos recording_url y la transcripción procesada).
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.completed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"duration": 87,
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"outcome": "quote_to_send",
"outcome_source": "ai"
}
}| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| direction | 'inbound' | 'outbound' | Dirección de la llamada. |
| caller_phone | string | null | Número guardado del llamante; null si no está disponible en call.completed. |
| customer_phone_e164 | string | null | Número del cliente para buscar el contacto en el CRM; null si no está disponible en call.completed. |
| customer_phone_national | string | null | El mismo número del cliente en formato nacional, listo para pegar en un campo de teléfono del CRM; null cuando el valor guardado no es un número utilizable, por ejemplo con un identificador oculto. |
| company_phone_e164 | string | null | El número por el que entró o salió esta llamada. Normalmente tu número de Heilo; en una llamada desviada es tu propio número, el que la desvió. Sirve para encaminar notas cuando tienes más de un número; null si no se registró. |
| call_created_at | string (ISO 8601) | null | Cuándo se registró la llamada en Heilo (ISO 8601). No es lo mismo que el created_at del sobre, que es el momento del envío y puede ser días posterior en un evento reparado. |
| app_url | string | null | Enlace permanente a la llamada en Heilo. A diferencia de recording_url no caduca, así que puede guardarse en un registro del CRM. Abrirlo requiere iniciar sesión en Heilo. |
| duration | number | Duración de la grabación en segundos. |
| recording_url | string | null | Enlace a la grabación, válido 7 días; null cuando la grabación aún no estaba guardada al procesar. Cuando caduque, obtén un enlace nuevo con GET /calls/:id/recording-url. |
| transcript_processed | object | Análisis procesado de la llamada; consulte la referencia de campos de transcript_processed en esta sección. |
| transcript_original | string | null | Transcripción literal sin procesar; null cuando no está disponible. |
| outcome | string | null | Código de resultado en el momento en que se construyó el evento (consulta los códigos de resultado más abajo); null si nadie lo ha establecido. La clave no aparece en la reproducción de un evento antiguo o cuando Heilo no pudo leerla. Un call.outcome.changed posterior prevalece. |
| outcome_source | 'ai' | 'user' | null | Quién estableció el resultado: ai (lo eligió el análisis), user (lo eligió o confirmó una persona) o null (nadie). Falta siempre que falta outcome. |
La entrega es al menos una vez y no se garantiza el orden: persista de forma idempotente. Clave de deduplicación: event_id. data.call_id vincula los eventos de la misma llamada (p. ej. call.completed después de call.recording.ready).
Resultado de la llamada
outcome es uno de los códigos de abajo o null si nadie lo ha establecido. outcome_source indica quién lo estableció: ai o user. REST devuelve ambos campos en cada llamada; call.completed y call.transcribed los llevan en el nivel superior de data; call.outcome.changed informa de cada cambio posterior. Pueden añadirse códigos nuevos, así que trata un valor desconocido como información adicional, no como un error.
| Código | Significado |
|---|---|
| booking | Se acordó una reserva, una visita o una cita. |
| cancellation_or_reschedule | Quien llamó canceló o pide una nueva fecha. |
| information_request | Quien llamó pidió información. |
| quote_to_send | Quien llamó espera un presupuesto u oferta. |
| awaiting_customer_decision | El cliente lo está pensando y avisará. |
| deal_won | El cliente aceptó en la llamada comprar, hacer un pedido o la oferta. Ejecuta una automatización de «ganado» en tu CRM solo cuando outcome_source sea user. |
| callback_scheduled | Se acordó un nuevo contacto. |
| not_interested | Quien llamó no está interesado. |
| spam_wrong_number | Mensaje vacío, spam o número equivocado. |
| new_opportunity | Una nueva oportunidad de venta.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| existing_deal_update | Una actualización de un proyecto existente.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| follow_up | Un contacto de seguimiento tras uno anterior.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| no_answer | Nadie contestó.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| voicemail | Quien llamó dejó un mensaje de voz.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| support | Una solicitud de soporte.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
| complaint | Una reclamación.antiguo: ya no se ofrece, aún puede aparecer en llamadas anteriores |
Qué valor prevalece
Un evento call.outcome.changed prevalece sobre el resultado de call.completed y call.transcribed, en el orden en que lleguen. Ordena los eventos de cambio por data.changed_at, nunca por la hora de llegada ni por el created_at del sobre. REST siempre devuelve el valor actual, así que con él recuperas un evento perdido.
data.outcome es un código de la tabla de arriba. No es lo mismo que transcript_processed.call_outcome, una frase de texto libre del análisis.
Zapier y Make: el botón Test envía la forma de call.completed. Para obtener un ejemplo de call.outcome.changed, elige un resultado en cualquier llamada en Heilo.
Apuntes de la llamada (user_notes)
user_notes es la lista de entradas que las personas escribieron sobre una llamada en Heilo («Apuntes de la llamada»). REST la devuelve solo en GET /calls/:id; call.user_notes.changed envía la lista actual completa unos cinco minutos después del último cambio. El autor es el nombre completo del perfil de Heilo, nunca una dirección de correo.
Qué lista prevalece
Cada lista lleva una revision que crece con cada cambio. Sustituya su copia por una lista solo cuando su revision sea mayor que la que tiene, y descarte cualquier otra: un reenvío manual vuelve a entregar una lista más antigua. REST siempre devuelve la lista actual, así que úselo para recuperar un evento perdido.
source indica de dónde viene una entrada: live (escrita en la pantalla de la llamada durante la llamada), after (añadida después) o legacy (la única nota de la llamada anterior al 28/10/2026). Pueden añadirse nuevos valores, así que trate un valor desconocido como información opcional y no como un error. recording_offset_seconds solo se rellena en una entrada live escrita dentro de la grabación.
Zapier y Make: el botón Test envía la forma de call.completed. Para obtener una muestra de call.user_notes.changed, añada una entrada a cualquier llamada en Heilo y espere cinco minutos.
call.missedNormalmente se envía unas dos horas después de una llamada entrante que terminó sin transcripción, y hasta unas 4 h 15 min más tarde cuando no se informó del final de la llamada. data.reason indica el motivo y data.answered indica si alguien contestó. Los casos son: nadie contestó y no se dejó mensaje, quien llamó colgó antes de que empezara la grabación, la grabación estaba desactivada para el número en ese momento, Heilo no grabó la llamada a propósito, la grabación fue demasiado corta o no se pudo generar la transcripción. También se envía una llamada contestada que no tiene transcripción, con answered en true, así que crea una devolución de llamada solo cuando answered sea false. Desactivado por defecto: añade call.missed a los eventos de un endpoint para recibirlo; un endpoint que lo añada más tarde también puede recibir estas llamadas de los últimos 7 días, así que comprueba call_created_at. Se envía como máximo una vez por llamada. No se garantiza el orden: si existe un call.completed para el mismo call_id (una grabación que llegó tarde o una llamada de más de dos horas), call.completed describe la llamada, llegue antes o después; suscríbete a ambos para ver esas llamadas. Un borrado en Heilo se anuncia con call.deletion_scheduled o call.recording.deleted solo para una llamada que tenía grabación; una llamada sin grabación no recibe evento de borrado, así que elimina tu copia tú mismo si lo necesitas. Las llamadas a las que añadiste Heilo no se incluyen. Zapier y Make: el botón Test envía la forma de call.completed; para una muestra de call.missed, llama a tu número de Heilo, cuelga antes de que alguien conteste y espera unas dos horas.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| direction | 'inbound' | Dirección de la llamada. |
| customer_phone_e164 | string | null | Número del cliente para buscar el contacto en el CRM; null si no está disponible en call.completed. |
| customer_phone_national | string | null | El mismo número del cliente en formato nacional, listo para pegar en un campo de teléfono del CRM; null cuando el valor guardado no es un número utilizable, por ejemplo con un identificador oculto. |
| company_phone_e164 | string | null | El número por el que entró o salió esta llamada. Normalmente tu número de Heilo; en una llamada desviada es tu propio número, el que la desvió. Sirve para encaminar notas cuando tienes más de un número; null si no se registró. |
| call_created_at | string (ISO 8601) | null | Cuándo se registró la llamada en Heilo (ISO 8601). No es lo mismo que el created_at del sobre, que es el momento del envío y puede ser días posterior en un evento reparado. |
| app_url | string | null | Enlace permanente a la llamada en Heilo. A diferencia de recording_url no caduca, así que puede guardarse en un registro del CRM. Abrirlo requiere iniciar sesión en Heilo. |
| reason | 'no_recording' | 'capture_refused' | 'no_speech' | 'not_transcribed' | Por qué no hay transcripción: no_recording — no se grabó nada (nadie contestó y no se dejó mensaje, quien llamó colgó antes de que empezara la grabación o la grabación estaba desactivada para este número en ese momento); capture_refused — Heilo no grabó la llamada a propósito (tu plan o periodo de prueba no incluye la grabación, o el número está en la lista “No grabar”); no_speech — la grabación fue demasiado corta para contener un mensaje (tres segundos o menos); not_transcribed — existe una grabación pero no se pudo obtener una transcripción útil. Lee answered para saber si alguien contestó. Pueden añadirse nuevos valores. |
| has_recording | boolean | true cuando existe una grabación de esta llamada; una clave de API con el permiso read.recordings obtiene un enlace con GET /calls/:id/recording-url. |
| answered | boolean | true cuando la llamada se puso en comunicación y fue contestada, por ejemplo una conversación que Heilo no grabó; false cuando nadie contestó. Crea una devolución de llamada solo cuando sea false. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.missed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "no_recording",
"has_recording": false,
"answered": false
}
}call.outbound.attemptedSe envía cuando un intento de llamada saliente alcanza un estado final, incluidos los fallos. completed significa que la llamada se estableció y terminó con normalidad; la grabación y la transcripción llegan como eventos separados.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| agent_user_id | string (uuid) | Identificador del usuario de Heilo que realizó la llamada. |
| customer_phone | string | Número del cliente marcado. |
| customer_phone_e164 | string | Número del cliente para buscar el contacto en el CRM; null si no está disponible en call.completed. |
| outbound_lifecycle | 'completed' | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate' | Estado final que desencadenó el evento; completed significa que la llamada se estableció y terminó con normalidad. |
| duration | number | null | Duración de la llamada en segundos; null cuando la llamada falló al iniciarse o la duración aún no se conoce. |
| attempted_at | string (ISO 8601) | Momento de emisión del evento (ISO 8601). |
| has_recording | boolean | true solo cuando outbound_lifecycle es completed y la llamada no estaba en modo no_recording; la grabación llega entonces como call.recording.ready. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outbound.attempted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"agent_user_id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"customer_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"outbound_lifecycle": "completed",
"duration": 95,
"attempted_at": "2026-09-08T10:00:00Z",
"has_recording": true
}
}call.recording.readySe envía cuando el archivo de la grabación está disponible. Úselo para obtener o archivar el audio.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| recording_url | string | null | Enlace a la grabación, válido 7 días; en casos raros null, cuando no se pudo generar el enlace. Cuando caduque, obtén un enlace nuevo con GET /calls/:id/recording-url. |
| duration | number | null | Duración en segundos; null cuando aún no se conoce. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.recording.ready",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"duration": 87
}
}call.transcribedSe envía en el mismo procesamiento que call.completed: contiene solo la transcripción, sin metadatos de la llamada ni enlace a la grabación.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| transcript_original | string | null | Transcripción literal sin procesar; null cuando no está disponible. |
| transcript_processed | object | Análisis procesado de la llamada; consulte la referencia de campos de transcript_processed en esta sección. |
| outcome | string | null | Código de resultado en el momento en que se construyó el evento (consulta los códigos de resultado más abajo); null si nadie lo ha establecido. La clave no aparece en la reproducción de un evento antiguo o cuando Heilo no pudo leerla. Un call.outcome.changed posterior prevalece. |
| outcome_source | 'ai' | 'user' | null | Quién estableció el resultado: ai (lo eligió el análisis), user (lo eligió o confirmó una persona) o null (nadie). Falta siempre que falta outcome. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.transcribed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"outcome": "quote_to_send",
"outcome_source": "ai"
}
}call.failedSe envía cuando una llamada saliente no se completó (sin respuesta, ocupado, error al iniciar). Solo afecta a llamadas salientes. Normalmente no conviene crear un lead; registre un intento de contacto.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| outbound_lifecycle | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate' | Qué fase de la llamada saliente falló. |
| failure_reason | string | null | Código técnico del motivo (p. ej. customer_busy, agent_no_confirmation o carrier_rejected cuando el operador rechazó la llamada al teléfono del comercial); puede ser null. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.failed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"outbound_lifecycle": "customer_no_answer",
"failure_reason": "customer_busy"
}
}call.outbound.lifecycle_repairedSe envía cuando Heilo corrige retroactivamente el estado de una llamada saliente (una confirmación tardía del operador demostró que la llamada sí se estableció). Actualice el estado de la llamada en su sistema.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| previous_lifecycle | 'agent_only' | Estado antes de la corrección; actualmente siempre agent_only. |
| new_lifecycle | 'completed' | Estado tras la corrección; actualmente siempre completed. |
| repaired_at | string (ISO 8601) | Momento de la corrección (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outbound.lifecycle_repaired",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"previous_lifecycle": "agent_only",
"new_lifecycle": "completed",
"repaired_at": "2026-09-08T10:00:00Z"
}
}call.deletion_scheduledRGPD art. 17: la llamada está programada para su eliminación. Su CRM debería dejar de usar la grabación y prepararse para eliminar los datos. Solo se le informa de una llamada si Heilo tiene constancia de que su contenido pudo llegar a su endpoint. Suscribirse únicamente a los eventos de borrado no le convierte en destinatario: no hay nada que borrar si nunca recibió nada.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| pending_deletion_at | string (ISO 8601) | Cuándo se eliminarán definitivamente los datos (ISO 8601). |
| reason | 'consent_not_asked' | 'consent_withdrawn' | 'retention_expired' | 'user_erasure' | Motivo de la eliminación programada. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.deletion_scheduled",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pending_deletion_at": "2026-09-09T10:00:00Z",
"reason": "retention_expired"
}
}call.recording.deletedRGPD: la grabación se eliminó; recording_url devuelve 410. Elimine o desactive el enlace de la grabación por su parte. Cuando `reason` no es `retention_expired`, también se borraron la transcripción, el resumen, los datos extraídos de la llamada y los apuntes de la llamada: bórrelos también por su parte. Las llamadas movidas a la papelera llegan como este evento con el motivo `user_erasure` 30 días después. Solo se le informa de una llamada si Heilo tiene constancia de que su contenido pudo llegar a su endpoint, por lo que esto no es un registro completo de todos los borrados de su organización. Un 2xx por su parte significa que la instrucción llegó, nunca que la copia haya desaparecido.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| reason | string | null | Motivo registrado al programar la eliminación; puede ser null. |
| recording_sid | string | null | Identificador de la grabación en Twilio; null cuando no se pudo determinar. |
| deletion_kind | 'hard_deleted' | 'twilio_404' | hard_deleted = eliminada por Heilo; twilio_404 = el archivo ya no existía en Twilio. |
| deleted_at | string (ISO 8601) | Momento de la eliminación de la grabación (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.recording.deleted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "user_erasure",
"recording_sid": null,
"deletion_kind": "twilio_404",
"deleted_at": "2026-09-08T10:00:00Z"
}
}call.followup_email.draftedSe envía después de procesar una llamada bidireccional cuando Heilo ha redactado un borrador de correo de seguimiento a partir de lo acordado. No se envía para el buzón de voz ni cuando no se pudo redactar. Heilo NUNCA envía este correo a la persona que llamó — el borrador es para que tu comercial lo revise y lo envíe.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| subject | string | Asunto del correo, listo para pegar. |
| body | string | Cuerpo del correo en texto plano, SIN firma — el comercial añade la suya al enviarlo. |
| language | string | Idioma del borrador: el idioma detectado de la llamada o, en su defecto, el idioma de la cuenta configurado en Heilo (no un ajuste por número). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.followup_email.drafted",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subject": "Oferta po rozmowie",
"body": "Dzień dobry, przesyłam ustalenia naszej rozmowy.",
"language": "pl"
}
}call.outcome.changedSe envía cada vez que cambia el resultado de una llamada: alguien lo elige, cambia, confirma o borra en Heilo, o un nuevo análisis cambia el resultado que Heilo eligió antes. El resultado que Heilo elige en el primer análisis de la grabación no tiene evento propio; llega en call.completed y call.transcribed. Un resultado elegido por primera vez solo en un nuevo análisis posterior sí envía call.outcome.changed. No se envía para llamadas en la papelera o programadas para eliminación. Los eventos de cambio prevalecen sobre el resultado de call.completed y call.transcribed; ordénalos por data.changed_at.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| outcome | string | null | El resultado tras el cambio; null si se borró o se retiró. |
| outcome_source | 'ai' | 'user' | null | Quién lo estableció tras el cambio: ai, user o null. Un resultado vacío con user significa que una persona lo borró; un resultado vacío con null significa que el análisis retiró su elección. |
| previous_outcome | string | null | El resultado antes del cambio; null si no había ninguno. |
| previous_outcome_source | 'ai' | 'user' | null | Quién había establecido el resultado anterior: ai, user o null. |
| changed_at | string (ISO 8601) | Cuándo se guardó el cambio (ISO 8601). Ordena por él los eventos de cambio: el que tiene el changed_at más reciente es el vigente. No es el created_at del sobre. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.outcome.changed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"outcome": "booking",
"outcome_source": "user",
"previous_outcome": "quote_to_send",
"previous_outcome_source": "ai",
"changed_at": "2026-09-08T10:05:00Z"
}
}call.user_notes.changedSe envía cuando cambian las entradas que las personas escribieron sobre una llamada en Heilo («Apuntes de la llamada»): alguien añade, edita o elimina una entrada. data.notes es la lista actual COMPLETA, no una diferencia, así que su CRM sustituye su copia en lugar de combinarla. El evento sale unos cinco minutos después del último cambio (para las entradas escritas durante una llamada: unos cinco minutos después de la llamada) y nunca más de una vez cada cinco minutos por llamada. data.revision crece con cada cambio; descarte una lista cuya revision no sea mayor que la que ya tiene (un reenvío manual vuelve a enviar una lista más antigua). No se envía para llamadas en la papelera o programadas para eliminación.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| revision | integer | Contador que crece con cada cambio de las entradas de la llamada. Guarde la revision más alta que haya visto para la llamada y descarte toda lista cuya revision no sea mayor; un reenvío manual o una repetición entrega una lista más antigua. |
| changed_at | string (ISO 8601) | Cuándo construyó Heilo esta lista (ISO 8601). No es el created_at del sobre ni el momento en que alguien editó una entrada. |
| notes | object[] | La lista actual completa de entradas, de la más antigua a la más reciente, como máximo 200; vacía cuando se eliminó la última entrada. Sustituya su copia por ella. |
| notes[].id | string (uuid) | Identificador de la entrada; no cambia al editar el texto. |
| notes[].body | string | El texto de la entrada, de 1 a 2000 caracteres. |
| notes[].source | 'live' | 'after' | 'legacy' | live: escrita en la pantalla de la llamada durante la llamada. after: añadida después en Heilo. legacy: la única nota de la llamada anterior al 28/10/2026, pasada a las entradas. Pueden añadirse nuevos valores. |
| notes[].author.id | string (uuid) | null | El usuario de Heilo que escribió la entrada. Null en una entrada legacy o cuando esa cuenta fue eliminada. |
| notes[].author.name | string | null | El nombre completo del autor según su perfil de Heilo; null cuando el perfil no lo tiene. Nunca una dirección de correo. Un cambio de nombre posterior aparece en la lista siguiente, sin un evento propio. |
| notes[].noted_at | string (ISO 8601) | Cuándo la escribió la persona (ISO 8601); en una entrada live, el momento durante la llamada. |
| notes[].recording_offset_seconds | integer | null | Segundos desde el inicio de la grabación, solo para una entrada escrita durante la llamada dentro de la grabación; null en los demás casos. |
| notes[].created_at | string (ISO 8601) | Cuándo se guardó la entrada (ISO 8601). |
| notes[].updated_at | string (ISO 8601) | Última edición del texto (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.user_notes.changed",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"revision": 3,
"changed_at": "2026-09-08T10:12:00Z",
"notes": [
{
"id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"body": "Klient prosi o telefon po 10:00.",
"source": "live",
"author": {
"id": "2ce127a0-c621-483d-b576-e68f69d95e84",
"name": "Anna Nowak"
},
"noted_at": "2026-09-08T10:01:12Z",
"recording_offset_seconds": 72,
"created_at": "2026-09-08T10:01:12Z",
"updated_at": "2026-09-08T10:01:12Z"
}
]
}
}call.tracker.matchedSe envía cuando al menos un tracker de palabras clave coincide con la transcripción procesada. Incluye términos y fragmentos; si faltan fragmentos, la lista está vacía.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| matches | object[] | Trackers encontrados en esta llamada. |
| matches[].tracker_id | string (uuid) | Identificador del tracker configurado. |
| matches[].name | string | Nombre del tracker. |
| matches[].matched_terms | string[] | Términos encontrados. |
| matches[].excerpts | string[] | Fragmentos de transcripción; puede estar vacío. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "call.tracker.matched",
"resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"matches": [
{
"tracker_id": "cd794362-6117-44d1-b487-c5e7e1ea9082",
"name": "Oferta",
"matched_terms": [
"ofertę"
],
"excerpts": [
"Proszę o ofertę w przyszłym tygodniu."
]
}
]
}
}contact.createdSe envía al crear un contacto nuevo en Heilo. data.contact es una instantánea completa del contacto nuevo; no incluye notas ni etiquetas.
| Campo | Tipo | Descripción |
|---|---|---|
| contact | object | Instantánea completa del contacto nuevo (campos abajo). |
| contact.id | string (uuid) | Identificador del contacto en Heilo. |
| contact.phone | string | Número de teléfono del contacto. |
| contact.first_name | string | null | null si no se indicó. |
| contact.last_name | string | null | null si no se indicó. |
| contact.email | string | null | null si no se indicó. |
| contact.company | string | null | null si no se indicó. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "contact.created",
"resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"contact": {
"id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"phone": "+447700900123",
"first_name": "Alicja",
"last_name": "Testowa",
"email": "alicja@example.com",
"company": null
}
}
}contact.updatedSe envía al editar un contacto. A diferencia de contact.created, no es una instantánea: data.diff contiene solo los campos modificados.
| Campo | Tipo | Descripción |
|---|---|---|
| contact_id | string (uuid) | Identificador del contacto actualizado. |
| diff | object (partial) | Solo los campos modificados; las claves ausentes de diff no cambiaron. |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "contact.updated",
"resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"contact_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
"diff": {
"company": "Example",
"notes": "Oddzwonić",
"tags": [
"oferta"
]
}
}
}Claves posibles en diff: first_name, last_name, email, phone, company, notes, tags
webhook.testSe envía solo al pulsar Test en una suscripción. resource_id identifica la suscripción, no una llamada. data contiene datos sintéticos de call.completed y los tres marcadores descritos abajo. No demuestra que exista audio real.
| Campo | Tipo | Descripción |
|---|---|---|
| call_id | string (uuid) | ID de llamada en Heilo. Coincide con resource_id en eventos de llamadas de negocio; en webhook.test es un ID sintético. |
| direction | 'inbound' | 'outbound' | Dirección de la llamada. |
| caller_phone | string | null | Número guardado del llamante; null si no está disponible en call.completed. |
| customer_phone_e164 | string | null | Número del cliente para buscar el contacto en el CRM; null si no está disponible en call.completed. |
| customer_phone_national | string | null | El mismo número del cliente en formato nacional, listo para pegar en un campo de teléfono del CRM; null cuando el valor guardado no es un número utilizable, por ejemplo con un identificador oculto. |
| company_phone_e164 | string | null | El número por el que entró o salió esta llamada. Normalmente tu número de Heilo; en una llamada desviada es tu propio número, el que la desvió. Sirve para encaminar notas cuando tienes más de un número; null si no se registró. |
| call_created_at | string (ISO 8601) | null | Cuándo se registró la llamada en Heilo (ISO 8601). No es lo mismo que el created_at del sobre, que es el momento del envío y puede ser días posterior en un evento reparado. |
| app_url | string | null | Enlace permanente a la llamada en Heilo. A diferencia de recording_url no caduca, así que puede guardarse en un registro del CRM. Abrirlo requiere iniciar sesión en Heilo. |
| duration | number | Duración de la grabación en segundos. |
| recording_url | string | null | Enlace a la grabación, válido 7 días; null cuando la grabación aún no estaba guardada al procesar. Cuando caduque, obtén un enlace nuevo con GET /calls/:id/recording-url. |
| transcript_processed | object | Análisis procesado de la llamada; consulte la referencia de campos de transcript_processed en esta sección. |
| transcript_original | string | null | Transcripción literal sin procesar; null cuando no está disponible. |
| outcome | string | null | Código de resultado en el momento en que se construyó el evento (consulta los códigos de resultado más abajo); null si nadie lo ha establecido. La clave no aparece en la reproducción de un evento antiguo o cuando Heilo no pudo leerla. Un call.outcome.changed posterior prevalece. |
| outcome_source | 'ai' | 'user' | null | Quién estableció el resultado: ai (lo eligió el análisis), user (lo eligió o confirmó una persona) o null (nadie). Falta siempre que falta outcome. |
| _test | true | Siempre true; distingue el mensaje de prueba de los eventos reales. |
| _message | string | Aviso legible de que se trata de una prueba. |
| _sent_at | string (ISO 8601) | Momento del envío de la prueba (ISO 8601). |
{
"api_version": "2026-06-15",
"event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
"event_type": "webhook.test",
"resource_id": "c2d38cc8-bc1d-4336-91ea-51b8a549a882",
"created_at": "2026-09-08T10:00:00Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"direction": "inbound",
"caller_phone": "+447700900123",
"customer_phone_e164": "+447700900123",
"customer_phone_national": "07700 900123",
"company_phone_e164": "+48222630000",
"call_created_at": "2026-09-08T10:00:00Z",
"app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"duration": 87,
"recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
"transcript_processed": {
"caller_name": "Alicja Testowa",
"counterparty_name": null,
"counterparty_email": null,
"caller_location": "Warszawa, Mokotów",
"client_address": "ul. Przykładowa 10",
"client_city": "Warszawa",
"client_country": "Poland",
"service_needed": "Tynki gipsowe w mieszkaniu 65m²",
"services_match": true,
"preferred_date": "w przyszłym tygodniu",
"additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
"lead_score": 7,
"summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
"subject": "Wycena tynków — Warszawa, 65 m²",
"detected_language": "pl"
},
"transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
"outcome": "quote_to_send",
"outcome_source": "ai",
"_test": true,
"_message": "Synthetic webhook test; do not create CRM records.",
"_sent_at": "2026-09-08T10:00:00Z"
}
}transcript_processed: referencia de campos
El subconjunto estable en el que puede confiar al mapear a un CRM. Todos los campos son opcionales: valen null cuando la llamada no contenía esa información.
| Campo | Tipo | Descripción |
|---|---|---|
| caller_name | string | null | Nombre del llamante, si lo dio. |
| summary | string | null | Resumen breve de la llamada. |
| subject | string | null | Título de una línea de la llamada (hasta 80 caracteres). |
| service_needed | string | null | Qué pidió el llamante. |
| services_match | boolean | null | Si la petición encaja con los servicios que usted ofrece. |
| lead_score | number | null (1–10) | Estimación de la calidad del lead, de 1 a 10, o null si la IA no dio ninguna. |
| preferred_date | string | null | Fecha u hora mencionada por el llamante, si la hubo. |
| client_city | string | null | Ciudad, si se mencionó. |
| client_address | string | null | Dirección, si se mencionó. |
| additional_details | string | null | Contexto adicional de la llamada. |
Campos que pueden aparecer
| Campo | Tipo | Descripción |
|---|---|---|
| caller_location | string | null | Referencia geográfica detectada en la conversación. |
| client_country | string | null | País, si se mencionó. |
| counterparty_name | string | null | Nombre de la otra parte — solo en llamadas salientes y en llamadas en vivo a las que se ha añadido a Heilo. |
| counterparty_email | string | null | Correo electrónico del cliente tal como se dijo en la llamada y comprobado con la transcripción — solo en llamadas en vivo a las que se ha añadido a Heilo. |
| detected_language | string | Código de idioma de la conversación (p. ej. pl); la clave puede faltar por completo. |
| proposal_items | object[] | null | Acciones y decisiones sugeridas extraídas de la llamada. |
El análisis puede incluir campos adicionales: trate los campos desconocidos como opcionales y no dé por hecha su presencia.
Roadmap (v1.1+)
Endpoints previstos para próximas versiones v1.X. No es un compromiso firme: la dirección depende de sus comentarios.
- GET /contacts — listar contactos
- POST /contacts — crear contacto (sincronizar desde el CRM hacia Heilo)
- POST /calls — iniciar una llamada saliente a través de su número Heilo; se graba, se transcribe y se entrega a su CRM como cualquier otra llamada
¿Necesita un endpoint? Escriba a support@heilo.io con su caso de uso: priorizamos el roadmap según la demanda real.
Roadmap (v1.1+)
¿Necesita un endpoint? Escriba a support@heilo.io con su caso de uso: priorizamos el roadmap según la demanda real.
Gestione claves y webhooks en el panel
Tras iniciar sesión podrá generar claves API, añadir suscripciones de webhooks y consultar el historial de envíos.