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

  1. Sign in to your console and open Developers.
  2. Create an API key and copy it. It is shown once.
  3. 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

ParameterMeaning
limit1 to 100, default 20
channelvoice (phone call), whatsapp (chat), whatsapp_call or sms
outcomebooked, rescheduled, answered, handed_over, reminder_confirmed or no_answer
sinceOnly conversations that started at or after this time
starting_afterFor 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.

EventWhen it is sent
conversation.completedA call, chat or SMS conversation finished
booking.createdThe agent booked an appointment
handover.requestedThe agent passed a conversation to your team
change.appliedA 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"
  }
}
StatusCodeMeaning
400invalid_parameterA query parameter is not valid
401unauthorizedMissing, wrong or revoked key
404not_foundNo such conversation or endpoint
405method_not_allowedThe API is read-only for now
429rate_limitedMore 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.