Quickstart Guide
This guide will walk you through creating a persona, adding it to a scenario, and calling a meeting. Let’s build your first AI conversation in three simple steps.
Prerequisites
- Authentication token (JWT token from OAuth login or API secret)
- HTTP client (curl, Postman, or your preferred tool)
Getting Your Authentication Token
You have two options for authentication:
Option 1: JWT Token (from OAuth login)
- Log in through OAuth (Google, Microsoft, LinkedIn)
- Get your JWT token from the authentication response
Option 2: API Secret (recommended for automation)
- First, authenticate with a JWT token
- Create an API secret (see below)
- Use the API secret for all subsequent requests
Creating an API Secret
If you prefer using API secrets (they never expire), create one first:
curl -X POST https://api.waterrai.com/api-secrets \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My API Key"
}'
{
"status": "success",
"data": {
"id": 1,
"name": "My API Key",
"secret": "wai_abc123def456...",
"warning": "Save this secret now. You won't be able to see it again!"
}
}
Important: Save the secret value immediately - it’s only shown once! Use this secret instead of YOUR_JWT_TOKEN in the examples below.
Step 1: Create a Persona
A persona defines the AI character’s personality, background, and voice. Let’s create one:
curl -X POST https://api.waterrai.com/personas \
-H "Authorization: Bearer YOUR_API_SECRET_OR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Sarah Chen",
"job_title": "Senior Product Manager",
"demeanor": "friendly",
"background": "Experienced product manager with 10 years in tech, specializing in user experience and product strategy.",
"voice_id": 1
}'
{
"status": "success",
"data": {
"id": 123,
"name": "Sarah Chen",
"job_title": "Senior Product Manager",
"demeanor": "friendly",
"background": "Experienced product manager with 10 years in tech...",
"voice_id": 1,
"created_at": "2024-01-15T10:30:00Z"
}
}
Save the id from the response - you’ll need it for the next step!
Step 2: Create a Scenario
Now let’s create a scenario using the persona we just created. A scenario defines the conversation context and goals.
Organization ID: The org_id is automatically determined from your authenticated account, so you don’t need to provide it in the request.
curl -X POST https://api.waterrai.com/scenarios \
-H "Authorization: Bearer YOUR_API_SECRET_OR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Manager Interview Practice",
"description": "Practice interview scenarios for product management roles",
"type": "interview",
"persona_id": 123,
"prompt": "You are conducting a mock interview for a product manager position. Ask about product strategy, user research, and prioritization frameworks."
}'
{
"status": "success",
"data": {
"id": 456,
"name": "Product Manager Interview Practice",
"description": "Practice interview scenarios for product management roles",
"type": "interview",
"persona_id": 123,
"scenario_link": "pm-interview-practice",
"created_at": "2024-01-15T10:35:00Z"
}
}
Save the scenario id - you’ll use it to create a meeting!
Step 3: Create a Meeting from Scenario
Now let’s create a meeting using the scenario. This will give you a meeting room URL and token to join the conversation.
curl -X POST https://api.waterrai.com/meetings \
-H "Authorization: Bearer YOUR_API_SECRET_OR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"person_name": "John Doe",
"scenario_id": 456,
"meeting_type": "regular"
}'
{
"success": true,
"data": {
"id": 789,
"daily_meeting_id": "abc123",
"daily_meeting_url": "https://waterrai.daily.co/abc123",
"room_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"person_name": "John Doe",
"scenario_id": 456,
"status": "created",
"created_at": "2024-01-15T10:40:00Z"
}
}
Next Steps
Complete Example
Here’s a complete example in JavaScript that ties everything together:
const API_BASE = 'https://api.waterrai.com';
const API_TOKEN = 'YOUR_API_SECRET_OR_JWT_TOKEN'; // Use API secret or JWT token
async function createCompleteMeeting() {
// Step 1: Create Persona
const personaResponse = await fetch(`${API_BASE}/personas`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: "Sarah Chen",
job_title: "Senior Product Manager",
demeanor: "friendly",
background: "Experienced product manager with 10 years in tech...",
voice_id: 1
})
});
const persona = await personaResponse.json();
const personaId = persona.data.id;
// Step 2: Create Scenario
const scenarioResponse = await fetch(`${API_BASE}/scenarios`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: "Product Manager Interview Practice",
description: "Practice interview scenarios",
type: "interview",
persona_id: personaId,
prompt: "You are conducting a mock interview..."
})
});
const scenario = await scenarioResponse.json();
const scenarioId = scenario.data.id;
// Step 3: Create Meeting
const meetingResponse = await fetch(`${API_BASE}/meetings`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
person_name: "John Doe",
scenario_id: scenarioId,
meeting_type: "regular"
})
});
const meeting = await meetingResponse.json();
console.log('Meeting created:', meeting.data);
return meeting.data;
}
// Run it
createCompleteMeeting();
Pro Tip: After the meeting ends, use the meeting ID to fetch analysis, recordings, and transcripts. Check out the API Reference for all available endpoints. 
