API reference · Embed

Start a call with a publishable key

POSThttps://goblins-call-api.onrender.com/v1/embed/calls

Starts a call from a web page or an app with an agent’s publishable key. The agent runs exactly as saved; nothing else can be sent. The embed script makes this request for you.

Needs no key.

Body

keystringRequired

The agent’s publishable key, pk_…. It may be sent as Authorization: Bearer instead.

Response

tokenstring

A join token for this room. It can be used to join for two minutes.

maxDurationSecondsinteger

When the call will be ended at the latest: the agent’s maxCallSeconds, or less when the balance or the day’s limit leaves less.

Errors

401INVALID_PUBLIC_KEY

No agent has that publishable key.

403EMBED_DISABLED

The agent’s call button is switched off.

403ORIGIN_NOT_ALLOWED

The page’s site is not in the agent’s allowedOrigins.

429RATE_LIMITED

This visitor has started too many calls in the last hour.

429EMBED_DAILY_LIMIT_REACHED

The agent’s dailySpendLimit has been reached for today.

429AGENT_BUSY

The workspace is on as many calls as it may run at once.

503AGENT_UNAVAILABLE

The workspace cannot take calls right now, for example because its balance has run out. The reason is not given to the visitor.

Every request can also answer 401, 429 and 500: see Errors.

Notes

  • A request from a browser is checked against allowedOrigins. One with no Origin header, as from a mobile app, is let through: the spend limits apply to every call regardless.
  • These calls appear in call logs with the source embed.
curl -X POST "https://goblins-call-api.onrender.com/v1/embed/calls" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "pk_3f9a1c2b7d4e5f603f9a1c2b7d4e5f603f9a1c2b"
}'
Response · 201 Created
{
  "callId": "8f1c2c1e-7b1a-4e0a-9c55-2f6f0d3b1a90",
  "roomName": "web_8f1c2c1e7b1a",
  "livekitUrl": "wss://…",
  "token": "eyJhbGciOiJIUzI1NiJ9…",
  "participantIdentity": "visitor_5d2e8a41",
  "agentName": "Front desk",
  "maxDurationSeconds": 300
}