Riya AI
Developers

Build on Riya AI

Three ways to connect Riya AI to your stack. Everything below is also configurable without code from Integrations in the app.

Base URL
https://riya-ai-beryl.vercel.app/api

All requests and responses are JSON (UTF-8). Phone numbers are Indian mobiles in E.164 (+91XXXXXXXXXX); 10-digit and 0-prefixed inputs are normalised. Timestamps are ISO 8601 in UTC; money is in paise.

Authentication

Create an API key under Integrations → API keys. Keys start with rk_, are shown once, and carry full access to one workspace. Send them as a Bearer token from your server; never from a browser or mobile app.

curl https://riya-ai-beryl.vercel.app/api/auth/me \
  -H "Authorization: Bearer rk_your_key_here"

# 200 → { "user": null, "role": "api", "workspace": { "id": "ws_…", "name": "…", "plan": "starter", … } }
# 401 → { "error": "Not signed in" }   (missing, revoked or malformed key)

Revoking a key takes effect immediately. The app itself uses a session cookie on the same endpoints, so anything you see the dashboard do, you can do with a key.

REST endpoints

Lists return newest first. Every object carries id, createdAt and updatedAt. Errors are { "error": "message" } with a 4xx status.

ResourceEndpointsPurpose
WhatsAppGET /api/conversations · GET/POST/PATCH /api/conversations/{id} · GET/PATCH /api/whatsappRead WhatsApp threads, reply as a human, hand a thread back to Riya, manage the connected number
LeadsPOST /api/leadsSpeed to lead: send a new enquiry from any form, CRM, ad platform or Zapier and the agent calls it back within a minute (or next morning)
CallsGET /api/calls · POST /api/calls · GET /api/calls/{id}List calls (filter by phone, campaignId, agentId), start an outbound call, read transcript and outcome
ContactsGET /api/contacts · POST /api/contactsList, create or upsert contacts with attributes and tags
CampaignsGET /api/campaigns · POST /api/campaigns · GET /api/campaigns/{id} · GET /api/campaigns/{id}/jobsCreate a calling campaign from a contact list and track per-contact progress
KnowledgeGET /api/knowledge · POST /api/knowledge · PUT/DELETE /api/knowledge/{id} · GET /api/knowledge/search?q= · POST /api/knowledge/importQ&A the agent answers from; preview what it would say
Do-not-callGET /api/dnc · POST /api/dnc · DELETE /api/dncNumbers the platform must never dial; the agent adds to it when a caller asks
Custom actionsGET/POST /api/tools · GET/PATCH/DELETE /api/tools/{id} · POST /api/tools/{id}/testManage the webhooks the agent can call mid-conversation
Outgoing webhooksGET/POST /api/webhooks · GET/PATCH/DELETE /api/webhooks/{id} · POST /api/webhooks/{id}/testSubscribe URLs to events
API keysGET/POST /api/apikeys · DELETE /api/apikeys/{id}Create and revoke keys

Calls

POST/api/calls

Start an outbound call now. Refused outside the workspace's calling window, for numbers on the do-not-call list, when a call to that number is already in progress, or after the weekly attempt limit for that purpose.

Request
{
  "phone": "+919876543210",
  "purpose": "FOLLOW_UP",            // free text label, e.g. CONFIRMATION, REMINDER, LEAD
  "agentId": "agt_…",               // optional; defaults to the primary live agent
  "context": "Quote ₹18,500 for iPhone 13 sent on WhatsApp yesterday"
}
Response
201 { "call": { "id": "call_…", "status": "QUEUED", "phone": "+919876543210", "purpose": "FOLLOW_UP", "agentId": "agt_…", … } }
400 { "error": "Outside calling hours" }

Status moves QUEUED → RINGING → IN_PROGRESS → COMPLETED | NO_ANSWER | BUSY | VOICEMAIL | FAILED | TRANSFERRED. Outcome is one of BOOKED, RESCHEDULED, CANCELLED, INFO_GIVEN, INTERESTED, NOT_INTERESTED, CALLBACK_REQUESTED, CONFIRMED, WRONG_NUMBER, DO_NOT_CALL, HANDED_OFF, UNREACHED, UNKNOWN.

GET/api/calls?phone=&campaignId=&agentId=&limit=

Recent calls, newest first.

Response
{ "calls": [ { "id": "call_…", "direction": "OUTBOUND", "status": "COMPLETED", "outcome": "BOOKED", "phone": "+919876543210",
  "customerName": "Priya", "startedAt": "…", "endedAt": "…", "durationSec": 96, "summary": "…", "transcript": "…",
  "structuredData": { "outcome": "BOOKED", "details": { "slot": "Thu 11:00" } }, "toolLog": [ { "name": "search_knowledge", "ok": true, "ms": 41 } ],
  "chargePaise": 1000, "recordingUrl": null, "campaignId": null, "contactId": "ct_…" } ] }

Contacts

POST/api/contacts

Create or update a contact by phone. Attributes merge; blanks never overwrite.

