# Creating an Assistant

Create a voice Assistant with separate language, speech-to-text, and text-to-speech models using the REST API.

Use a project-scoped API key for these examples. With an organization-scoped key, include `projectId` in the Assistant creation payload. The model names, IDs, and timestamps shown below are illustrative; use values returned by your model catalog.

## Understanding the Assistant architecture

A pipeline Assistant uses these components to process speech. To use a single speech-to-speech model instead, follow the STS instructions in the [Quickstart](/docs/quickstart).

| Component                | Purpose                                                                        |
| ------------------------ | ------------------------------------------------------------------------------ |
| **LLM** (Language Model) | Powers the AI reasoning and generates responses                                |
| **TTS** (Text-to-Speech) | Converts the Assistant's text responses into spoken audio |
| **STT** (Speech-to-Text) | Transcribes user speech input into text                                        |
| **Voice**                | Defines the assistant's speaking voice characteristics                         |

***

## Gathering required dependencies

Get a valid `llmId`, `sttId`, `ttsId`, and `voiceId` from the model catalog before creating the Assistant.

Reecall's API provides model IDs and metadata. Send `Authorization: Bearer <your-api-key>` on each request:

* `llmId`: `GET /data_next/ai/LLM/`
* `sttId`: `GET /data_next/ai/STT/`
* `ttsId`: `GET /data_next/ai/TTS/`
* `voiceId`: choose a voice from the `voices` array returned by your selected TTS model

### Fetch available LLM models

```http
GET /data_next/ai/LLM/
```

**Response:**

```json
[
  {
    "id": "4bc352dd-556b-4b59-9740-82b4bd325b3a",
    "name": "Mistral Medium 3.5",
    "description": "Mistral's frontier-class multimodal model optimized for agentic and coding use cases.",
    "modelName": "mistral-medium-3-5",
    "provider": "Mistral",
    "disabled": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

### Fetch available TTS models

```http
GET /data_next/ai/TTS/
```

**Response:**

```json
[
  {
    "id": "49fa41bb-c1ed-483c-8115-42bda64f8310",
    "name": "ElevenLabs Flash v2.5",
    "description": "Fast, high-quality multilingual TTS",
    "modelName": "eleven_flash_v2_5",
    "provider": "ElevenLabs",
    "disabled": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

### Fetch available STT models

```http
GET /data_next/ai/STT/
```

**Response:**

```json
[
  {
    "id": "600592b5-54d1-4bc4-a8ab-770c376b235f",
    "name": "Voxtral Mini Transcribe Realtime",
    "description": "Mistral's realtime speech-to-text model optimized for low-latency transcription in voice agent workloads.",
    "modelName": "voxtral-mini-transcribe-realtime-2602",
    "provider": "Mistral",
    "disabled": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

### Fetch available voices

Read the `voices` array returned by your selected TTS model to get compatible voices:

```http
GET /data_next/ai/TTS/49fa41bb-c1ed-483c-8115-42bda64f8310
Authorization: Bearer <your-api-key>
```

**The response's `voices` array:**

```json
[
  {
    "id": "491d5301-d279-49c3-963f-0134b2eb3cb2",
    "name": "Eryn",
    "voiceId": "kdnRe2koJdOK4Ovxn2DI",
    "description": "Friendly female voice",
    "language": "en-US",
    "gender": "female",
    "disabled": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

***

## Creating the Assistant

### Constructing the request payload

```json
{
  "name": "Customer Support Assistant",
  "description": "Handles customer inquiries and support requests",
  "instructions": "You are a helpful customer support assistant. Be polite, professional, and concise. Help users with their questions about our products and services.",
  "language": "en-US",
  "llmId": "4bc352dd-556b-4b59-9740-82b4bd325b3a",
  "ttsId": "49fa41bb-c1ed-483c-8115-42bda64f8310",
  "sttId": "600592b5-54d1-4bc4-a8ab-770c376b235f",
  "voiceId": "491d5301-d279-49c3-963f-0134b2eb3cb2",
  "firstMessage": "Hello! How can I help you today?",
  "timezone": "Europe/Paris",
  "temperature": 0.3
}
```

### Making the POST request

```http
POST /data_next/conversational/assistants/
Content-Type: application/json
Authorization: Bearer <your-api-token>

{
  "name": "Customer Support Assistant",
  "instructions": "You are a helpful customer support assistant...",
  "language": "en-US",
  "llmId": "4bc352dd-556b-4b59-9740-82b4bd325b3a",
  "ttsId": "49fa41bb-c1ed-483c-8115-42bda64f8310",
  "sttId": "600592b5-54d1-4bc4-a8ab-770c376b235f",
  "voiceId": "491d5301-d279-49c3-963f-0134b2eb3cb2",
  "firstMessage": "Hello! How can I help you today?",
  "timezone": "Europe/Paris",
  "temperature": 0.3
}
```

**Response:**

```json
{
  "id": "f73b3d99-44f4-4fbc-9e23-17a310202b07",
  "name": "Customer Support Assistant",
  "description": null,
  "instructions": "You are a helpful customer support assistant...",
  "language": "en-US",
  "llmId": "4bc352dd-556b-4b59-9740-82b4bd325b3a",
  "ttsId": "49fa41bb-c1ed-483c-8115-42bda64f8310",
  "sttId": "600592b5-54d1-4bc4-a8ab-770c376b235f",
  "voiceId": "491d5301-d279-49c3-963f-0134b2eb3cb2",
  "firstMessage": "Hello! How can I help you today?",
  "timezone": "Europe/Paris",
  "temperature": 0.3,
  "organizationId": "6b72e68d-e596-4e11-a190-bedbded40cc2",
  "projectId": "7472cba2-6037-488f-b5aa-53b1c39fe450",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

***

## Configuring Assistant properties

The JSON examples in this section are field fragments for an Assistant creation or update payload.

### Instructions (system prompt)

The `instructions` field defines the Assistant's personality, behavior, and capabilities. Write clear, specific instructions:

```json
{
  "instructions": "You are a technical support specialist for a software company. Your role is to:\n- Help users troubleshoot software issues\n- Guide them through installation processes\n- Escalate complex issues to human support when needed\n\nAlways ask clarifying questions before providing solutions. Be patient and explain technical concepts in simple terms."
}
```

### Language and timezone

Set the `language` to match your target audience and provide the required `timezone` for time-aware responses:

```json
{
  "language": "fr-FR",
  "timezone": "Europe/Paris"
}
```

### Temperature

The `temperature` parameter controls response variability:

* **Lower values (0.1-0.3)**: More "deterministic", focused responses
* **Medium values (0.5-0.7)**: Balanced creativity and consistency
* **Higher values (0.8-1.0)**: More creative, varied responses

```json
{
  "temperature": 0.3
}
```

### First message

The `firstMessage` is the greeting the Assistant uses to initiate conversations:

```json
{
  "firstMessage": "Hello ! I'm your virtual assistant, how can I help you today?"
}
```

:::info{title="Note"}

If you don't set `firstMessage`, the Assistant does not send an opening greeting. It listens for user input, with answering machine detection first if that feature is enabled.

:::

<br />

## What's next

- [Tools and MCPs](/docs/tools-and-mcps)
