# 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](/#connect-to-reecall-mcp-servers) to connect the Platform server to your AI client, then give your agent this prompt:

```text title="Prompt for your AI agent"
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](/docs/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](https://vite.dev/guide/).
- 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.

:::warning{title="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:

```http title="List STS models"
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:

```http title="Create an Assistant"
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}"
}
```

```json title="Response excerpt"
{
  "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:

```http title="Create a WebRTC Channel"
POST /data_next/conversational/channels/
Authorization: Bearer {your-api-key}
Content-Type: application/json

{
  "name": "Quickstart WebRTC",
  "type": "WEBRTC",
  "assistantId": "{your-assistant-id}"
}
```

```json title="Response excerpt"
{
  "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:

```http title="Request a WebRTC connection token"
POST /calls/{your-channel-id}
Authorization: Bearer {your-api-key}
```

```json title="Response"
{
  "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](https://vite.dev/guide/#manual-installation) to resolve the LiveKit SDK's npm import:

```bash
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:

```html title="index.html"
<!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:

```javascript title="main.js"
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:

```bash
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](https://docs.livekit.io/reference/client-sdk-js/) 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:

```bash
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:

```json title="Response excerpt"
[
  {
    "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

| Problem | What to check |
| --- | --- |
| An API request returns `403` | Use the API key's token, check it has not been revoked, and confirm its scope. See [Authentication](/docs/authentication#troubleshoot-access-errors). |
| Channel creation reports a duplicate | An Assistant can have only one WebRTC Channel. Reuse the existing Channel instead of creating another. |
| The browser cannot connect | Use the Channel's ID in Step 4 and copy both returned credentials. Request new credentials if the token has expired. |
| The microphone does not work | Allow microphone access for the localhost app and check your selected input device. |
| You cannot hear the Assistant | Check 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 array | Confirm 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

- [Assistants & Models](/docs/assistants-and-models) explains the alternatives to native STS. The [Assistant creation guide](/docs/creating-an-assistant-with-the-api) shows the three-model configuration.
- [SIP Channel](/docs/sip-channel) connects an Assistant to your phone system.
- [Tools and MCPs](/docs/tools-and-mcps) adds actions during a conversation.
- [Post-conversation processing](/docs/post-conversation) sends completed results to your other systems.
