The Starter package is free: €0 a month, with 30 minutes to try it on real calls.The Starter package is free. Get started free

Voiceland AI

API reference / Web widget

Web widget

The Web widget endpoints of the Voiceland AI API, with parameters, schemas and curl examples.

Last updated:

List test links. Public "try this agent" links for one agent: pages we host at /try/{token} that embed the agent's web widget, so you can hand a reviewer a URL instead of an embed snippet. Each carries its url, how many sessions it has spent, and a status of active, expired, exhausted or revoked.

Parameters

Name In Type Required Description
name path string Yes Agent name.

Responses

Code Description
200 Success.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/share-links" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "agent": "front-desk",
      "created_at": "2026-09-14T12:00:00Z",
      "expires_at": "2026-09-17T12:00:00Z",
      "label": "for the reviewer",
      "last_used_at": "2026-09-14T15:20:00Z",
      "max_sessions": 20,
      "revoked": false,
      "sessions_used": 3,
      "status": "active",
      "token": "k3JqTz9wY1n8Qb2vXm5LpR0e",
      "url": "https://api.voiceland.ai/try/k3JqTz9wY1n8Qb2vXm5LpR0e"
    }
  ]
}

POST /v1/agents/{name}/share-links#

Create a test link. Mints an unguessable link that hosts this agent's web widget on our domain. Anyone with the URL can talk to the agent, so the link expires (expires_in_hours, default 168, at most 720; or no_expiry: true for a link that only revocation or the cap ends), is capped (max_sessions, default 50, at most 1000; or unlimited_sessions: true for no cap, max_sessions 0 on the link) and can be revoked. Every session it mints spends your minutes under your own rate limit and concurrency cap, exactly like a session from your site; the token only widens who can reach the agent. The agent's web widget must be enabled.

Request body

application/json Schema: WidgetShareRequest

Field Type Required Description
connection_id string Optionally one of the agent's stores (400 connection_not_on_agent otherwise). The hosted page then says "Test the assistant of <store name>". Checked again at every use: if the agent no longer has the store, the link keeps working without its name.
expires_in_hours integer Lifetime in hours. Default 168 (7 days), at most 720 (30 days).
label string A note shown on the hosted page and in your list (up to 80 characters).
max_sessions integer How many sessions the link may mint in its lifetime. Default 50, at most 1000. Ignored with unlimited_sessions.
mode string The channel the link offers: both (default), chat or voice. It must be a channel the agent's widget has (400 mode_channel_disabled otherwise). A session of another channel is refused with 403 share_mode_not_allowed, and the hosted page shows only the allowed one.
no_expiry boolean true for a link with no expiry: only revocation or the session cap ends it (only revocation, with unlimited_sessions as well). Overrides expires_in_hours. Operator only: a request from the console answers 403 operator_only.
unlimited_sessions boolean No session cap: the link mints sessions until it expires or is revoked. With no_expiry as well, only revocation ends it.

Responses

Code Description
201 Created. Send url to the person who should try the agent.
401 Missing or invalid API key.
409 widget_disabled, enable the web widget on the agent first; a test link is a hosted copy of it.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/share-links" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in_hours": 72,
  "label": "for the reviewer",
  "max_sessions": 20
}'

A successful response returns a WidgetShareView.

Example response

{
  "agent": "front-desk",
  "created_at": "2026-09-14T12:00:00Z",
  "expires_at": "2026-09-17T12:00:00Z",
  "label": "for the reviewer",
  "last_used_at": "2026-09-14T15:20:00Z",
  "max_sessions": 20,
  "revoked": false,
  "sessions_used": 3,
  "status": "active",
  "token": "k3JqTz9wY1n8Qb2vXm5LpR0e",
  "url": "https://api.voiceland.ai/try/k3JqTz9wY1n8Qb2vXm5LpR0e"
}

Revoke a test link. Withdraws the link at once: the hosted page answers 404 and no further session can be minted with it. Sessions already running are unaffected.

Parameters

Name In Type Required Description
name path string Yes Agent name.
token path string Yes The link's token (the last path segment of its url).

Responses

Code Description
204 Revoked.
401 Missing or invalid API key.
4XX Request error (validation, not-found, etc.).
5XX Server or upstream error.

Example request

curl -X DELETE "https://api.voiceland.ai/v1/agents/{name}/share-links/{token}" \
  -H "Authorization: Bearer VL_API_KEY"

Schemas#

Error#

Error envelope returned for non-2xx responses.

Field Type Required Description
error object Yes

WidgetShareRequest#

Options for a public test link. All optional.

Field Type Required Description
connection_id string Optionally one of the agent's stores (400 connection_not_on_agent otherwise). The hosted page then says "Test the assistant of <store name>". Checked again at every use: if the agent no longer has the store, the link keeps working without its name.
expires_in_hours integer Lifetime in hours. Default 168 (7 days), at most 720 (30 days).
label string A note shown on the hosted page and in your list (up to 80 characters).
max_sessions integer How many sessions the link may mint in its lifetime. Default 50, at most 1000. Ignored with unlimited_sessions.
mode string The channel the link offers: both (default), chat or voice. It must be a channel the agent's widget has (400 mode_channel_disabled otherwise). A session of another channel is refused with 403 share_mode_not_allowed, and the hosted page shows only the allowed one.
no_expiry boolean true for a link with no expiry: only revocation or the session cap ends it (only revocation, with unlimited_sessions as well). Overrides expires_in_hours. Operator only: a request from the console answers 403 operator_only.
unlimited_sessions boolean No session cap: the link mints sessions until it expires or is revoked. With no_expiry as well, only revocation ends it.

WidgetShareView#

A test link as reads return it: the row plus the URL to hand out and its status.

Field Type Required Description
agent string Yes
connection_id string The store the link names, if any.
created_at string (date-time) Yes
expires_at string (date-time) Yes When the link stops working. Absent for a link with no expiry.
id string Yes Names the link in the revoke call: the hash of its token, which is not a secret. The token itself is shown once, in the create answer.
label string
last_used_at string (date-time) When a session was last minted with the link.
max_sessions integer Yes
mode string Yes both, chat or voice: the channel the link offers.
revoked boolean Yes
revoked_at string (date-time)
sessions_used integer Yes Sessions minted so far; taken atomically at mint time.
status string Yes active, expired, exhausted (all sessions used) or revoked.
store_name string The name of the store the link names, while the agent still answers for it.
token string The token, in the create answer only; it is not stored and cannot be read again. In a list this repeats id (kept for older clients; use id).
token_hint string The last four characters of the token, to tell links apart in a list.
unlimited_sessions boolean true when the link has no session cap (its max_sessions is 0): only revocation or its expiry ends it.
url string The page to share. Anyone with it can talk to the agent until the link expires, is spent or is revoked. In the create answer only.

The console

These pages are read only. The test call, the API keys and the live API reference are in the console, where your account is signed in.

Open the console