Preview Share Link | SpeechifyAI API

{
  "agent_name": "Cliff Weitzman",
  "widget_config": {
    "version": 1,
    "style": "pill",
    "theme": "dark",
    "avatar": {
      "type": "orb",
      "image_url": "https://cdn.speechify.ai/avatars/cliff-weitzman.png",
      "orb_color_1": "#4A90E2",
      "orb_color_2": "#50E3C2"
    },
    "text": {
      "start_call": "Start Conversation",
      "end_call": "End Conversation",
      "listening": "Listening...",
      "thinking": "Thinking...",
      "speaking": "Speaking..."
    },
    "terms": {
      "enabled": true,
      "content": "By continuing, you agree to Acme Inc's [Terms of Service](https://acme.inc/terms)."
    },
    "transcript": {
      "enabled": true
    }
  },
  "terms_enabled": true,
  "max_call_duration_seconds": 1800,
  "seconds_remaining": 1200,
  "terms_content": "Please review and accept the terms before starting your call."
}

Resolve a share link for display, before any call is started.

Unauthenticated: the link token is the credential. The response is deliberately cosmetic-only — the agent’s display name, the embed’s visual configuration, and the link’s remaining budget. It never returns the agent id, the workspace id, the prompt, the model, or any tool or knowledge-base name.

This endpoint performs no write and consumes no budget. Link unfurlers (chat clients, mail providers, security scanners) will fetch a pasted URL, so a preview must never be able to spend a link’s remaining call time.

Unknown, revoked and expired links all answer 404 share_link_not_found. The states are indistinguishable on purpose: the token is a bearer credential that spends money, so telling a caller which of their guesses named a real link would hand them an enumeration oracle.

Resolve a share link for display, before any call is started. Unauthenticated: the link token is the credential. The response is deliberately cosmetic-only — the agent's display name, the embed's visual configuration, and the link's remaining budget. It never returns the agent id, the workspace id, the prompt, the model, or any tool or knowledge-base name. This endpoint performs no write and consumes no budget. Link unfurlers (chat clients, mail providers, security scanners) will fetch a pasted URL, so a preview must never be able to spend a link's remaining call time. Unknown, revoked and expired links all answer `404 share_link_not_found`. The states are indistinguishable on purpose: the token is a bearer credential that spends money, so telling a caller which of their guesses named a real link would hand them an enumeration oracle.

Query parameters

tokenstringRequired

The share link's opaque bearer token.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The link's public, cosmetic projection.

agent_namestring

The agent's display name. Present because a visitor needs to know who they are about to talk to, and it is not part of the embed's visual configuration.

widget_configobject

The embed’s resolved visual configuration — avatar, colours, theme, button copy — so the page renders exactly like the real embed without ever naming the agent.

terms_enabledboolean

Whether the owner configured a pre-call consent gate. Surfaced here so the PAGE can render it: the embed’s own gate reads the agent’s configuration, which a share-link page deliberately never loads.

max_call_duration_secondsinteger

seconds_remaininginteger

Call time left on the link, so the page can say "nearly used up" rather than failing at the click.

terms_contentstringOptional

The consent text to display, as markdown.

Errors

404

Not Found Error

429

Too Many Requests Error

Resolve a share link for display, before any call is started.

$	curl -G https://api.speechify.ai/v1/agents/share-links/preview \
>	-H "Content-Type: application/json" \
>	-d token=token

Headers

Query parameters

Response headers

Response

Errors