Developers / Agents
Mint a ticket for a private website widget
https://api.echonova.ai/v1/widgets/{publicId}/ticketsCall this from your server for a signed-in visitor. It returns a single-use ticket that you pass to the visitor browser, which starts one widget session with it. The widget must be private and turned on. Minting is free.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Path parameters
The widget id from the widget settings, starting with wdg_.
Request body
application/json
The signed-in visitor this ticket is for.
Restricts the ticket to one channel. Leave it out to allow both.
Seconds the ticket stays valid, from 60 to 900. It works once.
Response
200 application/json Every response uses this envelope.
The result.
The single-use ticket. Hand it to the visitor browser; it starts one session.
When the ticket stops working, as an ISO 8601 date-time.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. ttlSeconds is outside 60 to 900 or not a whole number; the message names the bound.
Fix. Send a whole number of seconds from 60 to 900, or leave the field out for 300.
When. channel is any other value.
Fix. Send voice or chat, or leave the field out.
When. user.id is over 128 characters.
Fix. Send a user.id of 128 characters or fewer.
When. user.id is an empty string.
Fix. Send a non-empty user.id, or leave the field out.
When. user.id holds a control character such as a newline or tab.
Fix. Remove control characters from user.id.
When. user.name is over 80 characters.
Fix. Send a user.name of 80 characters or fewer.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key has Widget tickets on No access.
Fix. Edit the key and set Widget tickets to Access, or use another key.
When. No widget has this publicId, or the widget belongs to another workspace.
Fix. Copy the publicId from the widget settings of an agent in this workspace.
When. The widget is in public mode, which needs no ticket.
Fix. Switch the widget to private mode in its settings.
When. The widget is turned off, so a ticket could never start a session.
Fix. Turn the widget on in its settings.
When. The JSON body is over 100 KB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send a smaller body; long text belongs in several calls.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
When. The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl -X POST "https://api.echonova.ai/v1/widgets/wdg_a1B2c3D4e5F6g7H8i9J0/tickets" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"ticket": "wtk_IlrI02c2RnE7iqidinRQanxpcTovunoAK7Bu5R6Zc5w",
"expiresAt": "2026-10-19T09:30:00.000Z"
},
"success": true,
"statusCode": 200,
"errorMessage": null
}