Node.js SDK
@rymi/node is the official server-side SDK for Node. It gives you strongly-typed access to the Rymi REST API from JavaScript or TypeScript.
Installation
Install the package:
npm install @rymi/node
# or
yarn add @rymi/node
# or
pnpm add @rymi/nodeLatest release: @rymi/node on npm. The package ships with full TypeScript types. Request/response shapes come from @rymi/sdk-types, a dependency that installs with it. Depend on @rymi/sdk-types directly only if you're sharing Rymi types across your own packages without pulling in the full client.
Initialization
Import the Rymi class and pass your API key. Omit apiKey and the SDK reads RYMI_API_KEY from the environment.
import { Rymi } from '@rymi/node';
// Initialize with an explicit API Key:
const rymi = new Rymi({ apiKey: 'rymi_your_secret_key' });
// OR rely on process.env.RYMI_API_KEY:
const rymiEnv = new Rymi();Accounts
rymi.accounts lists accounts, renames one, and manages members and this month's workspace usage. Roles are owner, admin, and billing. See Accounts.
const { accounts } = await rymi.accounts.list();
const { account } = await rymi.accounts.get(accounts[0].id);
await rymi.accounts.update(account.id, { name: 'Rymi' });
const added = await rymi.accounts.members.add(account.id, {
email: 'arvind@example.com',
role: 'billing',
});
const { members } = await rymi.accounts.members.list(account.id);
await rymi.accounts.members.update(account.id, added.member.user_id, { role: 'admin' });
await rymi.accounts.members.remove(account.id, added.member.user_id);
const { workspaces } = await rymi.accounts.workspaces(account.id);Workspaces
Pass workspace, or set RYMI_WORKSPACE, and every request sends Rymi-Workspace. withWorkspace returns a client aimed at one workspace you can reach. An account key may name any workspace in its account. A workspace key that names another workspace receives workspace_forbidden. Omit both and the request stays in the key's own workspace.
const rymi = new Rymi({
apiKey: 'rymi_your_secret_key',
workspace: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
});
const client = rymi.withWorkspace('7c9e6679-7425-40de-944b-e07fc1f90ae7');
await client.compliance.getSettings();rymi.workspaces lists, creates, updates, and deletes workspaces, plus monthly usage and members. role is admin, editor, client, viewer, or null. Rows include account_id, account_name, and account_role. create({ name, operating_country, parent }) creates in the current account. parent must name a workspace in that account. delete(id) removes an empty workspace for an account Owner. It rejects with cannot_delete_primary for the primary workspace and workspace_not_empty (with blockers) while agents, numbers, calls, campaigns, or other workspaces remain. See Delete a workspace. Creating one with operating_country saves that country's compliance preset. addMember(id, { email, role }) takes admin, editor, client, or viewer (default client). See Workspaces.
Agents
Create, list, and manage your AI voice personas.
// Create a new conversational Agent
const agent = await rymi.agents.create({
name: 'Customer Support',
system_prompt: 'You are a helpful customer support assistant for Acme Corp.',
voice: 'Aoede',
language: 'en-US'
});
console.log(agent.id);
// List all configured agents
const { agents } = await rymi.agents.list();Multi-language agents & model stack
create and update accept the full configuration surface. Set supported_languages for a multi-language agent, and optionally pin the STT/LLM/TTS stack, per-channel fallbacks, and Enterprise self-hosted endpoints. provider_config is server-derived and is not accepted as input.
const bilingual = await rymi.agents.create({
name: 'Ganga Sahayak',
language: 'hi-IN',
supported_languages: ['hi-IN', 'en-US'],
llm_provider: 'gemini',
llm_model: 'gemini-2.5-flash',
// optional fallbacks + explicit STT/TTS
tts_provider: 'sarvam',
llm_fallback_provider: 'openai',
llm_fallback_model: 'gpt-4o-mini',
});Preview the model stack
Resolve the per-language stack (STT/LLM/TTS), blockers, and warnings before saving.
const preview = await rymi.agents.previewStack({
supported_languages: ['hi-IN', 'en-US'],
});
console.log(preview.blockers, preview.warnings, preview.provider_config);Knowledge sources (RAG)
Attach searchable context to an agent from raw text or a URL.
await rymi.agents.addKnowledgeSource(agent.id, {
kind: 'text',
title: 'Refund policy',
text: 'Refunds are processed within 5 business days...',
});
const { sources } = await rymi.agents.listKnowledgeSources(agent.id);
await rymi.agents.deleteKnowledgeSource(agent.id, sources[0].id);Configuration history
Audit recorded config changes and revert any single one. It's a reversible undo, not a full rollback.
const { changes } = await rymi.agents.listChanges(agent.id);
await rymi.agents.undoChange(agent.id, changes[0].change_id);Evaluations
Run the agent's evaluation suite and read per-scenario scores.
const run = await rymi.agents.runEvals(agent.id, { mode: 'synthetic' });
const { runs } = await rymi.agents.listEvalRuns(agent.id) as any;
const detail = await rymi.agents.getEvalRun(agent.id, run.id ?? runs[0].id);Clone an agent
const clone = await rymi.agents.clone(agent.id);
console.log(clone.id); // new agent ID, name gets " (Copy)" appendedList calls for an agent
const { calls, total } = await rymi.agents.listCalls(agent.id, { limit: 20 });Validate before publishing
Check whether an agent's config is ready to go live. Returns a validation report without changing anything.
const report = await rymi.agents.validatePublish({ agent_id: agent.id });
if (!report.valid) {
console.error(report.errors);
}Capability discovery
Before showing an editor or writing automation, query what the connected tenant is allowed to do. These are read-only calls, safe to chain at startup:
// Available models and voices for this tenant
const { models, voices } = await rymi.agents.llmOptions();
// Full config for an agent, including runtime-affecting fields
const detail = await rymi.agents.retrieve(agent.id);
// Dry-run a change-set against the field registry; does not save
const dryRun = await rymi.agents.applyChanges({
currentConfig: detail,
changes: [{ key: 'voice', value: 'Charon' }],
mode: 'edit',
});
// Whether the agent passes every publish requirement
const report = await rymi.agents.validatePublish({ agent_id: agent.id });When a call returns errors, the code field is a machine identifier you can branch on. Use the codes for routing logic; render the human-readable message for display.
Apply a structured change-set
Validate and resolve a flat key/value diff against the field registry. Does not persist; follow up with update().
const result = await rymi.agents.applyChanges({
currentConfig: { name: 'Support', voice: 'Aoede' },
changes: [{ key: 'voice', value: 'Charon' }],
mode: 'edit',
});
// result.config has the merged config; result.applied lists what changed
await rymi.agents.update(agent.id, result.config);Enrich company from website
Generate a company description for the agent's persona using AI + Google Search grounding.
const info = await rymi.agents.enrichCompany({
companyName: 'Acme Corp',
websiteUrl: 'https://acme.example.com',
});
if (info.enriched) {
console.log(info.companyDescription);
}Calls
Create voice call sessions with one or more participants. Each call maps to a single room that can include WebRTC (browser) and PSTN (phone) participants.
// Start an outbound PSTN call
const call = await rymi.calls.create({
agent_id: agent.id,
participants: [
{
transport: 'pstn',
identity: '+15551234567',
from_number: '+15559876543'
}
],
metadata: {
customer_name: 'Alice',
order_status: 'shipped'
}
});
console.log(`Call queued with ID: ${call.id}`);
console.log(`Room: ${call.room_name}`);
// Start a WebRTC call (returns a LiveKit token)
const webCall = await rymi.calls.create({
agent_id: agent.id,
participants: [
{ transport: 'webrtc', identity: 'browser-user-1' }
]
});
// Access the participant's LiveKit credentials
const participant = webCall.participants[0];
console.log(`LiveKit URL: ${participant.access?.url}`);
console.log(`Token: ${participant.access?.token}`);
// Retrieve transcript and metadata after the call ends
const details = await rymi.calls.retrieve(call.id);
const transcript = await rymi.calls.transcript(call.id);Observe calls
Read-only helpers for browsing and analysing calls. None of these place a call.
const { calls } = await rymi.calls.list({ limit: 20, status: 'completed' });
const live = await rymi.calls.active();
const summary = await rymi.calls.summary(call.id);
const recording = await rymi.calls.recording(call.id); // playback metadata
const stats = await rymi.calls.queueStats();
await rymi.calls.reprocess(call.id); // re-run post-call intelligenceConfirm a test destination
Shared test lines only call a number this user confirmed on WhatsApp. start opens the request and returns the link. It does not confirm the number. The phone confirms it by sending message_text. A secret key needs calls:write to start and calls:read to check. See Confirm a test destination.
const pending = await rymi.phoneConfirmation.start({ phone: '+919876543210' });
if (!pending.confirmed) {
console.log(pending.wa_url, pending.message_text, pending.expires_in);
}
const { confirmed } = await rymi.phoneConfirmation.status('+919876543210');To confirm by code, call requestCode. A person then types the code at entry_url while signed in to Studio. No secret key can submit a code, and a confirmed number is never a login number. See Request a code.
const sent = await rymi.phoneConfirmation.requestCode({ phone: '+919876543210' });
console.log(sent.entry_url, sent.expires_in, sent.resend_after);409 in_progress means someone is already confirming that number (try again in 10 minutes). 429 daily_limit means this user has started 20 confirmations today. 503 means WhatsApp confirmation is not configured.
Control a live call
Mutate an in-progress call: end it, or add a participant to a live call.
// Add one or more participants to a call already in progress
await rymi.calls.addParticipants(call.id, {
participants: [{ transport: 'pstn', identity: '+15557654321', from_number: '+15559876543' }]
});
// End the call
await rymi.calls.end(call.id);Batch Calls
Queue up to 500 outbound PSTN recipients in one request.
const batch = await rymi.calls.batch({
agent_id: agent.id,
to: ['+15551234567', '+15557654321'],
from_number: '+15559876543',
variables: { batch_label: 'renewal-q2' }
});
console.log(batch.batch_id, batch.queued);Do-Not-Call (DNC)
Manage the Do-Not-Call registry. Numbers are normalized to E.164 server-side on both read and write, so any input format is accepted. Outbound calls to blocked numbers are refused.
// Add a single number
await rymi.dnc.add({ phone_number: '+15551234567', reason: 'customer opt-out' });
// Add up to 1000 at once; invalid numbers are skipped and returned
const result = await rymi.dnc.addBatch({ phone_numbers: ['+15551234567', '+15557654321'] });
console.log(result.count, result.invalid_count, result.invalid);
// Check up to 500 numbers without adding them (read-only)
const { results, blocked_count } = await rymi.dnc.check({ phone_numbers: ['+15551234567'] });
// List and remove
const { dnc_entries, total } = await rymi.dnc.list({ limit: 50 });
await rymi.dnc.remove('+15551234567'); // re-enables outbound to itSee the Compliance API for the underlying REST endpoints.
Compliance settings
Calling hours, the do-not-call check, voice consent, the recording notice for new agents, and destination countries. Choosing operating_country fills every setting you have not edited. See the guide.
const settings = await rymi.compliance.getSettings();
const preview = await rymi.compliance.previewSettings('IN');
await rymi.compliance.updateSettings({
operating_country: 'IN',
rules: { apply_to_single_calls: true },
});updateSettings({ operating_country: null }) clears the country and leaves the rules in place.
Phone Numbers
Register carrier-owned BYOC numbers, list registered numbers, and attach them to agents. Rymi does not purchase phone numbers; provision numbers in your carrier account first.
await rymi.numbers.register('+15559876543');
const { numbers } = await rymi.numbers.list();
await rymi.numbers.attach(numbers[0].number, agent.id);
// Detach + remove a number from the account
await rymi.numbers.remove(numbers[0].number);Telephony
Inspect the connected carrier, and with carrier credentials, manage it. Most teams connect a carrier once from the dashboard; the SDK methods exist for programmatic provisioning.
const status = await rymi.telephony.status(); // { connected, provider, account_name, account_country }
const { numbers } = await rymi.telephony.numbers();
// Connect / disconnect a carrier (requires carrier credentials)
await rymi.telephony.connect({ provider: 'twilio', auth_id: 'AC...', auth_token: '...' });
await rymi.telephony.disconnect();Phone line from Rymi
See Phone Line from Rymi for fields and errors.
const { has_line, line } = await rymi.telephony.line();
const { studio_url } = await rymi.telephony.requestLine({ country: 'IN', handoff: 'both' });
await rymi.telephony.acceptLineTerms();
await rymi.telephony.submitLineKyc({ fields: { name: 'Sharma Realty Pvt Ltd', city: 'Pune' }, submit: true });
const { pending_publish } = await rymi.agents.pendingPublish(agentId);
await rymi.contacts.recordConsent({ phone: '+919876543210', source: 'web_form', consent_text: 'I agree to receive calls.' });Secret keys
keys.create mints an account or workspace key. The response field is key, shown once. keys.self reads the key authenticating this client. See API keys and scopes.
const created = await rymi.keys.create({
kind: 'workspace',
label: 'Website calls',
scopes: ['calls:write', 'agents:read'],
});
console.log(created.key);
const self = await rymi.keys.self();
// { kind, account_id, workspace_id, scopes, legacy }Publishable keys
Manage browser-safe publishable keys for WebRTC calls. listPublishable returns prefixes and scoping only, never full secrets. createPublishable returns the full key once, at creation time; store it then.
const { keys } = await rymi.keys.listPublishable();
// Create a key scoped to a single agent. The full `key` is only returned here.
const created = await rymi.keys.createPublishable({
agent_id: agent.id,
label: 'Marketing site widget',
allowed_channels: ['web'],
default_from_number: '+15559876543',
});
console.log(created.key); // sb_publishable_...: store now, not retrievable later
await rymi.keys.revokePublishable(created.id);Server-side only
Key creation and revocation require your secret key, so do them from a backend. Never ship secret keys to the browser. (For the same reason, these aren't exposed over MCP.)
Usage
Get a lane-aware usage summary. Voice balance is reported in minutes (the customer-facing unit), not dollars.
const usage = await rymi.billing.usageSummary();
console.log(usage.voice_runtime.remaining_minutes, usage.voice_runtime.status);
console.log(usage.studio_ai?.used_units, usage.post_call_intelligence?.status);Cost estimate & spend controls
Estimate a call's cost before placing it, and configure auto-recharge and spend alerts. These are spend-management settings, so they are denominated in USD.
// Estimate a custom stack's cost for a given duration before dialing
const est = await rymi.billing.estimate({
stt_model: 'nova-2',
llm_model: 'gemini-2.5-flash',
tts_model: 'gemini-2.5-flash-tts',
duration_seconds: 300,
});
// Top up automatically when the balance drops below a threshold
await rymi.billing.setAutoRecharge({ enabled: true, pack_usd: 50, threshold_usd: 10 });
// Get notified at spend thresholds or low balance
await rymi.billing.setAlerts({ thresholds_usd: [25, 50], low_balance_pct: 15, email_enabled: true });
// Billing country. Locked after the first paid invoice (409 billing_country_locked).
await rymi.billing.setCountry('IN');Campaigns and live leads
Create a campaign, launch it, then keep adding people while it runs. See Campaigns and the Campaigns API.
const { campaign } = await rymi.campaigns.create({
agent_id: 'agent_123',
type: 'outbound',
name: 'Subscriber updates',
schedule_policy: { start: '09:00', end: '20:00', timezone: 'Asia/Kolkata' },
});
await rymi.campaigns.launch(campaign.id);
// Push a lead from your backend; it's dialed on the next sweep inside the window.
await rymi.campaigns.members.import(campaign.id, {
contacts: [{ phone: '+919876543210', name: 'Ramesh', consent: { voice: true } }],
});
// Or give a form tool a URL it can post to without an API key (shown once).
const { url } = await rymi.campaigns.intake.set(campaign.id, { assume_voice_consent: true, default_country: 'IN' });Sharing and API-tool secrets
// Public share link: anyone with the URL can talk to the published agent.
const { link } = await rymi.agents.setShareLink('agent_123', { enabled: true, minutes_limit: 120 });
// Secret for an API tool header, used as {{secrets.RESERVATIONS_API_KEY}}.
await rymi.toolSecrets.set('RESERVATIONS_API_KEY', { value: 'sk_live_...', host: 'api.example.com' });Templates
List published agent templates and use a template's defaults to seed a new agent.
const { templates } = await rymi.templates.list();
const starter = templates.find(t => t.label === 'Healthcare Receptionist');
if (starter) {
await rymi.agents.create({ name: 'Front Desk', ...starter.defaults });
}Managing webhook endpoints
Register and maintain the endpoints Rymi delivers events to. Each endpoint has its own signing secret; keep it to verify deliveries (see below).
const created = await rymi.webhooks.create({
url: 'https://api.example.com/rymi-webhook',
events: ['call.completed', 'call.intelligence.ready'],
secret: process.env.RYMI_WEBHOOK_SECRET!,
alert_email: 'oncall@example.com',
});
const { webhooks } = await rymi.webhooks.list();
await rymi.webhooks.update(webhooks[0].id, { events: ['call.intelligence.ready'] });
await rymi.webhooks.delete(webhooks[0].id);See the Webhooks API for the full event catalog.
Verifying Webhooks
When your application receives asynchronous events (like call.intelligence.ready), you must cryptographically verify the webhook signature to protect against replay attacks and spoofing.
The Node SDK includes a built-in helper to validate the X-Rymi-Signature HMAC.
import express from 'express';
import { Rymi } from '@rymi/node';
const app = express();
const rymi = new Rymi();
// Ensure you parse the body as raw TEXT or BUFFER for accurate HMAC verification
app.post('/webhook', express.text({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-rymi-signature'] as string;
const timestamp = req.headers['x-rymi-timestamp'] as string;
const payload = req.body; // Raw JSON string
try {
rymi.webhooks.verifySignature(
payload,
signature,
timestamp,
process.env.RYMI_WEBHOOK_SECRET!
);
console.log('Webhook authenticated successfully!');
// Process webhook event safely...
const event = JSON.parse(payload);
if (event.type === 'call.intelligence.ready') {
console.log('Call intelligence:', event.data.call_id, event.data.summary);
}
res.status(200).send('OK');
} catch (error) {
console.error('Invalid webhook signature!', error);
res.status(401).send('Unauthorized');
}
});
