Skip to main content
The Node.js SDK is continually evolving, with new endpoints being added regularly. Stay tuned for updates!

​
Overview

The Roark Node.js SDK provides a streamlined way to interact with the Roark API. This guide covers the two most common workflows: uploading calls and running metrics, and executing simulation run plans.

​
Prerequisites

Before you begin, ensure you have:

​
Installation

Choose your preferred package manager: 
npm install @roarkanalytics/sdk

​
Initialize the Client

import Roark from '@roarkanalytics/sdk'

const client = new Roark({
  bearerToken: process.env.ROARK_API_BEARER_TOKEN,
})
Set ROARK_API_BEARER_TOKEN in your environment, or replace with your actual API key from Roark.

​
Upload a Call and Run Metrics

Upload a call recording, then run metric definitions against it using a collection job.
1

Upload a Call

const call = await client.call.create({
  recordingUrl: 'https://example.com/recording.mp3',
  startedAt: '2024-01-15T10:00:00Z',
  interfaceType: 'PHONE',
  callDirection: 'INBOUND',
  agent: {
    name: 'Support Agent',
    customId: 'agent-123',
  },
  customer: {
    phoneNumberE164: '+15551234567',
  },
  // Optional: custom properties for filtering
  properties: {
    department: 'sales',
    campaignId: 'summer-2024',
  },
})
2

Get Metric Definitions

List available metric definitions to choose which ones to run:
const definitions = await client.metric.listDefinitions()

// Find the metrics you want to collect
const taskCompletion = definitions.data.find(
  (m) => m.metricId === 'task_completion'
)
const satisfaction = definitions.data.find(
  (m) => m.metricId === 'customer_satisfaction'
)
3

Create a Metric Collection Job

Run the selected metrics against your uploaded call:
const job = await client.metricCollectionJob.create({
  callIds: [call.data.id],
  metrics: [
    { id: taskCompletion.id },
    { id: satisfaction.id },
  ],
})
4

Poll for Completion

let status = 'PENDING'
while (status !== 'COMPLETED' && status !== 'FAILED') {
  const result = await client.metricCollectionJob.getByID(job.data.id)
  status = result.data.status
  console.log(`Progress: ${result.data.completedItems}/${result.data.totalItems}`)
  if (status !== 'COMPLETED' && status !== 'FAILED') {
    await new Promise((r) => setTimeout(r, 2000))
  }
}
5

Fetch Results

const metrics = await client.call.listMetrics(call.data.id)
console.log(metrics.data)
If you have metric policies configured, metrics are collected automatically when calls are uploaded — no collection job needed.

​
Run a Simulation Run Plan

Create and execute a simulation run plan to systematically test your voice AI agent.
1

Create the Run Plan

Define scenarios, personas, agent endpoints, and metrics to include:
const plan = await client.simulationRunPlan.create({
  name: 'Production Regression Suite',
  direction: 'INBOUND',
  maxSimulationDurationSeconds: 300,
  scenarios: [
    { id: 'scenario-uuid-1' },
    { id: 'scenario-uuid-2' },
  ],
  personas: [
    { id: 'persona-uuid-1' },
    { id: 'persona-uuid-2' },
  ],
  agentEndpoints: [
    { id: 'agent-endpoint-uuid' },
  ],
  metrics: [
    { id: 'metric-definition-uuid-1' },
    { id: 'metric-definition-uuid-2' },
  ],
  iterationCount: 1,
  maxConcurrentJobs: 10,
  autoRun: true, // Start immediately after creation
})

// plan.data.runPlanJob contains the job if autoRun is true
2

Or Start an Existing Plan

If you already have a run plan, start a new job for it:
const job = await client.simulationRunPlanJob.start('plan-uuid')
3

Monitor Progress

const jobResult = await client.simulationRunPlanJob.getByID(
  job.data.simulationRunPlanJobId
)

console.log(`Status: ${jobResult.data.status}`)
console.log(`Jobs: ${jobResult.data.simulationJobs.length}`)
4

View Results

Results including metric evaluations are available in the Roark dashboard, or you can fetch metrics for individual simulation calls via the API:
// Get metrics for a specific simulation call
const metrics = await client.call.listMetrics('simulation-call-id')

​
Additional Examples

Track function calls and tool usage during the conversation:
const call = await client.call.create({
  recordingUrl: 'https://example.com/recording.mp3',
  startedAt: '2024-01-15T10:00:00Z',
  interfaceType: 'PHONE',
  callDirection: 'INBOUND',
  agent: {
    name: 'Booking Agent',
    customId: 'booking-agent-1',
  },
  customer: {
    phoneNumberE164: '+15551234567',
  },
  toolInvocations: [
    {
      name: 'checkAvailability',
      description: 'Check available appointment slots',
      startOffsetMs: 5000,
      endOffsetMs: 5500,
      parameters: {
        date: '2024-01-20',
        serviceType: 'consultation',
      },
      result: { slots: ['9:00 AM', '2:00 PM', '4:00 PM'] },
      agent: { customId: 'booking-agent-1' },
    },
    {
      name: 'bookAppointment',
      description: 'Book an appointment for the customer',
      startOffsetMs: 15000,
      endOffsetMs: 15800,
      parameters: {
        date: '2024-01-20',
        time: '2:00 PM',
        customerName: 'John Doe',
      },
      result: 'Appointment confirmed',
      agent: { customId: 'booking-agent-1' },
    },
  ],
})
Reference an agent by its Roark ID or custom ID:
// By Roark ID
const call = await client.call.create({
  recordingUrl: 'https://example.com/recording.mp3',
  startedAt: '2024-01-15T10:00:00Z',
  interfaceType: 'WEB',
  callDirection: 'OUTBOUND',
  agent: {
    roarkId: '550e8400-e29b-41d4-a716-446655440000',
  },
  customer: {
    phoneNumberE164: '+15551234567',
  },
})

// By custom ID
const call2 = await client.call.create({
  recordingUrl: 'https://example.com/recording.mp3',
  startedAt: '2024-01-15T10:00:00Z',
  interfaceType: 'PHONE',
  callDirection: 'INBOUND',
  agent: {
    customId: 'my-agent-id',
  },
  customer: {
    phoneNumberE164: '+15551234567',
  },
})
Run metrics across a batch of existing calls:
const job = await client.metricCollectionJob.create({
  callIds: [
    'call-uuid-1',
    'call-uuid-2',
    'call-uuid-3',
  ],
  metrics: [
    { id: 'metric-definition-uuid-1' },
    { id: 'metric-definition-uuid-2' },
  ],
})

// totalItems = callIds.length * metrics.length
console.log(`Processing ${job.data.totalItems} items`)

​
Additional Resources

API Reference

Explore our comprehensive API documentation

Example Repository

View example implementations and use cases

NPM Package

View package details and stats on npm

GitHub Repository

Browse the source code and contribute