Developers
Connect vaartu.ai to your CRM.
Read every conversation and its result with a simple REST API, and get a signed webhook the moment your agent books an appointment, hands a call to your team or finishes a conversation.
Getting started
- Sign in to your console and open Developers.
- Create an API key and copy it. It is shown once.
- Call the API from your server, or add a webhook endpoint so we can send you events.
The base address is https://app.vaartu.ai/v1. Everything is JSON over HTTPS. Times are UTC in ISO 8601, for example 2026-10-04T09:40:00Z.
Authentication
Send your key in the Authorization header. Keys start with vk_live_, or vk_test_ on sample accounts. Keep them on your server, never in a web page or app. Revoke a key in the console at any time; apps using it stop working immediately.
Authorization: Bearer vk_live_…
Conversations
Every phone call, WhatsApp chat, WhatsApp call and SMS conversation, newest first, with what happened.
GET /v1/conversations
| Parameter | Meaning |
|---|---|
limit | 1 to 100, default 20 |
channel | voice (phone call), whatsapp (chat), whatsapp_call or sms |
outcome | booked, rescheduled, answered, handed_over, reminder_confirmed or no_answer |
since | Only conversations that started at or after this time |
starting_after | For the next page: the last id from the previous page, while has_more is true |
curl "https://app.vaartu.ai/v1/conversations?limit=2&channel=sms" \
-H "Authorization: Bearer vk_live_…"
{
"data": [
{
"id": "conv_236",
"channel": "sms",
"direction": "outbound",
"started_at": "2026-10-03T06:21:00Z",
"duration_seconds": 0,
"customer": "+91 966•• ••59",
"language": "English",
"outcome": "reminder_confirmed",
"summary": "SMS reminder: patient replied 1 to confirm tomorrow's visit."
}
],
"has_more": true
}
When a message was sent on a second channel because the first didn’t get through, fallback_from names the first channel (for example an SMS with "fallback_from": "whatsapp"); otherwise it is null.
GET /v1/conversations/{id}
One conversation with its full transcript: a list of {"speaker": "agent" | "customer", "text": "…"}.
Usage
GET /v1/usage
This month’s usage, the same figures as Plan and usage in your console.
{
"month": "2026-10",
"plan": "Growth",
"phone_minutes_included": 3000,
"phone_minutes_used": 50,
"whatsapp_chats": 10,
"whatsapp_call_minutes": 21,
"sms_sent": 5,
"conversations": 45
}
Webhooks
Add an endpoint in your console, choose its events, and we send a POST to it when they happen. Endpoints must use https:// on a public address. Reply with any 2xx status within 8 seconds. Every delivery, with its result, is listed in your console.
| Event | When it is sent |
|---|---|
conversation.completed | A call, chat or SMS conversation finished |
booking.created | The agent booked an appointment |
handover.requested | The agent passed a conversation to your team |
change.applied | A change to your agent’s settings was confirmed |
POST /your-webhook HTTP/1.1
Content-Type: application/json
Vaartu-Event: booking.created
Vaartu-Signature: t=1791060000,v1=5f2b…c9e1
{
"id": "evt_8c1d2f0a9b3e4d57",
"type": "booking.created",
"created_at": "2026-10-04T09:40:00Z",
"test": false,
"data": {
"id": "conv_241",
"channel": "whatsapp_call",
"outcome": "booked",
"summary": "WhatsApp call: booked a follow-up visit for Monday 6 pm.",
…
}
}
Use Send test in the console to send a sample event ("test": true) to your endpoint.
Verifying signatures
Each endpoint has its own signing secret (whsec_…), shown once when you add it. The Vaartu-Signature header holds a timestamp t and v1, an HMAC-SHA256 of "t.raw_body" made with your secret. Check it against the raw request body, before parsing the JSON.
Python
import hashlib, hmac, time
def is_from_vaartu(raw_body: bytes, signature_header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in signature_header.split(","))
t, v1 = parts["t"], parts["v1"]
if abs(time.time() - int(t)) > 300: # reject old or replayed events
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Node.js
import crypto from "node:crypto";
export function isFromVaartu(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret)
.update(`${parts.t}.`).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
Errors and limits
Errors use standard HTTP status codes with a JSON body.
{
"error": {
"code": "unauthorized",
"message": "This API key is not valid or has been revoked"
}
}
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_parameter | A query parameter is not valid |
| 401 | unauthorized | Missing, wrong or revoked key |
| 404 | not_found | No such conversation or endpoint |
| 405 | method_not_allowed | The API is read-only for now |
| 429 | rate_limited | More than 60 requests a minute on one key |
You can have up to 5 active keys and 3 webhook endpoints per account.
Coming soon
- Place an outbound call or WhatsApp call from your CRM
- Send a WhatsApp message or SMS from an approved template
- Ready-made connectors for popular Indian CRMs
Need one of these now, or a different integration? Tell us what you use.