Developer documentation

The two keys

Every call carries a key in the header Authorization: Bearer …. A key belongs to a workspace, not to an agent: it opens every agent in that workspace, and no other. The server keeps only a hash of it, so it is displayed only once, when it is created.

Where to create them.

• Server key sk_: console, Settings, “ChatGPT and Claude” tab, collapsed section “For a developer: API keys”, “Create a server key” button. Restricted to people who administer the workspace.
• Publishable key pk_: the agent's page, “Publish” tab, “Website” card, “For a technician” part. This is also where the list of allowed domains is set, and where the widget tag is copied, with the key already filled in.

First call

Replace the key and the agent name. The name is the one in the embed code (data-agent), and the agent's identifier as it appears in the console address (/agents/…) is accepted too. The API answers with the PUBLISHED version of the agent: an agent that has never been published returns 404.

curl -X POST https://dalevoz.ai/api/v1/interact \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "sessionId": null,
    "user": { "id": "client-42", "locale": "en" },
    "action": { "type": "text", "payload": { "message": "Hello, what are your opening hours?" } }
  }'

const response = await fetch("https://dalevoz.ai/api/v1/interact", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DALEVOZ_SERVER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent: "my-agent",
    sessionId: null, // null on the first message
    user: { id: "client-42", locale: "en" },
    action: { type: "text", payload: { message: "Hello, what are your opening hours?" } },
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.error);

// Send it back on the next turn to continue the same conversation
const sessionId = data.sessionId;
for (const trace of data.traces) {
  if (trace.type === "text") console.log(trace.payload.message);
}

import os
import requests

response = requests.post(
    "https://dalevoz.ai/api/v1/interact",
    headers={"Authorization": f"Bearer {os.environ['DALEVOZ_SERVER_KEY']}"},
    json={
        "agent": "my-agent",
        "sessionId": None,  # None on the first message
        "user": {"id": "client-42", "locale": "en"},
        "action": {"type": "text", "payload": {"message": "Hello, what are your opening hours?"}},
    },
    timeout=60,
)
data = response.json()
response.raise_for_status()

session_id = data["sessionId"]  # send it back on the next turn
for trace in data["traces"]:
    if trace["type"] == "text":
        print(trace["payload"]["message"])

The response:

{
  "sessionId": "0b6f7c1e-5d3a-4f1b-9a57-2c8e4d1a9f30",
  "traces": [
    { "type": "text", "payload": { "message": "We are open Tuesday to Saturday, 9 am to 7 pm.", "markdown": true } },
    { "type": "choice", "payload": { "buttons": [ { "label": "📅 Book an appointment", "value": "rdv" } ] } }
  ],
  "usage": { "tokensIn": 2140, "tokensOut": 58, "costMicroUsd": 812 }
}

• sessionId: send null on the first message, then send back the one from the response to continue the same conversation. An unknown identifier, or one from another workspace, is not an error: it opens a new conversation, and the response carries the new identifier.
• user.id: your identifier for this person. Keeping the same one from day to day lets the agent recognize them when its memory is on. With a pk_ key, memory also requires signed identity (see Signed identity). Never put a secret in this field.
• usage: only present with an sk_ key. A pk_ key never receives it, neither in JSON nor in the stream.

Conventions

• Base URL: https://dalevoz.ai. JSON bodies (Content-Type: application/json), except voice dictation, which is multipart.
• Authentication: Authorization: Bearer pk_… or Bearer sk_…. Only the theme route also accepts the key as a parameter (?key=).
• Every v1 route answers calls from another domain (CORS open to all origins): it is the key and its domain list that filter, not the browser.
• The agent is referred to by its technical name (slug), within the key's workspace. Only interact also accepts its identifier (UUID).
• An error returns an object { "error": "…" }, sometimes supplemented with issues (validation details), code and detail. On the routes the widget shows to the visitor (interact, messages, history, attachments, voice), error is a sentence for the visitor, in their language: for a program, read the HTTP status and code.

Origin rejection for a pk_ key (status 403):

