Agents

An agent answers in Yoruba, Pidgin, Hausa, Igbo or Nigerian English. You set its instructions and tools in the dashboard or through the API, then send it messages.

Get a reply

Only live agents answer. Turn an agent live in the dashboard, or with PATCH /v1/agents/{agent_id} and {"status": "live"}.

curl https://api.vocalistic.ai/v1/agents/YOUR_AGENT_ID/responses \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a-unique-value' \
  -d '{"input": "Wetin be una opening time?"}'

The reply comes straight back:

{
  "conversation_id": "conv_abc",
  "status": "open",
  "reply": "We dey open by nine for morning.",
  "tool_calls": [{"name": "knowledge_search", "input": {"query": "opening time"}, "output": {"results": []}}],
  "sources": ["opening-hours.md"],
  "usage": {"credits": 0.2, "quantity": 1, "unit": "reply"},
  "request_id": "req_abc"
}

Send conversation_id with the next message to continue the conversation. To hear the reply, pass reply to POST /v1/audio/speech, which is charged separately. Sending the same Idempotency-Key with an API key returns the same reply, with no second charge. Keys last a day, and belong to one API key and one agent. Client tokens can’t use them. tool_calls shows each tool’s input and output to API keys. Client tokens get tool names only, so a browser can’t read your documents or what your webhook returned.

Errors

Code	Status	Meaning
`not_found`	`404`	No such agent or conversation, or the conversation has expired.
`agent_not_live`	`409`	The agent is a draft.
`request_in_progress`	`409`	This `Idempotency-Key` is still being used.
`idempotency_conflict`	`422`	This `Idempotency-Key` was used with a different request.
`conversation_busy`	`409`	A reply is still running in this conversation.
`conversation_ended`	`409`	The agent ended this conversation. Start a new one.
`insufficient_credits`	`402`	Top up to continue.
`rate_limited`, `too_many_concurrent_requests`	`429`	Wait, then try again.
`model_unavailable`	`503`	Try again shortly. You aren’t charged.

Conversations

We keep a conversation for 1 hour after its last message, or for your organization’s retention period if that’s longer, and delete it within a day of that. A conversation older than this returns 404. Delete one sooner with DELETE /v1/conversations/{conversation_id}.

Knowledge

Upload TXT, Markdown, CSV, JSON or HTML files of up to 2 MB, or add short notes, up to 20 per agent. With Knowledge search on, the agent looks up answers there and sources names the documents it used. An agent can repeat anything in its documents to whoever it’s talking to, so don’t upload anything callers shouldn’t hear.

Tools

Tool	What it does
Knowledge search	Searches this agent’s documents.
Collect caller details	Saves the details you list on the conversation.
End conversation	Closes the conversation.
HTTP webhook	Calls your backend.
Transfer to human, Send SMS	Coming soon.

Webhooks

Your endpoint must be a public https URL. We wait 5 seconds in total, read at most 8 KB and don’t follow redirects. An agent can make at most 8 tool calls in a reply. A live agent’s webhook needs a signing secret. A POST carries this JSON, and a GET sends the same fields as query parameters:

{"tool": "check_order", "arguments": {"order": "7"}, "agent_id": "agt_abc", "conversation_id": "conv_abc"}

Create a signing secret in the dashboard, then check X-Vocalistic-Signature on each request. It’s sha256= followed by the hex HMAC-SHA256 of {X-Vocalistic-Timestamp}.{body}, keyed with your secret. For a GET, use the path and query in place of the body. Reject old timestamps. A failed reply can be retried after a webhook has already run. Use X-Vocalistic-Delivery, which is unique to each call, to spot repeats, and make actions safe to repeat where you can.

Testing

Send "test": true with an API key to run a draft. It’s charged like any reply, but webhooks aren’t called: the agent is told the action was simulated. A test conversation can’t continue as a real one. The dashboard’s test console does this for you.

Get started

API reference

Get a reply

Errors

Conversations

Knowledge

Tools

Webhooks

Testing

​Get a reply

​Errors

​Conversations

​Knowledge

​Tools

​Webhooks

​Testing

Get a reply

Errors

Conversations

Knowledge

Tools

Webhooks

Testing