Reecall
Getting Started

Quickstart

Create a speech-to-speech Assistant, connect it through a WebRTC Channel, and make a browser call. After the call, read its transcript from the Exchange API.

Create your first Assistant with an AI agent

Use the Reecall Platform MCP server to let an AI agent guide you through setup. Follow the MCP connection instructions to connect the Platform server to your AI client, then give your agent this prompt:

Code
Use the Reecall MCP server to guide me through creating my first voice assistant. Explain each step and help me test the Assistant from my browser.

API tutorial prerequisites

  • A Reecall account with a Project and a project-scoped API key. See Authentication to create the key.
  • An HTTP client on your backend or workstation to send requests. The final query uses curl from a terminal.
  • Node.js and npm for the browser example. Use a Node.js version supported by Vite.
  • A browser with a microphone and speakers or headphones.

All request paths below are relative to your Reecall deployment host. They include the service prefix, such as /data_next or /calls. The Data API server URL in the API reference already includes /data_next; do not add that prefix twice.

Replace every placeholder with your own value. Response examples are excerpts, not the complete response schemas.

Use the API key only on your backend

Send Reecall API requests from your backend or workstation. Pass only the returned LiveKit wsUrl and connection token to the browser. Do not put your Reecall API key in the browser example.

Step 1: choose a model and voice

List the available speech-to-speech models:

Code
GET /data_next/ai/STS/ Authorization: Bearer {your-api-key}

Choose an enabled model with a voice you want to use. Save the model's id as stsId and one id from its voices array as voiceId. Use a voice from the selected model.

This tutorial uses native STS, so you do not need separate STT, LLM, or TTS model IDs.

Step 2: create an Assistant

Send the selected model and voice IDs with the Assistant's instructions:

Code
POST /data_next/conversational/assistants/ Authorization: Bearer {your-api-key} Content-Type: application/json { "name": "Quickstart Assistant", "instructions": "You are a friendly support assistant. Ask how you can help and keep your answers concise. If you do not know an answer, say so.", "language": "en-US", "timezone": "Europe/Paris", "firstMessage": "Hello! How can I help you today?", "stsId": "{your-sts-id}", "voiceId": "{your-voice-id}" }
JSONCode
{ "id": "{your-assistant-id}" }

Save the returned id as assistantId. Your project-scoped key supplies the Project and Organization automatically.

Step 3: create a WebRTC Channel

Create a Channel that routes browser calls to this Assistant:

Code
POST /data_next/conversational/channels/ Authorization: Bearer {your-api-key} Content-Type: application/json { "name": "Quickstart WebRTC", "type": "WEBRTC", "assistantId": "{your-assistant-id}" }
JSONCode
{ "id": "{your-channel-id}" }

Save the returned id as channelId. Reuse this Channel for later calls to the same Assistant.

Step 4: request connection credentials

Request a connection token from the Calls API using the Channel ID:

Code
POST /calls/{your-channel-id} Authorization: Bearer {your-api-key}
JSONCode
{ "wsUrl": "wss://your-livekit-host", "token": "{your-livekit-token}" }

Save both values. The token grants access to the call's LiveKit room and has a one-hour lifetime. Request new credentials for each new conversation.

Step 5: connect and talk

Create a local browser project. These commands use Vite's manual setup to resolve the LiveKit SDK's npm import:

TerminalCode
mkdir reecall-quickstart cd reecall-quickstart npm init -y npm install livekit-client npm install --save-dev vite

Create index.html in the project directory:

Code
<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Reecall quickstart</title> </head> <body> <button id="connect" type="button">Connect</button> <button id="disconnect" type="button" disabled>End call</button> <p id="status" role="status">Ready to connect.</p> <script type="module" src="/main.js"></script> </body> </html>

Create main.js alongside it. Replace wsUrl and token with the values from Step 4:

JavascriptCode
import { Room, RoomEvent, Track } from "livekit-client"; const wsUrl = "wss://your-livekit-host"; const token = "your-livekit-token"; const room = new Room(); const connectButton = document.querySelector("#connect"); const disconnectButton = document.querySelector("#disconnect"); const status = document.querySelector("#status"); room.on(RoomEvent.TrackSubscribed, (track) => { if (track.kind === Track.Kind.Audio) { document.body.appendChild(track.attach()); } }); room.on(RoomEvent.TrackUnsubscribed, (track) => { track.detach().forEach((element) => element.remove()); }); room.on(RoomEvent.Disconnected, () => { connectButton.disabled = false; disconnectButton.disabled = true; status.textContent = "Disconnected."; }); connectButton.addEventListener("click", async () => { connectButton.disabled = true; status.textContent = "Connecting..."; try { await room.startAudio(); await room.connect(wsUrl, token); await room.localParticipant.setMicrophoneEnabled(true); disconnectButton.disabled = false; status.textContent = "Connected. Your microphone is live."; } catch (error) { await room.disconnect(); connectButton.disabled = false; status.textContent = "Connection failed. Check the browser console."; console.error(error); } }); disconnectButton.addEventListener("click", async () => { await room.disconnect(); });

Start the local app:

TerminalCode
npx vite

Open the localhost URL printed in the terminal. Click Connect, allow microphone access, and speak to the Assistant. You should hear its greeting and responses. Click End call when you finish.

This example starts audio playback from a button click and attaches the Assistant's subscribed audio tracks to the page. See LiveKit's JavaScript SDK for the client API.

Keep this example local. In a deployed application, have your backend authorize connection requests and return fresh credentials instead of hardcoding them in JavaScript. Serve the browser app over HTTPS when hosting it outside localhost.

Step 6: read the conversation record

After ending the call, query the Data API from your backend or terminal. Replace the deployment host, API key, and Assistant ID in this command:

TerminalCode
curl --get 'https://your-deployment-host/data_next/conversational/exchanges' \ --header 'Authorization: Bearer {your-api-key}' \ --data-urlencode 'where={"assistantId":"{your-assistant-id}"}' \ --data-urlencode 'orderBy={"createdAt":"desc"}' \ --data-urlencode 'limit=1'

The response is an array ordered with the newest Exchange first. A completed conversation includes fields such as:

JSONCode
[ { "id": "{your-exchange-id}", "assistantId": "{your-assistant-id}", "status": "completed", "duration": 32 } ]

Read messages in the full response for the transcript. If the Exchange still has status: "inProgress", wait for final processing and query again. A recording and extracted data depend on additional configuration and are not required for this tutorial.

Troubleshooting

ProblemWhat to check
An API request returns 403Use the API key's token, check it has not been revoked, and confirm its scope. See Authentication.
Channel creation reports a duplicateAn Assistant can have only one WebRTC Channel. Reuse the existing Channel instead of creating another.
The browser cannot connectUse the Channel's ID in Step 4 and copy both returned credentials. Request new credentials if the token has expired.
The microphone does not workAllow microphone access for the localhost app and check your selected input device.
You cannot hear the AssistantCheck your output device, browser audio permissions, and whether the STS model and voice are compatible. Start the connection with the Connect button.
The Exchange query returns an empty arrayConfirm that you connected and started a conversation, then allow time for the record to appear. Use the same Project and Assistant as in the earlier steps.

Next steps

Last modified on