Launch offer: the Pro plan for US$1/month or US$10/year — with a 7-day full money-back guarantee.Ends December 31, 2026: Try Pro for US$1 →

Build on the same API we build on

Everything the platform does — conversations, contacts, AI agents, knowledge, analytics — is driven by this REST API. There is no private, better API behind it: this is the one. Base URL: `https://api.inteligenciaviva.com/v1`.

Quickstart: your first request in 60 seconds

Create an API key in your workspace, export it, and list your conversations. Keys are scoped per workspace and can be read-only or read-write.

curl https://api.inteligenciaviva.com/v1/workspaces/WORKSPACE_ID/conversations \
  -H "Authorization: Bearer sk_live_..."

Every response is JSON. Collection endpoints return `data` arrays; errors return an `error` object with `code` and `message` and a matching HTTP status.

The free API — no account, no key

The free layer speaks API too. `POST /v1/free/widget-snippet` takes the exact same configuration the visual generator builds on the Free page and returns the ready-to-paste HTML snippet — no authentication, no signup. Use it to batch-generate widgets for client sites, regenerate embeds from CI when schedules change, or simply to touch the API before paying a cent.

curl -X POST https://api.inteligenciaviva.com/v1/free/widget-snippet \
  -H "Content-Type: application/json" \
  -d @widget-config.json
# → { "snippet": "<link rel=\"stylesheet\" ..." }

Authentication

All requests carry an API key in the `Authorization` header as a Bearer token. Keys are created and revoked from the API itself or in the dashboard, per workspace — revoking a key cuts its access immediately.

Account-level session endpoints (register, login, Google sign-in, ticket exchange, profile, account deletion under `/v1/auth`) power our own apps; for server-to-server integrations always prefer workspace API keys over user sessions.

Authorization: Bearer sk_live_...

Resource reference

All routes below hang from `https://api.inteligenciaviva.com/v1/workspaces/{workspaceId}` unless noted. This is the real mounted surface of the current backend — not aspirational.

Conversations /conversations

GET/List conversations, filterable by state.
GET/{id}One conversation with its state, channel, contact and assignment.
GET/{id}/messagesMessage history (visitor, human agent, AI, system).
POST/{id}/messagesSend a message into the conversation as an agent.
POST/{id}/assignAssign the conversation to a human agent or department.
POST/{id}/resolveClose the conversation. If the AI closed it alone, it counts as a billable resolution.

Contacts /contacts

GET/List contacts.
GET/{id}One contact with its identities and conversation history.
POST/Create a contact.

AI agents /ai-agents

GET/List the workspace's AI agents.
POST/Create an AI agent: instructions, department, confidence threshold.
PATCH/{id}Update instructions, threshold or department.
GET/{id}/knowledge-sourcesKnowledge sources attached to this agent.
POST/{id}/knowledge-sourcesAttach a knowledge source to this agent.

Knowledge (RAG) /knowledge-sources

POST/documentIndex a document as grounded knowledge.
POST/urlIndex a URL.
GET/{id}Source status and metadata.
DELETE/{id}Remove a source and its vectors.

Channels /channels

GET/List channels. Live today: web chat and API; more connect as they ship.
PUT/{id}/credentialsSet a channel's credentials.
PUT/{id}/statusEnable or disable a channel.

Human agents & departments /agents · /departments

GET/agentsList human agents in the workspace.
POST/agents/{userId}/departmentsPut an agent in a department.
GET/departmentsList departments.
PUT/departments/{id}/routing-rulesSet routing rules for incoming conversations.

Webhooks, keys, billing, analytics /webhooks · /api-keys · /billing · /analytics

POST/webhooksRegister an endpoint; you receive its signing secret once.
DELETE/webhooks/{id}Remove an endpoint.
POST/api-keysCreate a key (read-only or read-write).
DELETE/api-keys/{id}Revoke a key immediately.
GET/billing/subscriptionPlan, included AI resolutions and usage this period.
GET/analyticsAggregate metrics for the workspace.

