SDK quickstart - Famulor

This guide starts with a read request. Once your connection works, you can make an outbound call from a separate script.

Install the package

In your server project, run:

npm install famulor-sdk

Use Node.js 22 or newer. The package supports TypeScript and JavaScript, with both ESM import and CommonJS require.

Create a workspace API key

Select the intended workspace in Famulor, open Settings → API & MCP and create a key. Copy it while the full value is visible; it is shown only once.The workspace needs API Access through its plan or an add-on. A dashboard-created key has full scopes; if your integration needs fewer permissions, see API key hygiene.

Store the key on your server

For local development, put the key in a .env file:

FAMULOR_API_KEY=fam_your_workspace_key

Add .env to .gitignore. For hosted applications, use your host’s secret manager or server environment settings. The SDK receives the key explicitly; it does not load .env files or choose a workspace automatically.

Read your assistants

Save this file as sdk-read.mjs:

sdk-read.mjs

import { Famulor } from 'famulor-sdk';

if (!process.env.FAMULOR_API_KEY) {
  throw new Error('Set FAMULOR_API_KEY before running this script.');
}

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data } = await client.assistants.list({ limit: 10 });

for (const assistant of data) {
  console.log(assistant.id, assistant.name);
}

Run it with Node’s environment-file support:

node --env-file=.env sdk-read.mjs

An empty list is a successful connection when your workspace has no assistants yet. If the request fails, see Troubleshooting.

Start one outbound call

Choose an active assistant and an outbound-capable phone number assigned to it. Use a destination you intend to call, in E.164 format such as +4915123456789.

Running this next script places a real outbound call and can consume workspace credits. Replace both command arguments with your own assistant ID and intended destination.

Save this file as sdk-call.mjs:

sdk-call.mjs

import { Famulor } from 'famulor-sdk';

if (!process.env.FAMULOR_API_KEY) {
  throw new Error('Set FAMULOR_API_KEY before running this script.');
}

const [assistantId, toNumber] = process.argv.slice(2);
if (!assistantId || !toNumber) {
  throw new Error('Usage: node sdk-call.mjs <assistant-id> <E.164-number>');
}

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data: call } = await client.calls.create({
  assistant_id: assistantId,
  to_number: toNumber,
});

console.log({ id: call.id, status: call.status });

node --env-file=.env sdk-call.mjs <assistant-id> <E.164-number>

The response contains the created call’s ID and initial status. A successful creation response does not mean the recipient has answered. Save the ID and read the result later:

const { data: call } = await client.calls.get('call-id');
console.log(call.status, call.summary);

Prefer the assistant’s conversation-ended webhook for the final result; see Webhooks. The CLI equivalents are:

famulor create-call --assistant-id <assistant-id> --to-number <E.164-number>
famulor get-call <call-id>

Use your own domain

For a white-label workspace, use the domain you sign in to and include /api/v1:

import { Famulor } from 'famulor-sdk';

const client = new Famulor({
  apiKey: process.env.FAMULOR_API_KEY,
  baseUrl: 'https://app.example.com/api/v1',
});

Each API key belongs to one workspace. Use a separate key and client for each workspace. A custom domain does not add permissions or change the API paths. Continue with Use the SDK for pagination and complete API access, or Configuration and errors for reliable request handling.

​Start one outbound call

​Use your own domain

Start one outbound call

Use your own domain