{ "openapi": "3.1.0", "info": { "title": "DaleVoz API", "version": "1", "description": "DaleVoz API v1: make an agent talk, read its conversations, write its configuration. Documentation: https://dalevoz.ai/en/docs" }, "servers": [ { "url": "https://dalevoz.ai" } ], "externalDocs": { "url": "https://dalevoz.ai/en/docs" }, "tags": [ { "name": "Conversation" }, { "name": "Voice" }, { "name": "Appearance" }, { "name": "Administration" }, { "name": "Site reading" }, { "name": "GDPR" } ], "paths": { "/api/v1/interact": { "post": { "tags": [ "Conversation" ], "summary": "Move a conversation forward by one turn", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "parameters": [ { "name": "x-dalevoz-channel", "in": "header", "required": false, "description": "Channel, takes precedence over `channel` in the body. Default: widget (pk_) or api (sk_).", "schema": { "type": "string", "enum": [ "widget", "iframe", "sdk_js", "ios", "android", "api", "zendesk", "playground", "whatsapp", "messenger", "instagram", "voice" ] } }, { "name": "x-dalevoz-identity", "in": "header", "required": false, "description": "HS256 signed identity token (see /en/docs#identite). A valid token replaces `user`.", "schema": { "type": "string", "maxLength": 4096 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractRequest" } } } }, "responses": { "200": { "description": "The turn's response. With `stream: true`, a text/event-stream of events (session, meta, delta, tool, final, error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid JSON body, or invalid request (`issues`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key, or identity token rejected, or `user.id` declared on a key that requires a signed identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Unknown agent, or never published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "423": { "description": "Agent paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limit: 300 calls per minute, 3,000 per hour and 20,000 per day per key; 40 per minute and 600 per hour per visitor. The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } }, "500": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "502": { "description": "Model response ended without a result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/messages": { "get": { "tags": [ "Conversation" ], "summary": "Messages from a human agent since a cursor", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "Conversation identifier.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Cursor returned by the previous call (ISO date).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "50 items at most.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "from": { "const": "human_agent" }, "agentName": { "type": [ "string", "null" ] }, "text": { "type": "string" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "etat": { "type": "string" }, "message": { "type": "string" } } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "traces": { "type": "array", "items": { "$ref": "#/components/schemas/Trace" } } } } }, "cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "sessionId required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Unknown session (or one from another workspace).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/history": { "get": { "tags": [ "Conversation" ], "summary": "The thread of a conversation, to display it again", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "Conversation identifier (UUID). Unknown: empty items.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The 60 most recent items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "user", "bot", "human" ] }, "agentName": { "type": "string" }, "traces": { "type": "array", "items": { "$ref": "#/components/schemas/Trace" } } } } } } } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/attachments": { "post": { "tags": [ "Conversation" ], "summary": "Extract the text from a PDF or DOCX", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mediaType", "data" ], "properties": { "mediaType": { "type": "string", "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ] }, "data": { "type": "string", "maxLength": 15000000, "description": "The file in base64." }, "filename": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Extracted text, truncated at 20,000 characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "text": { "type": "string" }, "truncated": { "type": "boolean" } } } } } }, "400": { "description": "Unsupported type, missing or oversized file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "422": { "description": "Extraction failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "Rate limit: 60 per minute, 600 per hour and 3,000 per day per key; 10 per minute and 60 per hour per visitor. The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } } } } }, "/api/v1/voice/dictee": { "post": { "tags": [ "Voice" ], "summary": "Transcribe a spoken turn", "security": [ { "clePubliable": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "agent", "audio" ], "properties": { "agent": { "type": "string" }, "audio": { "type": "string", "format": "binary", "description": "8 MB at most." }, "dureeMs": { "type": "integer", "description": "120,000 at most." }, "locale": { "type": "string" } } } } } }, "responses": { "200": { "description": "Transcription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "texte": { "type": "string" }, "langue": { "type": "string" }, "secondes": { "type": "number" }, "vide": { "type": "boolean" } } } } } }, "400": { "description": "Multipart body expected, agent and audio required, empty audio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Publishable key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found or not published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "413": { "description": "Audio too large, or turn too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "More than 20 dictations per minute for this workspace, or rate limit: 600 per hour and 4,000 per day per key (dictation and speech together); 20 per minute and 200 per hour per visitor. The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } }, "503": { "description": "Listening not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/voice/lecture": { "post": { "tags": [ "Voice" ], "summary": "Read a text aloud in the agent's voice", "security": [ { "clePubliable": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "texte" ], "properties": { "agent": { "type": "string" }, "texte": { "type": "string", "description": "Truncated at 1,200 characters." }, "conversationId": { "type": "string" }, "locale": { "type": "string" } } } } } }, "responses": { "200": { "description": "The audio bytes.", "content": { "audio/*": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "JSON body expected, agent and text required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Publishable key required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key called from a domain missing from its list (code: origine_non_autorisee).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found or not published.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "More than 30 readings per minute for this workspace, or rate limit: 600 per hour and 4,000 per day per key (dictation and speech together); 20 per minute and 200 per hour per visitor. The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } }, "503": { "description": "Speech not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/voix/{id}": { "get": { "tags": [ "Voice" ], "summary": "The audio of one of the agent's voice notes (public)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audio, private cache for one hour.", "content": { "audio/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/theme": { "get": { "tags": [ "Appearance" ], "summary": "Public theme of an agent's published version", "security": [ { "clePubliable": [] }, { "cleServeur": [] }, { "cleEnParametre": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "Language of the displayed name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resolved theme. Public cache 60 s.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "object" }, "agentName": { "type": "string" }, "title": { "type": "string" }, "textIdleMs": { "type": "integer" }, "attachmentsEnabled": { "type": "boolean" }, "voiceMode": { "type": "string" }, "pttSilenceMs": { "type": "integer" }, "conformite": { "$ref": "#/components/schemas/Conformite" }, "credit": { "$ref": "#/components/schemas/CreditWidget" } } } } } }, "401": { "description": "Missing key or agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/assets/{id}": { "get": { "tags": [ "Appearance" ], "summary": "An image from a workspace's library (public)", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The image, immutable cache for one year.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/agents": { "post": { "tags": [ "Administration" ], "summary": "Create an agent, or rewrite it by its slug", "security": [ { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "name", "systemPrompt" ], "properties": { "slug": { "type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[a-z0-9][a-z0-9-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "systemPrompt": { "type": "string", "minLength": 1, "maxLength": 60000 }, "llmProvider": { "type": "string", "enum": [ "anthropic", "openai", "grok", "gemini" ] }, "llmModel": { "type": "string", "maxLength": 80 }, "localeDefault": { "type": "string", "minLength": 2, "maxLength": 5 }, "status": { "type": "string", "enum": [ "draft", "live", "paused" ] }, "maxTokens": { "type": "integer", "minimum": 256, "maximum": 32000, "description": "If absent: 4096, including on a rewrite." }, "greetingByLocale": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } }, "launchButtonsByLocale": { "type": "object", "additionalProperties": { "type": "array", "minItems": 2, "maxItems": 5, "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "Starts with an emoji, 20 characters at most." }, "value": { "type": "string" } } } } }, "settings": { "type": "object", "description": "Merged into the existing settings." }, "motif": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Written.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "cree": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Validation, format rule for the welcome message or the buttons, model not in the plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "500": { "description": "Server error during the write.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/segments": { "get": { "tags": [ "Administration" ], "summary": "List an agent's segments", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segments, without the prompt contents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "segment": { "type": "string" }, "champs": { "type": "array", "items": { "type": "string" } }, "promptFragmentLongueur": { "type": "integer" }, "systemPromptLongueur": { "type": "integer" } } } } } } } } }, "400": { "description": "agent parameter required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } }, "post": { "tags": [ "Administration" ], "summary": "Create or replace a segment", "security": [ { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "segment", "config" ], "properties": { "agent": { "type": "string" }, "segment": { "type": "string", "maxLength": 60, "pattern": "^[a-z0-9][a-z0-9_-]{0,59}$" }, "config": { "$ref": "#/components/schemas/SegmentConfig" }, "autoriserDefault": { "type": "boolean" }, "autoriserVocal": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Written.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "segment": { "type": "string" }, "champs": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Validation, segment name, default without autoriserDefault, prompt without a random token, open voice without autoriserVocal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } }, "delete": { "tags": [ "Administration" ], "summary": "Delete a segment", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } }, { "name": "segment", "in": "query", "required": true, "description": "Segment name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "segment": { "type": "string" }, "supprime": { "const": true } } } } } }, "400": { "description": "agent and segment parameters required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/kb/sync-table": { "post": { "tags": [ "Administration" ], "summary": "Sync rows into the knowledge base", "security": [ { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "rows" ], "properties": { "agent": { "type": "string" }, "collection": { "type": "string", "maxLength": 120, "description": "With it, the upload replaces the whole batch." }, "rows": { "type": "array", "minItems": 1, "maxItems": 2000, "items": { "type": "object", "required": [ "name", "text" ], "properties": { "name": { "type": "string" }, "text": { "type": "string" }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" } } } }, "motif": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Synced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "integer" }, "chunks": { "type": "integer" }, "collection": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "409": { "description": "Batch synced automatically from a help center.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "500": { "description": "Server error during the import.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/kb/rows": { "get": { "tags": [ "Administration" ], "summary": "Read back the entries of an agent or a batch", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } }, { "name": "collection", "in": "query", "required": false, "description": "Batch name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "collection": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "sourceUrl": { "type": [ "string", "null" ] }, "text": { "type": "string" } } } } } } } } }, "400": { "description": "Missing agent parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/analytics": { "get": { "tags": [ "Administration" ], "summary": "An agent's results over a period", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "1 to 90, 7 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 90 } }, { "name": "from", "in": "query", "required": false, "description": "ISO start, takes precedence over days.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "ISO end.", "schema": { "type": "string", "format": "date-time" } }, { "name": "channels", "in": "query", "required": false, "description": "Channels to keep, comma-separated.", "schema": { "type": "string" } }, { "name": "excludePrefix", "in": "query", "required": false, "description": "Visitor identifier prefixes to exclude, comma-separated.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "periode": { "type": "object" }, "tronque": { "type": "boolean" }, "totaux": { "type": "object" }, "fichesOuvertes": { "type": "array", "items": { "type": "object" } }, "questionsSansFiche": { "type": "array", "items": { "type": "object" } }, "demandes": { "type": "object" }, "rendezVous": { "type": "object" }, "pagesOrigine": { "type": "array", "items": { "type": "object" } }, "satisfaction": { "type": "object" }, "sansIssue": { "type": "array", "items": { "type": "object" } }, "ventes": { "type": "object" }, "langues": { "type": "object" }, "canaux": { "type": "object" }, "joursActivite": { "type": "object" }, "heuresActivite": { "type": "object" }, "conversations": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Missing agent parameter, invalid date, from after to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/conversations/export": { "get": { "tags": [ "Administration" ], "summary": "Raw export of conversations, turns included", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": true, "description": "The agent's technical name.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "ISO start.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "ISO end.", "schema": { "type": "string", "format": "date-time" } }, { "name": "channels", "in": "query", "required": false, "description": "Channels to keep, comma-separated.", "schema": { "type": "string" } }, { "name": "excludePrefix", "in": "query", "required": false, "description": "Visitor identifier prefixes to exclude.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 200, 100 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "nextCursor from the previous page.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "periode": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "status": { "type": "string" }, "locale": { "type": [ "string", "null" ] }, "externalUserId": { "type": [ "string", "null" ] }, "issue": {}, "satisfaction": {}, "sujet": {}, "classifieAt": { "type": [ "string", "null" ] }, "turns": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": {}, "createdAt": { "type": "string" } } } } } } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Missing parameter or invalid date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/site/lire": { "post": { "tags": [ "Site reading" ], "summary": "Have the agent read a website (landing page)", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent", "url" ], "properties": { "agent": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "minLength": 3, "maxLength": 500 }, "locale": { "type": "string", "minLength": 2, "maxLength": 10 }, "segment": { "type": "string", "maxLength": 60 }, "contexte": { "type": "object" } } } } } }, "responses": { "200": { "description": "Reading started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "statut": { "const": "encours" }, "url": { "type": "string" } } } } } }, "400": { "description": "Invalid request, or adresse-invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "Origin not allowed, or lecture-desactivee on the agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "agent-inconnu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "422": { "description": "site-injoignable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "error: trop-de-lectures (6 per hour per IP), or key limit: 60 readings per hour and 400 per day (error: trop-de-lectures, code: limite, the sentence in message). The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } } } } }, "/api/v1/site/statut": { "get": { "tags": [ "Site reading" ], "summary": "Status of a site reading", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "parameters": [ { "name": "sessionId", "in": "query", "required": true, "description": "Identifier returned by site/lire.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statut": { "type": "string", "enum": [ "aucune", "encours", "pret", "echec" ] }, "url": { "type": "string" }, "pages": { "type": "integer" }, "titre": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing sessionId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "Origin not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "session-inconnue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/site/pont-whatsapp": { "post": { "tags": [ "Site reading" ], "summary": "Continue the conversation on WhatsApp", "security": [ { "clePubliable": [] }, { "cleServeur": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "telephone" ], "properties": { "sessionId": { "type": "string", "format": "uuid" }, "telephone": { "type": "string", "minLength": 6, "maxLength": 30 } } } } } }, "responses": { "200": { "description": "Sent, or already sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "waId": { "type": "string" }, "deja": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request, or numero-invalide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "Origin not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "session-inconnue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "409": { "description": "site-non-lu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "429": { "description": "error: trop-d-envois (3 per hour per IP), or key limit: 30 sends per hour and 200 per day (error: trop-d-envois, code: limite, the sentence in message). The visitor is counted by IP address, and only behind a pk_ key. The `error` sentence is written for the visitor, in their language.", "headers": { "Retry-After": { "description": "Seconds until the exceeded window reopens.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plafond" } } } }, "502": { "description": "envoi-refuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "503": { "description": "canal-absent or canal-sans-jeton.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/visiteurs/{userId}/export": { "get": { "tags": [ "GDPR" ], "summary": "Export everything DaleVoz keeps about a visitor (right of access and portability)", "description": "Scoped to the key's workspace. Conversations (turns included, including those removed from the thread, marked deletedAt), consent date, memory record, leads, appointments and orders. An unknown visitor returns empty lists.", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The visitor's identifier (user.id, sub of the signed token, WhatsApp number…), URL-encoded. 200 characters at most.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "agent", "in": "query", "required": false, "description": "Technical name or UUID of an agent in the workspace, to scope to that agent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The visitor's data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportVisiteur" } } } }, "400": { "description": "Missing or too long identifier (code: visiteur_invalide).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found for this key (code: agent_introuvable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } }, "/api/v1/visiteurs/{userId}": { "delete": { "tags": [ "GDPR" ], "summary": "Erase a visitor (right to erasure)", "description": "Irreversible, scoped to the key's workspace. Erases the conversations (turns, leads, voice notes), the memory record, the leads carrying the identifier and the linked Instagram comments. Anonymizes appointments and orders (name, email, phone, free text removed), detaches costs and sales. 200 even when there was nothing.", "security": [ { "cleServeur": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 200 } }, { "name": "agent", "in": "query", "required": false, "description": "Technical name or UUID of an agent in the workspace, to scope to that agent.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "What was erased and anonymized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "deleted": { "type": "object", "properties": { "conversations": { "type": "integer" }, "memories": { "type": "integer" }, "leads": { "type": "integer" }, "instagramComments": { "type": "integer" } } }, "anonymized": { "type": "object", "properties": { "bookings": { "type": "integer" }, "orders": { "type": "integer" } } } } } } } }, "400": { "description": "Missing or too long identifier (code: visiteur_invalide).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "401": { "description": "Missing, invalid or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "403": { "description": "pk_ key on a route reserved for sk_ keys.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } }, "404": { "description": "Agent not found for this key (code: agent_introuvable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erreur" } } } } } } } }, "components": { "securitySchemes": { "clePubliable": { "type": "http", "scheme": "bearer", "description": "Publishable key pk_…, restricted by the key's domain list (Origin/Referer)." }, "cleServeur": { "type": "http", "scheme": "bearer", "description": "Server key sk_…, to keep on your server." }, "cleEnParametre": { "type": "apiKey", "in": "query", "name": "key", "description": "Accepted by /api/v1/theme only." } }, "schemas": { "Plafond": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "The sentence for the visitor (or the legacy code on site/lire and site/pont-whatsapp)." }, "message": { "type": "string", "description": "site/lire and site/pont-whatsapp: the sentence for the visitor." }, "code": { "const": "limite" }, "portee": { "type": "string", "enum": [ "cle", "visiteur", "espace" ] }, "reessayerDansS": { "type": "integer" } } }, "Conformite": { "type": "object", "description": "The widget's AI notice and consent banner, both off by default. Set in the Appearance tab or through MCP (agent_conformite).", "properties": { "mentionIa": { "type": "object", "properties": { "actif": { "type": "boolean", "description": "Shows the notice under the widget header. False by default." }, "style": { "type": "string", "enum": [ "visible", "discrete" ] }, "texte": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Language → custom text. Absent = shipped text." } } }, "consentement": { "type": "object", "properties": { "actif": { "type": "boolean" }, "texte": { "type": "object", "additionalProperties": { "type": "string" } }, "lienPolitique": { "type": [ "string", "null" ] } } } } }, "CreditWidget": { "type": "object", "description": "The effective credit line under the widget input: what is set on the agent, otherwise the default for the workspace's plan (“Created by DaleVoz” on every plan except the paid self-serve subscription, which shows none). Set in the Appearance tab or through MCP (agent_credit).", "properties": { "marque": { "type": "string", "enum": [ "aucune", "dalevoz", "revolution" ] }, "niveau": { "type": "string", "enum": [ "visible", "discret" ] }, "origine": { "type": "string", "enum": [ "reglage", "formule" ] } } }, "ExportVisiteur": { "type": "object", "properties": { "userId": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "exportedAt": { "type": "string", "format": "date-time" }, "conversations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agent": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "userName": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "context": { "type": "object" }, "summary": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "satisfaction": { "type": [ "string", "null" ] }, "consentAt": { "type": [ "string", "null" ], "format": "date-time" }, "closedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "turns": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": {}, "createdAt": { "type": "string" }, "deletedAt": { "type": "string" } } } } } } }, "memories": { "type": "array", "items": { "type": "object" } }, "leads": { "type": "array", "items": { "type": "object" } }, "bookings": { "type": "array", "items": { "type": "object" } }, "orders": { "type": "array", "items": { "type": "object" } } } }, "Erreur": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "detail": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object" } }, "avertissements": { "type": "array", "items": { "type": "string" } } } }, "Attachment": { "oneOf": [ { "type": "object", "required": [ "kind", "mediaType", "data" ], "properties": { "kind": { "const": "image" }, "filename": { "type": "string", "maxLength": 200 }, "mediaType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif" ] }, "data": { "type": "string", "description": "base64 without a data: prefix" } } }, { "type": "object", "required": [ "kind", "filename", "text" ], "properties": { "kind": { "const": "text" }, "filename": { "type": "string", "maxLength": 200 }, "text": { "type": "string" }, "truncated": { "type": "boolean" } } } ] }, "Action": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "const": "launch" }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "const": "text" }, "payload": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 8000 }, "attachments": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/Attachment" } }, "parle": { "type": "boolean" } } } } }, { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "const": "choice" }, "payload": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } }, { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "const": "event" }, "payload": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "data": {} } } } } ] }, "InteractRequest": { "type": "object", "required": [ "agent", "action" ], "description": "An unknown field is ignored and named in `avertissements`. Aliases understood: userId/user_id, locale/langue/language, channel/canal, message (without action).", "properties": { "agent": { "type": "string", "description": "Technical name (slug) or identifier (UUID) of the agent." }, "sessionId": { "type": [ "string", "null" ], "format": "uuid" }, "action": { "$ref": "#/components/schemas/Action" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "locale": { "type": "string" } } }, "context": { "type": "object", "description": "Frozen when the conversation is created. context.segment chooses a segment." }, "contexte": { "type": "object", "description": "Merged on every turn, filtered by the variables declared on the agent." }, "stream": { "type": "boolean" }, "consentement": { "type": "string", "format": "date-time", "maxLength": 40, "description": "ISO date at which the visitor accepted the widget's consent banner. Set once on the conversation (returned by the GDPR export); a date in the future or more than 400 days old is replaced by the server time." }, "channel": { "type": "string", "enum": [ "widget", "iframe", "sdk_js", "ios", "android", "api", "zendesk", "playground", "whatsapp", "messenger", "instagram", "voice" ], "description": "Alias; the x-dalevoz-channel header takes precedence." } } }, "InteractResponse": { "type": "object", "required": [ "sessionId", "traces" ], "properties": { "sessionId": { "type": "string", "description": "UUID; empty when the plan limit rejects a new conversation." }, "traces": { "type": "array", "items": { "$ref": "#/components/schemas/Trace" } }, "usage": { "type": "object", "description": "sk_ keys only.", "properties": { "tokensIn": { "type": "number" }, "tokensOut": { "type": "number" }, "costMicroUsd": { "type": "number" } } }, "avertissements": { "type": "array", "items": { "type": "string" } } } }, "Trace": { "type": "object", "required": [ "type", "payload" ], "properties": { "type": { "type": "string", "enum": [ "text", "choice", "multi_choice", "slider", "card", "carousel", "document", "audio", "scheduler", "template", "handoff", "systeme", "end" ] }, "payload": { "type": "object" } } }, "SegmentConfig": { "type": "object", "additionalProperties": false, "properties": { "collections": { "type": [ "array", "null" ], "items": { "type": "string" } }, "carousels": { "type": [ "array", "null" ], "items": { "type": "string" } }, "carouselsDisabled": { "type": "boolean" }, "tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "promptFragment": { "type": [ "string", "null" ], "maxLength": 20000 }, "systemPrompt": { "type": [ "string", "null" ], "maxLength": 20000 }, "greeting": { "type": [ "string", "null" ], "maxLength": 2000 }, "launchButtons": { "type": [ "array", "null" ], "maxItems": 6, "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "maxLength": 60 }, "value": { "type": "string", "maxLength": 200 } } } }, "welcomeVideoUrl": { "type": [ "string", "null" ], "format": "uri" }, "welcomeVoiceUrl": { "type": [ "string", "null" ], "format": "uri" } } } } } }