Request
{ "phone": "9876543210", "name": "Priya", "attributes": { "city": "Hisar", "device": "iPhone 13" }, "tags": ["lead"] }
Response
201 { "contact": { "id": "ct_…", "phone": "+919876543210", "name": "Priya", "attributes": { … }, "tags": ["lead"], "source": "api" } }
GET/api/contacts?q=&tag=&limit=

List contacts.

Response
{ "contacts": [ … ] }

Campaigns

Only for people who asked to hear from you, such as a recent enquiry or a booked appointment. Promotional and cold calls to lists are not allowed (terms, section 5), and the A2P declaration with our telephony provider is not complete yet.

POST/api/campaigns

Queue calls to a list of contacts. Calls are paced within the workspace's concurrency and calling window, with retries up to maxAttempts.

Request
{
  "name": "October pickup confirmations",
  "agentId": "agt_…",
  "purpose": "Confirm this week's pickup slot and the device condition",
  "contacts": [ { "phone": "+919876543210", "name": "Priya", "context": "Pickup Thu 11 AM, iPhone 13" } ],
  "scheduledFrom": "2026-10-08T04:30:00Z",   // optional
  "maxAttempts": 2                          // optional
}
Response
201 { "campaign": { "id": "camp_…", "status": "scheduled", "stats": { "queued": 1, "dialed": 0, "answered": 0, "booked": 0 } } }
GET/api/campaigns/{id}/jobs

Per-contact progress.

Response
{ "jobs": [ { "id": "q_…", "phone": "+91…", "status": "done", "attempts": 1, "callId": "call_…", "lastReason": null } ] }

Knowledge

POST/api/knowledge

Add a Q&A entry. Tags are matched too, so include Hinglish keywords.

Request
{ "category": "Payment", "q": "When do I get paid?", "a": "By UPI once the device is verified, usually at the door.", "tags": ["payment", "paisa", "kab"] }
Response
201 { "entry": { "id": "kb_…", "category": "Payment", "q": "…", "a": "…", "tags": [ … ] } }
GET/api/knowledge/search?q=paisa kab milega

What the agent would answer. Same ranking and synonyms the agent uses mid-call.

Response
{ "query": "paisa kab milega", "answer": "By UPI once the device is verified…", "matches": [ { "id": "kb_…", "q": "When do I get paid?", "score": 17 } ],
  "agentNote": "The agent paraphrases this answer in the caller's language, keeping the facts exact." }
POST/api/knowledge/import

Bulk import from "Q: … / A: …" blocks (optional Category:/Tags: lines) or CSV "question,answer,category,tags". Pass dryRun: true to preview.

Request
{ "text": "Q: Is pickup free?\nA: Yes, doorstep pickup is free.\nCategory: Pickup\nTags: free, muft", "dryRun": false }
Response
201 { "imported": 1, "skipped": 0, "format": "qa", "entries": [ … ] }

Do-not-call

POST/api/dnc

Add a number. Outbound calls and campaign jobs to it are refused from then on.

Request
{ "phone": "+919876543210", "reason": "Customer request on 7 Oct" }
Response
201 { "ok": true, "phone": "+919876543210" }

Speed to lead

Leads called back within five minutes convert several times better than leads called the next day. Point any lead source at this endpoint and the agent dials immediately inside your calling hours, or first thing in the next window. The contact is created or updated with the lead details, tagged lead and the source, and the call carries the enquiry as context so the agent opens with it.

curl -X POST https://riya-ai-beryl.vercel.app/api/leads \\
  -H "Authorization: Bearer rk_your_key" -H "Content-Type: application/json" \\
  -d '{"phone":"9876543210","name":"Asha Verma","source":"website","interest":"Diabetes package","message":"Please call after 4 pm"}'

// 201 { contact, call, job, when: "now" | "queued" }

Works with Google Forms (Apps Script), Meta Lead Ads via Zapier or Make, IndiaMART and JustDial lead pushes, WhatsApp forms, and your own website. Duplicate leads update the same contact. Numbers on the do-not-call list return 409. If you switch on a service area (Settings, Service area), send pincode (or city) with the lead: a lead outside your area is saved but not called, goes on your callback list with the reason, and returns when: "skipped". A lead with neither is called and the agent asks for the pincode first.

WhatsApp

Connect your own Meta WhatsApp Business number under Integrations → WhatsApp. Riya answers incoming messages from the same knowledge base and actions as calls. The platform receives Meta's webhook at /api/channels/whatsapp and routes by phone number id; you never handle the webhook yourself. Each customer conversation is a conversation with status open, handoff or closed and an autoReply flag. Posting a message to a conversation as a human pauses Riya on that thread; PATCH { autoReply: true, status: "open" } hands it back, and { nudge: true } asks her to reply now. The outgoing webhook event conversation.started fires when a new 24-hour window opens. Business-initiated messages (lead first touch, call summaries, notes outside the window) use the templates you name in settings.

Outgoing webhooks

