Le forfait Starter est gratuit : 0 € par mois, avec 30 minutes pour l'essayer sur de vrais appels.Le forfait Starter est gratuit. Commencer gratuitement

Voiceland AI

Référence de l'API / Web widget

Web widget

Les endpoints du groupe Web widget de l'API Voiceland AI, avec les paramètres, les schémas et des exemples curl.

Dernière mise à jour:

Les descriptions des endpoints et des champs restent en anglais, telles que l'API les publie. C'est un choix délibéré : vous lisez ici ce que vous verrez aussi dans les réponses.

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.

Paramètres

Nom Emplacement Type Requis Description
name path string Oui Agent name.

Réponses

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

Exemple de requête

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

Exemple de réponse

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

Corps de la requête

application/json Schéma : WidgetShareRequest

Champ Type Requis 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.

Réponses

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.

Exemple de requête

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

Une réponse réussie renvoie un WidgetShareView.

Exemple de réponse

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

Paramètres

Nom Emplacement Type Requis Description
name path string Oui Agent name.
token path string Oui The link's token (the last path segment of its url).

Réponses

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

Exemple de requête

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

Schémas#

Error#

Error envelope returned for non-2xx responses.

Champ Type Requis Description
error object Oui

WidgetShareRequest#

Options for a public test link. All optional.

Champ Type Requis 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.

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

Ces pages sont en lecture seule. L'appel de test, les clés API et la référence de l'API à jour se trouvent dans la console, où votre compte est connecté.

Ouvrir la console