- Guides
- Send reports to your ticket system
Send reports to your ticket system
Open a ticket in your own system for each report: your URL, secret headers, a JSON body template, and optional OAuth 2.0 client credentials.
A Custom API integration sends each report Espejo gets (the ones your visitors record and send from the widget, and the automatic ones) to an HTTP endpoint you choose, so it lands as a ticket in your own system. You define the URL, the headers, the body and the authentication; Espejo calls it from its server, never from the visitor’s browser.
It is one way: Espejo creates the ticket and records whether your API accepted it. It does not read tickets back.
Add it
Section titled “Add it”In the console, open Project settings → Integrations → Reports and choose
+ Custom API. A project can have several, each with its own name (for example
Nexus) and its own choice of which reports it receives.
| Field | What it is |
|---|---|
| Name | How the integration is called in the console. Up to 60 characters. |
| Request URL and method | POST (default), PUT or PATCH. https only, and the host must resolve to a public address. |
| Headers | Up to 10. A name and a value each. |
| Body | A JSON template with variables. |
| Authentication | None, or OAuth 2.0 client credentials. |
Then open the integration and pick Which reports go here:
- Only reports with errors: reports with an HTTP 4xx or 5xx or a console error. This is the default.
- Every report.
- None: keep it configured but quiet.
Use Send test to post a sample report with your saved settings before a real one arrives. It goes out even when the integration is set to None.
Headers
Section titled “Headers”Each header has a name and a value. The value is a secret: it is stored encrypted and the console never shows it again. To change one, type a new value; to keep it, leave the field empty.
Use them for whatever your API asks for: an API key (X-Api-Key), a fixed
Authorization: Bearer ..., a tenant id.
Espejo sets Content-Type: application/json and Accept: application/json; a
header of yours with the same name replaces them. These cannot be set: Host,
Content-Length, Connection, Keep-Alive, Transfer-Encoding, TE, Trailer,
Upgrade, Expect, Cookie, Set-Cookie, and any name starting with Proxy- or
Sec-. A value must be a single line of at most 2048 characters. With OAuth,
Espejo sets Authorization itself, so do not add your own.
Body template
Section titled “Body template”The body is JSON with {{variable}} placeholders. This is the default:
{ "title": "{{title}}", "description": "{{summary}}", "type": "{{type}}", "external_id": "{{session_id}}", "reporter": "{{user_email}}", "replay_url": "{{replay_url}}"}{{name}}goes inside a JSON string. The value is escaped for you (quotes, line breaks, backslashes), so text a visitor wrote cannot break the JSON. A missing value becomes an empty string.{{json:name}}inserts the value as JSON as it is:42,true,null,"text". Use it for numbers and booleans, for example"errors": {{json:errors_5xx}}.
Espejo checks the template when you save it: every variable must exist, and the
result, filled with sample values, must be a valid JSON object or array. Otherwise
it answers 400 with the reason. The template can have up to 20,000 characters.
| Variable | Value |
|---|---|
title | [Espejo] and the report’s title, if it came with one; otherwise [Espejo] and the first 120 characters of the description; otherwise [Espejo] Reporte en <site>. See How the title is built. |
summary | A multi-line text: replay link, project, site, user, duration, error counts and the first error. Its labels are in Spanish. |
message | The description, whole. Empty if there is none. |
type | bug if the report has an HTTP 4xx or 5xx or a console error, otherwise report. |
has_errors | true or false. |
replay_url | Link to the recording in the console. It does not expire, but whoever opens it needs an Espejo account on the project. |
share_url | Public link to the recording, signed and valid for 72 hours. Anyone with the link can watch it, no account needed. Only on the Team plan; empty on Free. |
share_expires_at | When share_url stops working, ISO 8601. Empty when there is no share_url. |
session_id | The recording id. The same report always carries the same one, so use it to avoid duplicates. |
project | The project name. |
page_host | The host of the page where it was reported. |
user_ref | The user reference your site passed to the SDK. |
user_email | user_ref, only if it looks like an email address. |
duration_ms | Length of the recording, in milliseconds. |
errors_5xx, errors_4xx, errors_console | The error counts. |
first_error | An excerpt of the first console error. |
sent_at | When Espejo sent it, ISO 8601. |
summary and message carry at most 20,000 characters, and user_ref at most 200.
How the title is built
Section titled “How the title is built”title is always [Espejo] followed by one of these, in this order:
- The title the page sent with the report:
espejo.report({ title, description }). One line, at most 120 characters (a longer one is cut). - If there is no title, the first 120 characters of the description. The cut is blind: it does not look for a period or a line break, so a long text ends in the middle of a sentence.
- If there is neither,
Reporte en <site>, or the project name when the site is unknown.
The floating button has a single text field, so its reports take the second path.
To get a real title, send the report from your own button
with an object. The whole description always arrives in message, so put
{{message}} in the field where your system expects the long text.
If your system wants the description and the replay link together, summary already
has them. message has only what the person wrote.
The public link
Section titled “The public link”share_url is the same link as the console’s Copy link to share, signed at the
moment Espejo sends the report. It stops working after 72 hours (share_expires_at),
so a ticket that stays open longer will have a dead link. Keep replay_url next to
it for your own team, which does not expire.
The link also stops working if the account leaves the Team plan or is deactivated, even before it expires. On the Free plan both variables arrive empty.
Authentication
Section titled “Authentication”None is enough when your headers carry the credentials.
OAuth 2.0 · client credentials is for an API behind an authorization server. Fill in:
- Token URL:
https, public address. - Client ID and Client secret. The secret is stored encrypted and never shown again.
- Scope and Audience, both optional.
- Send the credentials as a Basic header (the default) or in the form body.
Espejo requests a token with grant_type=client_credentials, keeps it until it
expires, and sends it as Authorization: Bearer <token>. If your API answers
401, it gets a new token once and retries the request. The token endpoint must
answer JSON with an access_token; expires_in is in seconds and defaults to 3600.
What your API has to answer
Section titled “What your API has to answer”- Any
2xxcounts as delivered. - Redirects are not followed: a
3xxcounts as a failure. - Espejo waits up to 10 seconds.
- A failure that can pass is retried on its own: no answer within the timeout, a
network error,
5xx,408,425and429. Any other answer (4xx, a redirect) or a configuration problem is not retried, because it would repeat. - Up to 6 attempts in total, waiting 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours between them (about 7 hours from the first to the last). A retry uses the integration as it is saved at that moment, so fixing the URL or a header is enough.
- Every attempt of the same delivery carries the header
x-espejo-deliverywith the same id. Deliveries are at least once: if your API accepted one but Espejo did not get the answer, it arrives again. Use that id to ignore a repeat.
The integration’s Last delivery shows the HTTP status and when it happened. On a failure it also shows the first 300 characters of your API’s answer, or the reason Espejo did not send it (for example, the token endpoint rejecting the credentials, or a URL that no longer resolves to a public address).
See and retry deliveries
Section titled “See and retry deliveries”In Project settings, Integrations, Reports, the Deliveries button opens the list of the latest deliveries of the project’s channels and webhooks. Each one shows its status (Delivered, Retrying or Failed), the attempt it is on, the HTTP status and the reason of the last failure. A failed delivery, or one waiting for its next attempt, has a Retry button that sends it right away; Retry all failed does it for every failed one. A manual retry is a single attempt: if it fails again the delivery stays Failed.
Deliveries are kept for 30 days, and a failed one can be retried during that time. Send test is one attempt and does not appear in the list.
Send a recommendation from Insights
Section titled “Send a recommendation from Insights”On a task in Insights, each Custom API integration adds a Send to followed by the integration name
button. It posts through the same template, with title and message set to the
task, type set to improvement, and the report variables empty.
Limits
Section titled “Limits”- A project can have up to 10 integrations in total (Slack, webhooks and Custom APIs together).
- Up to 10 headers per Custom API.