HTTP API

viora cloud and the self-hosted server share the same API, so the widget and your own integrations work with either.

Base URL: https://viora-cloud.depriver-tech.workers.dev for viora cloud, or your own server.

Public endpoints

Called by the widget. If your profile sets allowed_origins, only those websites can use them.

GET /v1/sites/{site}/config

The assistant's public settings: name, business, greeting, colour, position, suggestions, WhatsApp link, and voice (whether the microphone is available).

POST /v1/sites/{site}/ask

{ "question": "Do you offer school transport?", "history": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}] }

Responds with a stream of server-sent events. Text arrives as token events, then one done event:

data: {"type": "token", "text": "Yes, school buses cover "}
data: {"type": "token", "text": "routes within Arusha city."}
data: {"type": "done", "answered": true, "language": "en", "sources": [], "handoff": "https://wa.me/255700000000?text=..."}

For voice conversations, add "mode": "voice" for short answers that sound natural read aloud, and "language": "sw" or "en" from the transcription.

answered: false means viora didn't find the answer in your information; the widget then offers the lead form and WhatsApp. Limits: 30 questions per visitor per hour, plus your plan's daily total (status 429 when reached).

POST /v1/sites/{site}/transcribe

Speech to text for one spoken question. Send the recording as the request body, with its type as Content-Type (audio/webm, audio/mp4, audio/ogg, audio/wav or audio/mpeg), up to about a minute.

curl https://viora-cloud.depriver-tech.workers.dev/v1/sites/your-site/transcribe \
  -H "Content-Type: audio/webm" --data-binary @question.webm

{"text": "Mnafungua saa ngapi Jumapili?", "language": "sw"}

An empty text means nothing was said. Limit: 40 recordings per visitor per hour. Returns 403 when voice is turned off for the assistant.

POST /v1/sites/{site}/speak

{ "text": "Karibu! We are open until 9 pm.", "voice": "luna" }

Text to speech in a natural English voice. viora cloud returns MP3 (audio/mpeg); a self-hosted server returns WAV. Voices include luna, asteria, athena, orion and apollo. On viora cloud each call counts toward the plan's monthly natural-voice answers; when none are left it returns 402 with code: "plan".

GET /v1/sites/{site}/live

A WebSocket for real-time voice conversations: microphone audio in, answers and speech out. See Live voice for the protocol.

POST /v1/sites/{site}/leads

{ "name": "Asha", "contact": "+255 711 111 111", "message": "A Form One place for my daughter next year" }

Owner endpoints

Send your site key: Authorization: Bearer vk_... (viora cloud) or your VIORA_ADMIN_KEY (self-hosted).

Example: ask from your own code

curl -N https://viora-cloud.depriver-tech.workers.dev/v1/sites/your-site/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Mnafungua saa ngapi?"}'