Reecall
AI Assistants

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.

ComponentPurpose
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
VoiceDefines 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:

JSONCode
[ { "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

Code
GET /data_next/ai/TTS/

Response:

JSONCode
[ { "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

Code
GET /data_next/ai/STT/

Response:

JSONCode
[ { "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:

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

The response's voices array:

JSONCode
[ { "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

JSONCode
{ "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/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:

JSONCode
{ "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:

JSONCode
{ "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:

JSONCode
{ "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
JSONCode
{ "temperature": 0.3 }

First message

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

JSONCode
{ "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.


What's next

Last modified on