Il pacchetto Starter è gratuito: 0 € al mese, con 30 minuti per provarlo su chiamate reali.Il pacchetto Starter è gratuito. Inizia gratis

Voiceland AI

Riferimento API / Web widget

Web widget

Gli endpoint del gruppo Web widget dell'API Voiceland AI, con parametri, schemi ed esempi curl.

Ultimo aggiornamento:

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
name path string Sì Agent name.

Risposte

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

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json Schema: WidgetShareRequest

Campo Tipo Obbligatorio Descrizione
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.

Risposte

Codice Descrizione
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.

Esempio di richiesta

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
}'

Una risposta riuscita restituisce un WidgetShareView.

Esempio di risposta

{
  "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.

Parametri

Nome Posizione Tipo Obbligatorio Descrizione
name path string Sì Agent name.
token path string Sì The link's token (the last path segment of its url).

Risposte

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

Esempio di richiesta

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

Schemi#

Error#

Error envelope returned for non-2xx responses.

Campo Tipo Obbligatorio Descrizione
error object Sì

WidgetShareRequest#

Options for a public test link. All optional.

Campo Tipo Obbligatorio Descrizione
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.

Campo Tipo Obbligatorio Descrizione
agent string Sì
connection_id string The store the link names, if any.
created_at string (date-time) Sì
expires_at string (date-time) Sì When the link stops working. Absent for a link with no expiry.
id string Sì 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 Sì
mode string Sì both, chat or voice: the channel the link offers.
revoked boolean Sì
revoked_at string (date-time)
sessions_used integer Sì Sessions minted so far; taken atomically at mint time.
status string Sì 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.

La console

Queste pagine sono di sola lettura. La chiamata di prova, le chiavi API e il riferimento API aggiornato si trovano nella console, dove il suo account è connesso.

Apri la console