API reference

Start a browser call

POST /v1/web-calls

Start a voice conversation with an agent in your own web page. Call this from your server, with the agent's values and your own data, and give the page the answer's url and token: it joins with @aigently/web. The token joins this one call and lasts 15 minutes. Needs calls:write and a live key. An Idempotency-Key makes a retry return the same call.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	Your own id for this call, up to 120 characters.

Body

Sent as JSON. A field this operation does not take is refused, so a typo fails loudly.

Field	Type	Required	Description
`agent_id`	string (uuid)	Yes	The agent to talk to. Browser voice must be on.
`agent_version`	integer or null	No	Answer with this published version of the agent rather than what is live now — its number from `GET /v1/agents/{id}/versions`. Its values and languages are that version's, and every turn of the conversation keeps it.
`external_id`	string or null	No
`language`	string or null	No	One of the agent's language versions, like `ar`.
`metadata`	object	No	Your own data, returned on every read and event. The agent never sees it.
`participant_name`	string or null	No	What the call names the person in the page. `Caller` unless you say.
`variables`	object	No	Values for the agent's `{{placeholders}}`. See its `variables_schema`.

Answer

201 with WebCall.

Errors

Every error is a problem document with a stable code.

Status	When
`401`	The key is missing, mistyped, unknown, revoked or expired.
`402`	The organization's credit is used up.
`403`	A test key: a browser call is a real conversation.
`404`	This key reaches no such agent.
`409`	The agent does not take browser calls or is not published, or its project is frozen.
`422`	A field or a variable does not fit — or the `Idempotency-Key` was used for a different request.
`429`	Too many calls going, or today's limit reached.
`500`	Something went wrong on our side. Quote the `request_id` to support.
`501`	This deployment does not run voice.
`502`	The voice service could not be reached. Try again shortly.

Examples

Start a browser call for your page

#!/bin/sh
# Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/web-calls" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  -H "Idempotency-Key: visit-20931" \
  --json '{
  "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f",
  "variables": {
    "first_name": "Sara"
  },
  "metadata": {
    "session": "S-20931"
  }
}'

Try it

Sends this request to the API from your browser, with a test key. Nothing it does rings a phone.