Speech & Agent Integration APIs

These endpoints let you embed AI-driven chat, voice synthesis, and speech transcription directly into your product. Your workspace admin will provide your API key before you begin. Production Base URL: https://api.dashboard.valuez.ai All endpoints require the x-api-key header. See API Authentication for setup details.

1. Text-to-Text Agent Chat

Send a text question to an AI agent and receive an answer grounded in its knowledge base and instructions.

Method: POST
Endpoint: /api/v1/ttt
Credits: Deducts TTT_API credits per token usage.

Request Body

{
  "question": "What are your business operating hours?",
  "sessionUUID": "c8a4b650-32b1-4c12-9844-313264fa5e2a",
  "variables": {
    "userName": "John Doe",
    "callDirection": "inbound"
  }
}

Field	Type	Required	Description
`question`	string	Yes	The user question or message text.
`sessionUUID`	string (UUID)	No	Session identifier. Pass the same UUID across turns to maintain conversation memory.
`variables`	object	No	Custom context variables injected into the agent prompt (e.g. `userName`, `contactName`).

Response

{
  "statusCode": 200,
  "answer": "Our offices are open Monday to Friday, from 9:00 AM to 6:00 PM IST.",
  "sessionUUID": "c8a4b650-32b1-4c12-9844-313264fa5e2a",
  "detectedLanguage": "english",
  "tokenUsage": {
    "promptTokens": 142,
    "completionTokens": 28,
    "totalTokens": 170
  }
}

Code Examples

curl -X POST "https://api.dashboard.valuez.ai/api/v1/ttt" \
  -H "x-api-key: $VALUEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are your business operating hours?",
    "sessionUUID": "c8a4b650-32b1-4c12-9844-313264fa5e2a"
  }'

const response = await fetch("https://api.dashboard.valuez.ai/api/v1/ttt", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VALUEZ_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    question: "What are your business operating hours?",
    sessionUUID: "c8a4b650-32b1-4c12-9844-313264fa5e2a"
  })
});
const data = await response.json();
console.log(data.answer);

import os, requests

response = requests.post(
    "https://api.dashboard.valuez.ai/api/v1/ttt",
    headers={"x-api-key": os.getenv("VALUEZ_API_KEY")},
    json={
        "question": "What are your business operating hours?",
        "sessionUUID": "c8a4b650-32b1-4c12-9844-313264fa5e2a"
    }
)
print(response.json()["answer"])

2. Text-to-Speech (TTS)

Synthesize speech audio from text using the workspace’s configured TTS provider and voice profile.

Method: POST
Endpoint: /api/v1/tts/external
Credits: Deducts TTS_API credits based on character count.
Output: Returns a binary audio/wav stream.

Request Body

{
  "text": "Hello, thank you for reaching out to Valuez AI support.",
  "language": "english",
  "pace": 1.0
}

Field	Type	Required	Description
`text`	string	Yes	Text to synthesize (max 5,000 characters).
`language`	string	Yes	`english`, `hindi`, or `marathi`.
`pace`	number	No	Speaking pace between `0.7` and `1.2`. Defaults to `1.0`.

Code Examples

curl -X POST "https://api.dashboard.valuez.ai/api/v1/tts/external" \
  -H "x-api-key: $VALUEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Welcome to Valuez AI", "language": "english", "pace": 1.0}' \
  --output response.wav

const response = await fetch("https://api.dashboard.valuez.ai/api/v1/tts/external", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VALUEZ_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ text: "Welcome to Valuez AI", language: "english", pace: 1.0 })
});
const audioBuffer = await response.arrayBuffer();
// Save or stream the WAV binary as needed

import os, requests

response = requests.post(
    "https://api.dashboard.valuez.ai/api/v1/tts/external",
    headers={"x-api-key": os.getenv("VALUEZ_API_KEY")},
    json={"text": "Welcome to Valuez AI", "language": "english", "pace": 1.0}
)
with open("response.wav", "wb") as f:
    f.write(response.content)

3. Speech-to-Text (STT)

Transcribe a recorded voice audio file to text.

Method: POST
Endpoint: /api/v1/stt/external
Content-Type: multipart/form-data
Credits: Deducts STT_API credits based on audio duration.

Request Fields

Field	Type	Required	Description
`audioFile`	file	Yes	Audio file in WAV, MP3, or PCM format.
`language`	string	Yes	Expected language: `english`, `hindi`, or `marathi`.
`durationSeconds`	number	No	Optional audio duration hint in seconds.

Response

{
  "statusCode": 200,
  "transcription": "I would like to check the status of my order."
}

Code Examples

curl -X POST "https://api.dashboard.valuez.ai/api/v1/stt/external" \
  -H "x-api-key: $VALUEZ_API_KEY" \
  -F "audioFile=@sample_audio.wav" \
  -F "language=english"

const FormData = require("form-data");
const fs = require("fs");

const form = new FormData();
form.append("audioFile", fs.createReadStream("sample_audio.wav"));
form.append("language", "english");

