Build on Vocenya

Create a key in the app under Developers, then send it as a Bearer token. Every request goes to https://vocenya.com/api/public/v1.

curl -X POST https://vocenya.com/api/public/v1/leads \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Maria Lopez",
    "phone_number": "+12015550147",
    "email": "maria@example.com",
    "reason": "Quote for a water heater replacement"
  }'

curl https://vocenya.com/api/public/v1/calls \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Accept: application/json"

Lists come back newest first, a page at a time. Pass the page's meta.next_cursor as ?cursor= to get the next. Asking for an AI callback when you create a lead also needs the outbound:write scope. Errors always have the same shape: {"message": "...", "code": "..."}, with errors added when a field fails validation.

API keys belong to your organization, not to a person, so they keep working when someone leaves the team. The full key is shown once, when you create it; we keep only a hash. Give each key only the scopes it needs, and revoke it in the app at any time.

A missing or revoked key gets 401. A key without the scope a request needs gets 403 with the code missing_scope.

Add an https endpoint in the app, or with the API, and pick the events it should receive. We POST JSON to it when:

• lead.createdA lead was captured
• call.completedAn inbound call ended
• booking.createdAn appointment was booked
• chat.handed_offA website chat was handed to a person
• outbound_call.completedAn outbound call ended
• chat.startedA visitor started a website chat
• chat.message.createdA website chat got a new message
• chat.lead_capturedA website chat captured a lead
• chat.handoff_requestedThe visitor or the AI asked for a person in a website chat
• chat.closedA website chat was closed
• call.missedA caller hung up before anyone answered
• message.takenA live agent took a message from a caller
• sms.receivedA customer texted one of your numbers
• sms.sentA text was sent from one of your numbers

Each delivery carries a Vocenya-Signature header in the form t=timestamp,v1=hex. The signature is an HMAC-SHA256 of timestamp.raw_body using your endpoint secret. Check it against the raw request body, before parsing, and reject anything older than 5 minutes.

<?php

$secret = getenv('VOCENYA_WEBHOOK_SECRET');
$payload = file_get_contents('php://input');
$header = $_SERVER['HTTP_VOCENYA_SIGNATURE'] ?? '';

parse_str(str_replace(',', '&', $header), $parts);
$timestamp = (int) ($parts['t'] ?? 0);
$signature = (string) ($parts['v1'] ?? '');

$expected = hash_hmac('sha256', $timestamp.'.'.$payload, $secret);

if (! hash_equals($expected, $signature) || abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
http_response_code(200);

import crypto from 'node:crypto';

// rawBody must be the exact bytes received, before JSON parsing.
export function verifyVocenyaSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((part) => part.split('=')),
  );
  const timestamp = Number(parts.t);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - timestamp) <= 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? '');

  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

Answer with any 2xx within 10 seconds. If your server errors, times out or is unreachable, we retry with exponential backoff, from one minute up to several hours apart, for up to 8 attempts. Each event has a unique id, in the body's id and the Vocenya-Delivery header, so you can safely ignore one you have already handled.

A key that adds endpoints through the API needs webhooks:manage plus the read scope of each event it subscribes to, for example leads:read for lead.created.

The chat is one script tag with the business's public site key, loaded once on every page, just before </body>. Don't bundle, self-host or proxy the script.

<script src="https://vocenya.com/api/chat/widget.js" data-key="pk_YOUR_SITE_KEY" async></script>

Building the site with an AI tool like Lovable, Bolt, v0, Replit, Cursor or Claude Code? Point it at the chat install instructions: where the tag goes in Next.js, Vite, Nuxt, SvelteKit, Astro, Remix and the site builders, the Content Security Policy sources to add, and the JavaScript API (Vocenya('open'), Vocenya('identify', {...})). In the app, each business also gets a ready-to-paste prompt with its own key.

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools on other services. Vocenya runs two MCP servers over streamable HTTP.

# Your account (needs an API key)
claude mcp add --transport http vocenya https://vocenya.com/mcp/platform \
  --header "Authorization: Bearer vk_live_..."

# Public site facts (no key)
claude mcp add --transport http vocenya-site https://vocenya.com/mcp/site

{
  "mcpServers": {
    "vocenya": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vocenya.com/mcp/platform",
        "--header",
        "Authorization:${VOCENYA_AUTH}"
      ],
      "env": {
        "VOCENYA_AUTH": "Bearer vk_live_..."
      }
    },
    "vocenya-site": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vocenya.com/mcp/site"
      ]
    }
  }
}

{
  "mcpServers": {
    "vocenya": {
      "url": "https://vocenya.com/mcp/platform",
      "headers": {
        "Authorization": "Bearer vk_live_..."
      }
    },
    "vocenya-site": {
      "url": "https://vocenya.com/mcp/site"
    }
  }
}

Replace vk_live_... with your key. Treat it like a password: anyone with it can use the scopes it carries.

Each API key can make 120 requests a minute by default, shared between the REST API and the platform MCP server. Over the limit you get 429 Too Many Requests with a Retry-After header. The public site server, and repeated requests with a missing or invalid key, are limited per IP address.

For practices in HIPAA mode, the API and the MCP server leave out call transcripts, summaries, handoff notes, chat message text and the reason and details of a lead. Webhooks carry ids only, so your server fetches details over an authenticated request. Call recordings are never available through the API.

• API referenceEvery endpoint, field and error
• OpenAPI JSONGenerate a client or import it
• llms.txtOur site, in a form AI agents read