Famulor SDKFor TypeScript and JavaScript backends

Famulor in your code.
Typed, field by field.

List assistants, start calls and read results in a few lines of TypeScript. Every API operation is a method, with autocomplete for every field.

Get an API keyRead the docs
npm install famulor-sdk
  • Types from the OpenAPI
  • ESM and CommonJS
  • Zero dependencies
server.ts
$ npm install famulor-sdk
added 1 package in 1s

// server.ts
import { Famulor } from 'famulor-sdk'

const client = new Famulor({
  apiKey: process.env.FAMULOR_API_KEY,
})

const { data: call } = await client.calls.create({
  assistant_id: '3e8b1f6a-9c2d-4a7e-b1f5-6d7c8e9a0b55',
  to_number: '+4930123456',
})

console.log(call.id, call.status)

$ node server.ts
c7d21e4a-5b3f-4e8a-a1c9-2f6e0b7d9a13 queued
Methods

Short methods for every day. client.api for everything else.

Seven groups cover the most common tasks. Every public API operation is also a typed method.

client.calls
Methodslist()create()get()recording()iterate()
const { data: call } = await client.calls.create({
assistant_id: assistant.id,
to_number: '+4930123456',
})
​
const { data: result } = await client.calls.get(call.id)
console.log(result.status, result.summary)
Pagination

Your whole call history. One loop.

The iterator fetches the next page only when you need it. A break stops fetching.

sync-calls.ts
for await (const call of client.calls.iterate({
status: 'completed',
limit: 50,
})) {
await saveToCrm(call)
if (isDone(call)) break
}
Safe retries

Reads retry. Calls never go out twice.

On 429, 502, 503 or 504 the SDK retries reads. Writes such as placing a call are never repeated automatically.

Read

  1. GET /calls
  2. 503
  3. Retry-Afterretried
  4. 200 OK

Write

  1. POST /calls
  2. timeout
  3. retryno second attempt
  4. mayHaveExecutedCheck the state before you resend.

Typed errors

  • FamulorApiError

    The API answered with status, code and requestId.

  • FamulorTimeoutError

    Deadline passed. mayHaveExecuted tells you if it may have run.

  • FamulorNetworkError

    No response received, also with mayHaveExecuted.

  • FamulorAbortError

    Your AbortSignal cancelled the request.

Built for production

Predictable in every environment.

Explicit credentials, one fixed deadline per request and no global state.

You pass the key

The SDK loads no .env files and picks no workspace for you. Each client knows only its own key.

One client per workspace

An API key belongs to one workspace. For several workspaces, create several clients.

On your own domain too

White-label partners point baseUrl at their own HTTPS domain with /api/v1.

OAuth for user apps

Pass an OAuth token, or a function that returns the current one, instead of a key.

One deadline per request

timeoutMs covers the token, retries and the response. Cancel any time with an AbortSignal.

Files and audio

Uploads go in as FormData. Recordings and voice previews come back as ArrayBuffer.

client.ts
const client = new Famulor({
apiKey: process.env.FAMULOR_API_KEY,
baseUrl: 'https://app.famulor.io/api/v1',
timeoutMs: 90_000,
maxRetries: 2,
})
​
const controller = new AbortController()
​
await client.calls.list(
{ status: 'completed', limit: 10 },
{ signal: controller.signal, timeoutMs: 10_000 },
)
SDK, CLI, MCP or API

Four ways in. Pick the one that fits.

All four work on the same workspace and the same data.

One operation, every tool

SDKclient.calls.create()
RESTPOST /api/v1/calls
CLIfamulor create-call
This page

Famulor SDK

For TypeScript and JavaScript in your backend.

  • Every API operation as a method
  • Types from the OpenAPI
  • ESM and CommonJS
Read the docs

Famulor CLI

For terminals, scripts, CI and coding agents.

  • One command per API operation
  • JSON, table or JSONL
  • Key in your OS keychain
See Famulor CLI

MCP Connector

For Claude, ChatGPT and other AI tools in chat.

  • One server URL, OAuth sign-in
  • Famulor tools right in the chat
  • Nothing to install locally
See MCP Connector

REST API

For HTTP integrations in any language.

  • OpenAPI specification
  • Real-time webhooks
  • Any language, any framework
See API reference
Everything for developers
At a glance

Small package. Full API.

API coverage

100%

Every public operation via client.api.

Runtime dependencies

0

Uses the fetch of your Node.js runtime.

Module formats

2

ESM and CommonJS, typed for both.

Resource groups

7

Assistants, calls, campaigns and more.

Get started

Your first call in three steps.

Install, create a key, go.

  1. 01

    Install

    npm install famulor-sdk. Runs on Node.js 22 or newer, as ESM or CommonJS.

  2. 02

    Create a key

    Create a key in Settings → API & MCP and store it in your server’s environment or secret manager.

  3. 03

    Go

    new Famulor({ apiKey }), then client.assistants.list(). Your editor shows every field.

Works with

More from the platform

Other building blocks teams usually pair with this one.

FAQ

Questions before you go live

What is the Famulor SDK?

The Famulor SDK is the official TypeScript and JavaScript client for the public Famulor API. It brings short methods for assistants, calls, campaigns, contacts, voices, knowledge bases and your account. client.api reaches every other operation, with types from the OpenAPI specification.

What do I need to use the SDK?

Node.js 22 or newer and a workspace with API Access through your plan or an add-on. Install it with npm install famulor-sdk. Create the API key in the dashboard under Settings → API & MCP.

Can I use the SDK in a browser or mobile app?

The SDK runs on your server so your API key stays secret. For conversations right on your website, use the web widget.

Can a call start twice if the connection drops?

Not through the SDK. It never retries writes automatically, not even after a rate limit. After a timeout, mayHaveExecuted shows whether the request may already have arrived. Check the state before you send it again.

Does it work with plain JavaScript?

Yes. The package ships ESM and CommonJS, so you can use import or require('famulor-sdk'). TypeScript projects get the types automatically.

Does it work with several workspaces and white-label?

Yes. An API key belongs to exactly one workspace, so you create one client per workspace. On your own domain, set baseUrl, for example to https://app.example.com/api/v1.

Does the SDK support OAuth?

Yes. Pass accessToken instead of apiKey: a token, or a function that returns the current one. Your app runs consent and token refresh.

When should I use the SDK, CLI or MCP Connector?

The SDK fits your backend. The CLI is for terminals, scripts, CI and coding agents. The MCP Connector brings Famulor into chat tools like Claude or ChatGPT. All three use the same API and workspace.

Get started

Your first call, a few lines away.

Get an API key, install famulor-sdk and start with client.assistants.list().

Get an API keyRead the docs

The Famulor SDK is free and MIT licensed. It needs Node.js 22 or newer and a plan with API Access.