const response = await fetch("https://api.dashboard.valuez.ai/api/v1/stt/external", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VALUEZ_API_KEY,
    ...form.getHeaders()
  },
  body: form
});
const data = await response.json();
console.log(data.transcription);

import os, requests

with open("sample_audio.wav", "rb") as audio:
    response = requests.post(
        "https://api.dashboard.valuez.ai/api/v1/stt/external",
        headers={"x-api-key": os.getenv("VALUEZ_API_KEY")},
        files={"audioFile": audio},
        data={"language": "english"}
    )
print(response.json()["transcription"])

4. Conversational Agent Chat

Unified endpoint supporting text or audio input, RAG knowledge retrieval, and stateful multi-turn conversation history.

Method: POST
Endpoint: /api/v1/external/chat
Content-Type: application/json (or multipart/form-data when uploading audioFile)

Request Body

{
  "question": "Can I upgrade my monthly subscription?",
  "sessionUUID": "b7391a1e-84a1-432a-bc91-23214a1a3b5c",
  "connectionType": "ttt",
  "responseMode": "sync"
}

Fetch Session History

Retrieve the full multi-turn transcript for a session:

curl -X GET \
  "https://api.dashboard.valuez.ai/api/v1/external/history?sessionUUID=b7391a1e-84a1-432a-bc91-23214a1a3b5c" \
  -H "x-api-key: $VALUEZ_API_KEY"

const response = await fetch(
  "https://api.dashboard.valuez.ai/api/v1/external/history?sessionUUID=b7391a1e-84a1-432a-bc91-23214a1a3b5c",
  { headers: { "x-api-key": process.env.VALUEZ_API_KEY } }
);
const data = await response.json();
console.log(data.chatHistory);

import os, requests

response = requests.get(
    "https://api.dashboard.valuez.ai/api/v1/external/history",
    params={"sessionUUID": "b7391a1e-84a1-432a-bc91-23214a1a3b5c"},
    headers={"x-api-key": os.getenv("VALUEZ_API_KEY")}
)
print(response.json()["chatHistory"])

Response

{
  "statusCode": 200,
  "sessionUUID": "b7391a1e-84a1-432a-bc91-23214a1a3b5c",
  "AgentID": 17,
  "createdAt": "2026-10-13T10:00:00.000Z",
  "chatHistory": [
    { "sender": "user", "text": "Can I upgrade my monthly subscription?" },
    { "sender": "assistant", "text": "Yes, you can upgrade your plan anytime from Settings & Billing." }
  ]
}

5. Real-Time WebSockets

For low-latency streaming, Valuez exposes WebSocket endpoints for bidirectional voice and embedded widget interactions:

WebSocket Path	Purpose	Authentication
`/ws/sts`	Real-time Speech-to-Speech session	API Key / Session token
`/ws/widgetchat`	Live chat and voice for embedded website widgets	Widget Token / Domain validation
`/ws/transcribe`	Streaming audio transcription	Session token

Error Reference

Status Code	Meaning	Resolution
`401 Unauthorized`	`x-api-key` header missing	Add the `x-api-key` header. Contact your admin if you don’t have a key.
`403 Forbidden`	Feature locked or credits exceeded	Confirm your key has the correct scopes and that workspace credits are available.
`400 Bad Request`	Validation failure	Check that all required fields are present (`question`, `text`, `audioFile`, `language`).
`429 Too Many Requests`	Rate limit reached	Slow request cadence or ask your admin to request a higher rate limit.
`503 Service Unavailable`	Speech provider degraded	Retry with exponential backoff.

API Logs

Monitor request logs and inspect execution details.

Agents & Knowledge

Configure the AI agents that power these endpoints.

Getting started

Dashboards

Campaigns

Teams

Agents and knowledge

Reference

Speech & Agent Integration APIs

1. Text-to-Text Agent Chat

Request Body

Response

Code Examples

2. Text-to-Speech (TTS)

Request Body

Code Examples

3. Speech-to-Text (STT)

Request Fields

Response

Code Examples

4. Conversational Agent Chat

Request Body

Fetch Session History

Response

5. Real-Time WebSockets

Error Reference

API Logs

Agents & Knowledge

​1. Text-to-Text Agent Chat

​Request Body

​Response

​Code Examples

​2. Text-to-Speech (TTS)

​Request Body

​Code Examples

​3. Speech-to-Text (STT)

​Request Fields

​Response

​Code Examples

​4. Conversational Agent Chat

​Request Body

​Fetch Session History

​Response

​5. Real-Time WebSockets

​Error Reference

API Logs

Agents & Knowledge

1. Text-to-Text Agent Chat

Request Body

Response

Code Examples

2. Text-to-Speech (TTS)

Request Body

Code Examples

3. Speech-to-Text (STT)

Request Fields

Response

Code Examples

4. Conversational Agent Chat

Request Body

Fetch Session History

Response

5. Real-Time WebSockets

Error Reference