Real examples

Send an agent message (curl)

curl -X POST \
  https://api.inteligenciaviva.com/v1/workspaces/$WS/conversations/$CONV/messages \
  -H "Authorization: Bearer $IV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hi! I checked your order — it ships tomorrow."}'

List conversations (JavaScript)

const res = await fetch(
  `https://api.inteligenciaviva.com/v1/workspaces/${WS}/conversations`,
  { headers: { Authorization: `Bearer ${process.env.IV_KEY}` } }
);
const { data } = await res.json();

Verify a webhook signature (Node)

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

function verify(secret, rawBody, header, toleranceSec = 300) {
  const { t, v1 } = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Webhooks

Register an HTTPS endpoint and we POST every event to it, signed. The header is `iv-signature: t=<unix>,v1=<hex>`, where `v1` is the HMAC-SHA256 of `<timestamp>.<raw body>` with your endpoint's secret — reject anything older than 5 minutes (replay protection). Failed deliveries are retried automatically with a fresh signature, up to 5 attempts.

conversation.createdA new conversation started on any channel.
message.createdA message landed (visitor, human, AI or system).
handoff.requestedThe AI decided it needs a human — the exact moment, with the summary.
conversation.resolvedA conversation closed; tells you whether the AI closed it alone.

Every delivery and its status is recorded — a webhook you can't trust is worse than none.

Real-time streaming

For live UIs, open a WebSocket against the workspace stream and receive conversation events as they happen — the same channel our own agent apps use.

wss://api.inteligenciaviva.com/v1/workspaces/{workspaceId}/stream

Errors and limits

Errors are conventional HTTP: `400` malformed request, `401` missing or invalid key, `403` key without scope, `404` resource not in this workspace, `429` rate limited (back off and retry with jitter), `5xx` our fault — retry idempotent requests. The body always carries an `error.code` and a human `error.message`. Rate limits are per key and generous for real integrations.

Frequently asked questions

Is this documentation aspirational or the real surface?

Real. It is written against the mounted routes of the current backend. When something here says "coming", it does not exist yet — we don't document vapor.

Do I need a paid plan to use the API?

Yes — the API is part of the paid platform (Pro includes it). The free Widget and WordPress plugin are client-side and need no API at all.

What's the difference between read-only and read-write keys?

Read-only keys can list and fetch but never mutate — ideal for dashboards and BI. Read-write keys can create messages, contacts, AI agents and configuration.

How do I get notified of new messages — polling or webhooks?

Webhooks (`message.created`) for servers, the WebSocket stream for live UIs. Polling works but you'll hit rate limits before you get real-time.

How exactly do I verify a webhook came from you?

Recompute HMAC-SHA256 of `<t>.<raw body>` with your endpoint secret and compare in constant time with the `v1` value of the `iv-signature` header; reject if `t` is older than 300 seconds. Working code is on this page.

What happens if my webhook endpoint is down?

We record the failed delivery and retry automatically with a fresh timestamp and signature, up to 5 attempts. If the endpoint was deleted or disabled meanwhile, retries stop cleanly.

Can the AI hand off to my own escalation system?

Yes — that's precisely `handoff.requested`. It fires the moment the AI's confidence drops below the workspace threshold, carrying the conversation summary, so you can page a person or open a ticket elsewhere.

Which channels can I drive through the API today?

Web chat is live end to end, and everything in this reference works today. Telegram and further messaging channels connect to the same conversation model as they ship — your integration won't change.

Is there an SDK?

A Flutter SDK powers our own agent app and is the base of the white-label Enterprise SDK. For servers, the REST surface is deliberately plain — any HTTP client works without a wrapper.

Where do I report an API bug or a gap in these docs?

Write to l@inteligenciaviva.com. Docs that lie are bugs too — we treat them with the same severity.