E
Voice Tutorby Evelyn Learning

Getting Started

Embed a working AI Voice Tutor session in your platform in three steps.

1. Get Your API Keys

After your sandbox request is approved, you'll receive three credentials:

  • API Key — for server-to-server API calls (module uploads, session queries)
  • API Secret — for signing JWT session tokens
  • Webhook Secret — for verifying incoming webhook signatures

!Keep secrets server-side

Never expose your API Secret or Webhook Secret in client-side code. JWT signing and webhook verification must happen on your backend.

2. Generate a Session Token

When a student starts a tutoring session, your backend generates a signed JWT containing the session configuration:

Node.js example
import jwt from 'jsonwebtoken';

const token = jwt.sign({
  partner_id: 'your-partner-id',
  student_id: 'stu_abc123',
  student_name: 'Ahmed',
  subject: 'math',
  level: '11-12',
  engine: 'standard',        // 'standard' or 'premium'
  locale: 'ar-DZ',
  session_goal: 'test-prep',
  branding: {
    primary_color: '#1E40AF',
    product_name: 'BAC Tutor'
  }
}, process.env.EVELYN_API_SECRET, { expiresIn: '2h' });
Python example
import jwt, time

token = jwt.encode({
    "partner_id": "your-partner-id",
    "student_id": "stu_abc123",
    "student_name": "Ahmed",
    "subject": "math",
    "level": "11-12",
    "engine": "standard",
    "locale": "ar-DZ",
    "session_goal": "test-prep",
    "branding": {
        "primary_color": "#1E40AF",
        "product_name": "BAC Tutor"
    },
    "exp": int(time.time()) + 7200
}, os.environ["EVELYN_API_SECRET"], algorithm="HS256")

See Embed Configuration for all available parameters.

3. Embed the Tutor

Load the tutor in your frontend with a single iframe. Pass the JWT as a query parameter:

HTML
<iframe
  src="https://tutor.evelynlearning.com/embed?token=YOUR_JWT_TOKEN"
  width="100%"
  height="700"
  allow="microphone; camera"
  frameborder="0"
></iframe>

iMicrophone permission

The iframe requires the allow="microphone" attribute for voice mode. Without it, the browser will block audio input and the tutor will fall back to text-only mode.

4. Handle Webhooks

Register a webhook endpoint to receive session events. Configure it via the API:

Register webhook
curl -X POST https://api.evelynlearning.com/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/evelyn",
    "events": ["session.ended", "usage.summary", "student.milestone"]
  }'

See Webhooks for all 15 event types and payload schemas, and Authentication for signature verification.

Next Steps