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.
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
Code
GET /data_next/ai/LLM/
Response:
Code
[ { "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" }]
{ "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
Code
POST /data_next/conversational/assistants/Content-Type: application/jsonAuthorization: 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:
Code
{ "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:
Code
{ "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:
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
Code
{ "temperature": 0.3}
First message
The firstMessage is the greeting the Assistant uses to initiate conversations:
Code
{ "firstMessage": "Hello ! I'm your virtual assistant, how can I help you today?"}
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.