- Guías
- Enviar reportes a tu sistema de tickets
Enviar reportes a tu sistema de tickets
Abrí un ticket en tu propio sistema por cada reporte: tu URL, headers secretos, un body JSON con plantilla y OAuth 2.0 client credentials opcional.
Una integración API personalizada envía cada reporte que recibe Espejo (los que tus visitantes graban y mandan desde el widget, y los automáticos) a un endpoint HTTP que elegís, para que llegue como ticket a tu propio sistema. Vos definís la URL, los headers, el body y la autenticación; Espejo la llama desde su servidor, nunca desde el navegador del visitante.
Es de un solo sentido: Espejo crea el ticket y registra si tu API lo aceptó. No lee los tickets de vuelta.
Agregarla
Sección titulada «Agregarla»En la consola, abrí Project settings → Integrations → Reports y elegí
+ Custom API. Un proyecto puede tener varias, cada una con su nombre (por ejemplo
Nexus) y su propia elección de qué reportes recibe.
| Campo | Qué es |
|---|---|
| Name | Cómo se llama la integración en la consola. Hasta 60 caracteres. |
| Request URL y método | POST (por defecto), PUT o PATCH. Solo https, y el host tiene que resolver a una dirección pública. |
| Headers | Hasta 10. Cada uno con nombre y valor. |
| Body | Una plantilla JSON con variables. |
| Authentication | Ninguna, o OAuth 2.0 client credentials. |
Después abrí la integración y elegí Which reports go here:
- Only reports with errors: reportes con un HTTP 4xx o 5xx o un error de consola. Es el valor por defecto.
- Every report.
- None: la dejás configurada pero callada.
Con Send test mandás un reporte de muestra con lo que tenés guardado, antes de que llegue uno real. Sale aunque la integración esté en None.
Headers
Sección titulada «Headers»Cada header tiene nombre y valor. El valor es un secreto: se guarda cifrado y la consola no lo vuelve a mostrar. Para cambiarlo, escribí uno nuevo; para conservarlo, dejá el campo vacío.
Usalos para lo que pida tu API: una API key (X-Api-Key), un Authorization: Bearer ...
fijo, un id de tenant.
Espejo manda Content-Type: application/json y Accept: application/json; un header
tuyo con el mismo nombre los reemplaza. No se pueden definir: Host, Content-Length,
Connection, Keep-Alive, Transfer-Encoding, TE, Trailer, Upgrade, Expect,
Cookie, Set-Cookie, ni ningún nombre que empiece con Proxy- o Sec-. El valor
tiene que ser una sola línea de hasta 2048 caracteres. Con OAuth, Espejo pone
Authorization por su cuenta, así que no agregues el tuyo.
Plantilla del body
Sección titulada «Plantilla del body»El body es JSON con marcadores {{variable}}. Este es el de por defecto:
{ "title": "{{title}}", "description": "{{summary}}", "type": "{{type}}", "external_id": "{{session_id}}", "reporter": "{{user_email}}", "replay_url": "{{replay_url}}"}{{nombre}}va dentro de un string JSON. El valor se escapa por vos (comillas, saltos de línea, barras), así que un texto escrito por un visitante no puede romper el JSON. Un valor que falta queda como string vacío.{{json:nombre}}inserta el valor como JSON tal cual:42,true,null,"texto". Usalo para números y booleanos, por ejemplo"errors": {{json:errors_5xx}}.
Espejo valida la plantilla al guardarla: toda variable tiene que existir y el resultado,
con valores de muestra, tiene que ser un objeto o arreglo JSON válido. Si no, responde
400 con el motivo. La plantilla puede tener hasta 20.000 caracteres.
| Variable | Valor |
|---|---|
title | [Espejo] y el título del reporte, si vino con uno; si no, [Espejo] y los primeros 120 caracteres de la descripción; si tampoco hay, [Espejo] Reporte en <sitio>. Ver Cómo se arma el título. |
summary | Un texto de varias líneas: link al replay, proyecto, sitio, usuario, duración, conteo de errores y el primer error. Sus etiquetas están en español. |
message | La descripción, completa. Vacío si no hay. |
type | bug si el reporte tiene un HTTP 4xx o 5xx o un error de consola, si no report. |
has_errors | true o false. |
replay_url | Link a la grabación en la consola. No vence, pero quien lo abre necesita una cuenta de Espejo en el proyecto. |
share_url | Link público a la grabación, firmado y válido por 72 horas. Cualquiera que lo tenga puede verla, sin cuenta. Solo en el plan Team; vacío en Free. |
share_expires_at | Cuándo deja de funcionar share_url, ISO 8601. Vacío si no hay share_url. |
session_id | El id de la grabación. Un mismo reporte siempre lleva el mismo, usalo para evitar duplicados. |
project | El nombre del proyecto. |
page_host | El host de la página donde se reportó. |
user_ref | La referencia de usuario que tu sitio le pasó al SDK. |
user_email | user_ref, solo si parece una dirección de correo. |
duration_ms | Duración de la grabación, en milisegundos. |
errors_5xx, errors_4xx, errors_console | Los conteos de errores. |
first_error | Un extracto del primer error de consola. |
sent_at | Cuándo lo envió Espejo, ISO 8601. |
summary y message llevan hasta 20.000 caracteres, y user_ref hasta 200.
Cómo se arma el título
Sección titulada «Cómo se arma el título»title siempre es [Espejo] seguido de una de estas opciones, en este orden:
- El título que la página mandó con el reporte:
espejo.report({ title, description }). Una línea, de hasta 120 caracteres (uno más largo se corta). - Si no hay título, los primeros 120 caracteres de la descripción. El corte es ciego: no busca un punto ni un salto de línea, así que un texto largo termina a la mitad de una frase.
- Si no hay ninguno de los dos,
Reporte en <sitio>, o el nombre del proyecto si no se conoce el sitio.
El botón flotante tiene un solo campo de texto, así que sus reportes toman el segundo
camino. Para tener un título de verdad, mandá el reporte desde
tu propio botón con un objeto. La descripción completa
siempre llega en message, así que poné {{message}} en el campo donde tu sistema
espera el texto largo.
Si tu sistema quiere la descripción y el link al replay juntos, summary ya los trae.
message trae solo lo que escribió la persona.
El link público
Sección titulada «El link público»share_url es el mismo link del botón Copy link to share de la consola, firmado
en el momento en que Espejo envía el reporte. Deja de funcionar a las 72 horas
(share_expires_at), así que un ticket que siga abierto más tiempo va a tener el link
muerto. Dejá replay_url al lado para tu propio equipo, que no vence.
El link también deja de funcionar si la cuenta sale del plan Team o se desactiva, incluso antes de vencer. En el plan Free las dos variables llegan vacías.
Autenticación
Sección titulada «Autenticación»None alcanza cuando tus headers llevan las credenciales.
OAuth 2.0 · client credentials es para una API detrás de un servidor de autorización. Completá:
- Token URL:
https, dirección pública. - Client ID y Client secret. El secret se guarda cifrado y no se vuelve a mostrar.
- Scope y Audience, ambos opcionales.
- Send the credentials como header Basic (por defecto) o en el body del formulario.
Espejo pide un token con grant_type=client_credentials, lo conserva hasta que vence y
lo envía como Authorization: Bearer <token>. Si tu API responde 401, pide un token
nuevo una vez y reintenta. El token endpoint tiene que responder JSON con un
access_token; expires_in va en segundos y por defecto es 3600.
Qué tiene que responder tu API
Sección titulada «Qué tiene que responder tu API»- Cualquier
2xxcuenta como entregado. - No se siguen redirecciones: un
3xxcuenta como falla. - Espejo espera hasta 10 segundos.
- Un fallo que puede pasar se reintenta solo: sin respuesta dentro del timeout, un error
de red,
5xx,408,425y429. Cualquier otra respuesta (4xx, una redirección) o un problema de configuración no se reintenta, porque se repetiría. - Hasta 6 intentos en total, con una espera de 30 segundos, 2 minutos, 10 minutos, 1 hora y 6 horas entre ellos (unas 7 horas del primero al último). El reintento usa la integración como está guardada en ese momento, así que corregir la URL o un header alcanza.
- Todos los intentos de una misma entrega llevan el header
x-espejo-deliverycon el mismo id. Las entregas son al menos una vez: si tu API aceptó una pero Espejo no recibió la respuesta, llega de nuevo. Usá ese id para ignorar la repetida.
Last delivery de la integración muestra el status HTTP y cuándo pasó. Si falló, muestra además los primeros 300 caracteres de la respuesta de tu API, o el motivo por el que Espejo no la envió (por ejemplo, el token endpoint rechazando las credenciales, o una URL que ya no resuelve a una dirección pública).
Ver y reintentar entregas
Sección titulada «Ver y reintentar entregas»En Project settings, Integrations, Reports, el botón Deliveries abre la lista de las últimas entregas de los canales y webhooks del proyecto. Cada una muestra su estado (Delivered, Retrying o Failed), el intento en el que va, el status HTTP y el motivo del último fallo. Una entrega fallida, o una que espera su próximo intento, tiene un botón Retry que la envía en el momento; Retry all failed lo hace con todas las fallidas. Un reintento manual es un solo intento: si vuelve a fallar, la entrega queda en Failed.
Las entregas se guardan 30 días, y una fallida se puede reintentar durante ese tiempo. Send test es un solo intento y no aparece en la lista.
Mandar una recomendación desde Insights
Sección titulada «Mandar una recomendación desde Insights»En una tarea de Insights, cada integración API personalizada suma un botón
Send to seguido del nombre de la integración. Publica con la misma plantilla, con title y message puestos con
la tarea, type en improvement y las variables del reporte vacías.
Límites
Sección titulada «Límites»- Un proyecto puede tener hasta 10 integraciones en total (Slack, webhooks y APIs personalizadas juntos).
- Hasta 10 headers por API personalizada.