Skip to main content

​
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"
  }'
Response: 
{
  "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
  }'
Response: 
{
  "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."
  }'
Response: 
{
  "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"
  }'
Response: 
{
  "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

Join the Meeting

Use the daily_meeting_url and room_token from the response to join the meeting room using Daily.co SDK or embed.

Get Analysis

After the meeting ends, retrieve the analysis to see performance insights and feedback.

Get Transcripts

Access sentence-level transcripts of the conversation for detailed review.

Get Recordings

Retrieve meeting recordings for playback and review.

​
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.