{
  "error": "(neutral sentence for the visitor, in their language)",
  "code": "origine_non_autorisee",
  "detail": "Origine non autorisée pour cette clé (boutique.exemple.fr). Ajoutez ce domaine à la clé dans la console."
}

The site/* routes return this rejection in a shorter form, without code: { "error": "Origine non autorisee pour cette cle" }.

Conversation

curl -N -X POST https://dalevoz.ai/api/v1/interact \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "my-agent", "sessionId": null,
        "action": { "type": "text", "payload": { "message": "Hello" } },
        "stream": true }'

data: {"type":"session","sessionId":"0b6f7c1e-5d3a-4f1b-9a57-2c8e4d1a9f30"}

data: {"type":"meta","streaming":true}

data: {"type":"delta","text":"Hello! "}

data: {"type":"tool","kind":"recherche","phase":"start"}

data: {"type":"tool","kind":"recherche","phase":"done"}

data: {"type":"delta","text":"We're open…"}

data: {"type":"final","response":{"sessionId":"0b6f7c1e-…","traces":[…]}}

{
  "status": "human",
  "messages": [ { "id": "…", "at": "2026-09-23T10:12:04.512Z", "from": "human_agent", "agentName": "Julie", "text": "…" } ],
  "events": [ { "id": "…", "at": "…", "etat": "repris", "message": "…" } ],
  "questions": [ { "id": "…", "at": "…", "traces": [ { "type": "text", … }, { "type": "choice", … } ] } ],
  "cursor": "2026-09-23T10:12:04.513Z"
}

let cursor = "";
setInterval(async () => {
  const url = new URL("https://dalevoz.ai/api/v1/messages");
  url.searchParams.set("sessionId", sessionId);
  if (cursor) url.searchParams.set("since", cursor);
  const r = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((x) => x.json());
  for (const m of r.messages) showTeamMemberMessage(m.agentName, m.text); // deduplicate by m.id
  cursor = r.cursor ?? cursor;
}, 4000);

// 1. Extract the text from the PDF
const extracted = await fetch("https://dalevoz.ai/api/v1/attachments", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ mediaType: "application/pdf", data: base64NoPrefix, filename: "quote.pdf" }),
}).then((r) => r.json());

// 2. Send it with the message
await fetch("https://dalevoz.ai/api/v1/interact", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    agent: "my-agent",
    sessionId,
    action: {
      type: "text",
      payload: {
        message: "Can you check this quote?",
        attachments: [{ kind: "text", filename: extracted.filename, text: extracted.text, truncated: extracted.truncated }],
      },
    },
  }),
});

Voice

The routes behind the widget's push-to-talk. They use the voice pipeline configured on the published agent.

Appearance

Administration (sk_)

Write an agent and its knowledge base, and read its results, from your server. Every write is recorded in the agent's log, with the reason you give.

{
  "slug": "store-welcome",
  "name": "Store welcome",
  "systemPrompt": "You are the store's assistant…",
  "localeDefault": "en",
  "status": "draft",
  "greetingByLocale": { "en": "Hello! Shall we get started?" },
  "launchButtonsByLocale": { "en": [ { "label": "🛍️ Products" }, { "label": "🚚 Shipping" } ] },
  "motif": "Created from our back office"
}

{
  "agent": "store-welcome",
  "collection": "catalog",
  "rows": [
    { "name": "Olive vase, 24 cm", "text": "Glazed stoneware, €39, in stock.", "sourceUrl": "https://example.com/vase-olive" }
  ],
  "motif": "Nightly catalog sync"
}

{
  "agent": "store-welcome",
  "periode": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-09-08T00:00:00.000Z" },
  "conversations": [
    { "id": "…", "createdAt": "…", "updatedAt": "…", "channel": "widget", "status": "…", "locale": "fr",
      "externalUserId": "client-42", "issue": "…", "satisfaction": "…", "sujet": "…", "classifieAt": "…",
      "turns": [ { "role": "user", "content": { … }, "createdAt": "…" } ] }
  ],
  "nextCursor": "2026-09-03T17:42:10.118Z"
}

Site reading

Three routes designed for landing pages: the visitor gives their site's address, the agent reads it, then the conversation can continue on WhatsApp. They only make sense on an agent with site reading turned on.

GDPR: a visitor's data (sk_)

To answer an access or erasure request from your server. The visitor is identified by their identifier: the user.id you send, the sub of the signed token, the identifier passed to dalevoz.identify(), or the WhatsApp number. Everything is scoped to the key's workspace: two workspaces that each have their own “client-42” never see each other. ?agent= (technical name or UUID) scopes to one agent; without it, the whole workspace. URL-encode the identifier (encodeURIComponent).

curl "https://dalevoz.ai/api/v1/visiteurs/client-42/export" \
  -H "Authorization: Bearer YOUR_SERVER_KEY"

{ "userId": "client-42", "agent": null, "exportedAt": "…",
  "conversations": [ { "id": "…", "agent": "store-welcome", "channel": "widget",
      "consentAt": "2026-09-24T10:12:03.000Z", "turns": [ { "role": "user", "content": { … }, "createdAt": "…" } ] } ],
  "memories": [ { "agent": "store-welcome", "summary": "…" } ],
  "leads": [], "bookings": [], "orders": [] }

curl -X DELETE "https://dalevoz.ai/api/v1/visiteurs/client-42" \
  -H "Authorization: Bearer YOUR_SERVER_KEY"

{ "userId": "client-42", "agent": null,
  "deleted": { "conversations": 3, "memories": 1, "leads": 1, "instagramComments": 0 },
  "anonymized": { "bookings": 1, "orders": 0 } }

Tag attributes

data-canal and data-plein are set by DaleVoz's iframe embed page; you do not need to write them. data-greeting is read but has no effect: the welcome message is set on the agent.

window.dalevoz · window.DaleVoz

Both names refer to the same object. Each method is called directly (dalevoz.open()) or through the function (DaleVoz("open")), the form used by the queueing snippet below. The original French names remain valid.

<!-- Before the widget tag: calls made before it loads are queued, then replayed. -->
<script>
  window.DaleVoz = window.DaleVoz || function () {
    (window.DaleVoz.q = window.DaleVoz.q || []).push(arguments);
  };
  // Usable right away, even if the script has not loaded yet:
  DaleVoz("identify", { userId: "client-42", name: "Alexis" });
  DaleVoz("on", "message", function (m) { console.log(m.role, m.text); });
</script>

// Once loaded, window.DaleVoz and window.dalevoz are the same object.
dalevoz.open();
dalevoz.close();
dalevoz.toggle();

// What the page knows about the visitor. Merged; null erases a key.
dalevoz.contexte({ plan: "pro", cart_total: 129.9, page: "checkout" });

// A moment that can make the agent react, if it is declared on the agent.
dalevoz.evenement("cart_abandoned", { cart_total: 129.9 });

dalevoz.on("message", (m) => {
  // m.role : "user" | "assistant" | "human_agent" ; m.text ; m.sessionId
  if (m.role === "assistant") analytics.track("agent_reply");
});
dalevoz.on("open", () => console.log("panel open"));

Signed-in visitor. Without a token, the identifier remains declarative: the conversation works, but the agent neither reads nor writes this visitor's memory record. With a token, the token proves who is speaking; a key that requires signed identity then rejects any unidentified visitor. Prefer a token FUNCTION: a token lives 15 minutes at most, a conversation longer. Signed identity

// User signed in on YOUR site. The token is signed by YOUR server (see Signed identity).
dalevoz.identify({
  userId: "client-42",
  name: "Alexis Martin",
  email: "alexis@example.com", // goes through contexte(): declare the email variable on the agent
  // A function is called again before each token expiry (15 minutes at most):
  token: () => fetch("/api/dalevoz-token").then((r) => r.text()),
});

// Sign-out: back to this browser's anonymous visitor.
dalevoz.identify(null);

Events

Each event is received through dalevoz.on(name, function). The last five are also dispatched on window as a CustomEvent, with the same content in event.detail.

AI notice and consent

• The AI notice. Off by default, like the banner: you decide whether your visitors see it. Turned on in the console (Appearance tab, “AI notice and consent” block), it is a line under the header, in the visitor's language (French, Spanish or English shipped): “You are chatting with an AI. Its answers may contain mistakes.” Its text (per language, it must remain an AI notice) and its tone (visible or subtle) are set in the same place, or through MCP (agent_conformite).
• The consent banner. Off by default. Turned on in the same place, it covers the input until the visitor clicks “I accept”, with a link to YOUR privacy policy. Before consent, nothing is sent: no message, no button, no microphone. Consent is kept per browser and per agent, and its date is recorded on the conversation (consentAt in the GDPR export). The state can be read with dalevoz.consentement().

The secrets vault

An API key is never written in plain text in a tool. It is stored in the workspace's vault: console, Settings, “ChatGPT and Claude” tab, “For a developer: secrets vault”. The tool's header then refers to it by name:

Authorization: Bearer {{secret:CRM_API_KEY}}
X-Api-Key: {{secret:AGENDA_CLE}}

• The value is encrypted in the database and is NEVER displayed again, neither in the console nor through MCP: you see its name, its last four characters and the tools that reference it. To change it, store it again under the same name.
• A tool only reads the vault of ITS workspace. Only the people who administer the workspace can see and edit the vault.
• Name: uppercase letters, digits and _, starting with a letter, 64 characters at most (the console converts “crm key” into CRM_KEY). Value: 4,000 characters at most. 50 secrets per workspace.
• The older syntax {{env:TOOL_SECRET_NOM}} is still understood: it reads the secret NOM from the same vault, never a server variable.
• A secret that is referenced but missing from the vault makes the call get REJECTED: it is never sent without its authentication.

Advanced tools

• Typed fields. Each piece of information to collect has a type: text, number, integer, yes/no, choice list or date (YYYY-MM-DD). The value returned by the agent is checked before sending and goes out with its JSON type (42, not “42”). A tool without typed fields behaves as before.
• Authentication. Basic (username and password); OAuth2 client credentials (the token is requested from your tokenUrl, kept until its expiry minus 60 s, and requested again once if your API returns 401); HMAC-SHA256 signature in hexadecimal of “<X-Timestamp>.<body sent>”, in the header of your choice (X-Signature by default), with X-Timestamp in Unix seconds. Every secret (password, client secret, HMAC key) comes from the vault.
• Injected variables. Ticked per tool, they are added to the body without going through the agent, which can neither invent nor omit them: conversationId, segment, userId, canal, langue, contexte (the variables declared by the page).
• Response shaping. On a successful JSON response, the agent only receives the kept paths (data.status, items[0].name…), and at most N characters (between 100 and 8,000, 8,000 by default). Otherwise it receives the response as is.
• Edit and test. On the agent's page, “Actions” tab, each tool has “Edit” and “Test”. Test offers “See what would be sent” (method, address, headers with secrets masked, body) or “Call for real” (status, duration, response). Through MCP: outil_modifier and outil_tester.

Connect

The illustrated step by step, tool by tool, is in the console: Connect my AI. One authorization opens a single workspace: an agency adds one connection per client.

Claude (every plan, Free included, with one custom connector on Free; on Team or Enterprise, the organization owner adds it; on the web, the desktop app or your phone): the link below opens the “Add custom connector” window with the name and address already filled in. Keep the suggested options and click “Add” at the bottom of the window, then “Connect” on the connector page, and allow your workspace on the DaleVoz page that opens. Without the link: claude.ai/customize/connectors, “Add custom connector”, paste the address. The link: add DaleVoz to Claude.

ChatGPT (Plus, Pro, Business or Enterprise/Edu plan; not available on Free or Go; on Business or Enterprise, the admin of the ChatGPT workspace creates the app). Only on chatgpt.com, in a computer's browser: MCP apps exist neither in the app nor on the phone.

• In the left menu, open Plugins, click Add at the top right, then create an MCP app.
• In the New plugin window: name DaleVoz; leave the description empty; Connection on Server URL, and paste the address into the field that says https://example.com/mcp; Authentication OAuth; scroll down, tick “I understand and want to continue”; Create.
• In the Connect DaleVoz window, click Continue to DaleVoz, then authorize your workspace on the DaleVoz page.
• To use it: at the top, Work mode (it doesn't work in Chat); below the message box, Plugins, then DaleVoz. The GPT-6 Luna model is enough and the most economical in your plan.

If ChatGPT asks you to turn on developer mode before creating an MCP app: Settings, the search bar at the top of settings, type “developer”, then turn on Developer mode.

Claude Code : one command, then your browser opens for authorization.

claude mcp add --transport http dale-voz https://dalevoz.ai/api/mcp

Codex : the same logic, in two commands.

codex mcp add dale-voz --url https://dalevoz.ai/api/mcp
codex mcp login dale-voz

OAuth

• OAuth 2.1 with standard discovery: a call without a token receives a 401 whose WWW-Authenticate header points to /.well-known/oauth-protected-resource; the authorization server is described at /.well-known/oauth-authorization-server.
• Dynamic client registration, public clients only, authorization code with PKCE S256 (plain is rejected). Redirect addresses are limited to Claude and OpenAI surfaces, and to the loopback for terminal tools.
• The access token (mcpat_…) lasts 90 days, the refresh token one year. It carries a workspace and a person, nothing else: your permissions are checked again on every call, and it becomes inert as soon as you are no longer a member of the workspace. Revoking an sk_ key does not revoke an OAuth connector, and vice versa.
• HTTP transport over POST (JSON-RPC); a GET receives 405. Accepted protocol versions: 2026-07-28, 2025-11-25, 2025-06-18.

What the AI can do

To start, paste this message into a new conversation: your AI opens DaleVoz, tells you where you stand and guides you step by step.

I'm starting with DaleVoz: run dalevoz_demarrer, tell me in three lines where I stand, then guide me step by step, one question at a time, no jargon.

• Create an agent, asking first the questions that decide everything.
• Teach it your content: knowledge base, goals, lead qualification, memory.
• Configure its appearance, its voice mode, its channels (WhatsApp, phone) and its HTTP tools.
• Make it talk like a customer, run a diagnostic, read the conversations and the log.
• Publish it when you decide, and roll back to a previous version.
• Read all the documentation (the method, the agency guide, this page), section by section, with the tool dalevoz_documentation. Without a connector, it all fits in one address: https://dalevoz.ai/llms-full.txt?lang=en.
• For a partner agency, from any of its clients' workspaces: list its portfolio, create a client, set a monthly cap (agence_* tools).

The number of visible tools depends on your role and your plan. On self-service, your AI sees the essentials (create, feed, test, publish, install, read conversations) and opens the rest on demand, without reconnecting anything. Every write is recorded in the agent's log, under your name.

In what order to use them to build an agent that holds up: the method.

Three prompts to start with

• "List my DaleVoz agents and tell me which one has a problem." The AI reads each agent's status, recent conversations and diagnostics, then names what's wrong.
• "Create an agent that answers my bakery's customers using my website." The AI first asks the deciding questions (goal, tone, what it must never promise), then builds the agent and has it read the site.
• "Make my agent talk to a rushed customer who wants to book tonight, and tell me what goes wrong." The AI plays the conversation against the agent, without publishing anything, and reports what failed.

Rate limits per key

A pk_ key lives in your site's HTML: without a limit, anyone who copies it could drain your credits. Every public route therefore counts its calls in fixed windows (minute, hour, day), in the database, for the KEY (all visitors combined) and, behind a pk_ key only, for the VISITOR, recognized by their IP address. The thresholds are 10 to 20 times above the peaks measured at our customers: they stop a script, not a website. Beyond them: 429, with code limite, portee (cle or visiteur), reessayerDansS and the Retry-After header; error is a sentence for the visitor, in their language, which the widget shows once without retrying. A workspace that needs it (a conference where the whole room talks to the agent over the same Wi-Fi) can have them raised: write to us.

These limits come on top of those of the workspace's plan (conversations per month, turns per conversation), which do not answer with a 429 but with a 200 whose message tells the visitor (see the interact route).