Create a webhook under Integrations → Outgoing webhooks (or POST /api/webhooks). You get a signing secret once. We make one delivery attempt per event with an 8 second timeout and record the last status on the webhook; make your handler idempotent on data.call.id and return 2xx quickly.

EventWhendata
call.completedAn answered call ended and was processed (unanswered calls do not fire).{ call } — the full call object; transcript only if “Include transcript” is on
callback.requestedThe agent noted a callback for a team member.{ callback: { id, callId, phone, name, reason, callbackAt, status } }
campaign.finishedEvery job in a campaign reached a terminal state.{ campaign: { id, name, status, stats, finishedAt } }
POST https://your-url.example.com/riya
content-type: application/json
user-agent: RiyaAI-Webhooks/1.0
x-riya-event: call.completed
x-riya-webhook: wh_…
x-riya-signature: sha256=3f1a…   # HMAC-SHA256 of the raw request body, keyed with your webhook secret

{
  "event": "call.completed",
  "workspaceId": "ws_…",
  "timestamp": "2026-10-07T12:34:56.000Z",
  "data": { "call": { "id": "call_…", "status": "COMPLETED", "outcome": "BOOKED", "phone": "+91…", "summary": "…", "structuredData": { … }, "chargePaise": 1000 } }
}

Verify the signature (Node)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyRiya(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected); const b = Buffer.from(String(signatureHeader || ''));
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express: keep the raw body, verify, then parse
app.post('/riya', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyRiya(req.body, req.get('x-riya-signature'), process.env.RIYA_WEBHOOK_SECRET)) return res.sendStatus(401);
  const { event, data } = JSON.parse(req.body);
  if (event === 'call.completed') upsertInCrm(data.call);   // idempotent on data.call.id
  res.sendStatus(200);
});

Use the raw bytes, not a re-serialised object, when computing the HMAC. Send a sample delivery any time with “Send test” in the app or POST /api/webhooks/{id}/test; test payloads carry "test": true.

Custom actions

A custom action is a function the model can call during a conversation: it has a snake_case name, a description that tells the model when to use it, JSON-Schema parameters the model fills from what the caller says, and your URL. Riya validates the arguments, POSTs them to you, and reads your result back to the caller in their language. Built-in actions (contact lookup, knowledge search, save details, request callback, transfer, do-not-call) need no setup.

Riya sends
POST <your url>            # or GET/PUT/PATCH as configured
content-type: application/json
x-riya-workspace: ws_…
x-riya-call: call_…
<your configured headers>

{
  "tool": "check_order_status",
  "arguments": { "order_id": "ORD-5521" },
  "call": { "id": "call_…", "phone": "+91…", "customerName": "Priya", "purpose": "INBOUND" },
  "contact": { "id": "ct_…", "name": "Priya", "attributes": { … }, "tags": [] } | null
}
You return
HTTP 200
{
  "result": "Order ORD-5521 is out for delivery today before 6 PM.",
  "ok": true,                 // optional; false = treated as failure
  "data": { "eta": "18:00" }, // optional; logged with the call
  "mustSay": "Keep your ID ready for the delivery agent."  // optional; said verbatim, translated
}

// Plain text works too: the body becomes "result".
// Non-2xx or timeout → the agent apologises and offers a callback; your error body is never read aloud.
Definition (what you configure)
POST /api/tools
{
  "name": "check_order_status",
  "description": "Look up the delivery status of an order when the caller gives an order number.",
  "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Order number as the caller said it" } }, "required": ["order_id"] },
  "url": "https://api.yourcompany.com/riya/check-order",
  "method": "POST",
  "headers": { "Authorization": "Bearer …" },
  "timeoutMs": 8000
}
// Test it: POST /api/tools/{id}/test { "arguments": { "order_id": "ORD-5521" } } → { ok, ms, http: { status, body }, result }

Parameter types: string, number, integer, boolean (plus enum on strings). Keep descriptions concrete: they are the only hint the model has for what to collect from the caller.

Rate limits and errors

  • 60 requests per minute per API key, enforced at the edge with x-ratelimit-limit and x-ratelimit-remaining headers on every response and a 429 with retry-after when exceeded. Counting is per edge region, so bursts spread across regions may briefly exceed it; design clients to respect the headers is the intended limit; bursts above it will return 429 with a retry-after header once enforcement is switched on. Design clients to back off on 429 today.
  • Outbound calls are additionally bounded by your plan's concurrency, the workspace calling window (default 09:00-21:00 IST, within TRAI rules) and the weekly attempt limit per number and purpose.
  • Custom action timeouts: 1-20 s (default 8 s). Webhook deliveries: 8 s.
  • Errors: 400 validation, 401 bad key, 403 role not allowed, 404 not in this workspace, 429 rate limit, 5xx ours (retry with backoff).

Changelog

  • 2026-10Initial public API: calls, contacts, campaigns, knowledge, do-not-call; outgoing webhooks with HMAC signatures; custom actions with a test endpoint; API keys.
  • Breaking changes will be announced here and by email to workspace owners at least 30 days ahead.
Ready to build?
Create a workspace, add a key and make your first call in minutes.