Agents API

Create and change agents, start a call and read conversations from code.

The same API key as the speech API (x-api-key), and the same error shape. Everything here works on the workspace the key belongs to. Field names are the ones the dashboard uses (systemPrompt, firstMessage).

Request	What it does
`GET /v1/agents`	Your agents.
`POST /v1/agents`	Make an agent. It starts as a draft.
`GET /v1/agents/{id}`	One agent.
`PATCH /v1/agents/{id}`	Change some of its settings. Each change is saved as a version.
`GET /v1/conversations`	Calls and chats, newest first, 50 at a time. Filter with `agent_id`, `channel`, `caller`; page with `before` (the last one's `lastAt`).
`GET /v1/conversations/{id}`	One conversation with its transcript and the webhooks it called.
`POST /v1/calls`	Ring one person from one of your numbers; that number's agent talks to them.
`GET /v1/calls/{id}`	Where that call stands.

Make an agent

POST

/v1/agents

Field	Type	Description
`name`required	string	Shown in the dashboard and the conversation log.
`systemPrompt`	string	Who the agent is, what it helps with and what it must never do.
`firstMessage`	string	What it says when a conversation starts.
`languages`	string[]	The languages it speaks, main one first, e.g. `["en-IN", "hi-IN"]`.
`voiceId`	string	A voice from Models and voices, e.g. `voice:shubh`.
`behaviour`	object	Tone, reply length, interruptions, silences and the other settings on the Behaviour tab.
`status`	string	`draft` (default), `active` or `paused`.

curl -X POST https://lipivo.com/v1/agents \
  -H "x-api-key: $LIPIVO_API_KEY" -H "content-type: application/json" \
  -d '{"name": "Priya", "languages": ["en-IN"],
       "systemPrompt": "You are Priya, the customer support assistant for ShopX...",
       "firstMessage": "Hello, this is Priya from ShopX. How can I help you today?"}'

The answer is {"agent": {...}} with its id. Webhooks, knowledge and phone numbers are added in the dashboard.

Start a call

POST

/v1/calls

Field	Type	Description
`connectionId`required	string	One of your phone numbers (its id, from the Phone numbers page). Its agent takes the call.
`to`required	string	Who to ring. A 10-digit number is taken as Indian.
`name`	string	The person's name; `{{name}}` in the agent's first message becomes it.
`details`	object	Other facts the agent is given about the person, as text values.
`consent`required	true	You confirm the person agreed to be called.

curl -X POST https://lipivo.com/v1/calls \
  -H "x-api-key: $LIPIVO_API_KEY" -H "content-type: application/json" \
  -d '{"connectionId": "…", "to": "+919800000001", "name": "Ravi",
       "details": {"order": "A17", "amount": "₹1,250"}, "consent": true}'

A call follows the same rules as a call list in the dashboard: it is placed between 9:00 and 21:00 India time, never to a number on your do-not-call list, and only while you have credits and a free line. Poll GET /v1/calls/{id} for its status, or read the conversation once it has happened.

← Agent webhooks: data types and saved values Verify (one-time codes) →