Das Paket Starter ist kostenlos: €0 im Monat, mit 30 Minuten zum Testen an echten Anrufen.Das Paket Starter ist kostenlos. Kostenlos starten

Voiceland AI

API-Referenz / Web widget

Web widget

Die Endpoints der Gruppe Web widget der Voiceland AI API, mit Parametern, Schemata und Beispielen mit curl.

Zuletzt aktualisiert:

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

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.

Parameter

Name Ort Typ Erforderlich Beschreibung
name path string Ja Agent name.

Antworten

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

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json Schema: WidgetShareRequest

Feld Typ Erforderlich Beschreibung
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.

Antworten

Code Beschreibung
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.

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein WidgetShareView.

Beispielantwort

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

Parameter

Name Ort Typ Erforderlich Beschreibung
name path string Ja Agent name.
token path string Ja The link's token (the last path segment of its url).

Antworten

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

Beispielanfrage

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

Schemata#

Error#

Error envelope returned for non-2xx responses.

Feld Typ Erforderlich Beschreibung
error object Ja

WidgetShareRequest#

Options for a public test link. All optional.

Feld Typ Erforderlich Beschreibung
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.

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

Die Konsole

Diese Seiten sind schreibgeschützt. Der Testanruf, die API-Schlüssel und die aktuelle API-Referenz finden Sie in der Konsole, in der Ihr Konto angemeldet ist.

Konsole öffnen