> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valuez.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech & Agent Integration APIs

> Integrate TTT, TTS, STT, and conversational agents into your application

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](/dev-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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

***

## 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

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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
  ```

  ```javascript Node.js theme={null}
  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
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

***

## 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

```json theme={null}
{
  "statusCode": 200,
  "transcription": "I would like to check the status of my order."
}
```

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

***

## 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

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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. |

<CardGroup cols={2}>
  <Card title="API Logs" icon="clock-rotate-left" href="/api-logs">
    Monitor request logs and inspect execution details.
  </Card>

  <Card title="Agents & Knowledge" icon="brain" href="/dev-agents-knowledge">
    Configure the AI agents that power these endpoints.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.