Famulor SDKPara backends en TypeScript y JavaScript

Famulor en tu código.
Tipado, campo a campo.

Lista asistentes, inicia llamadas y lee resultados con unas líneas de TypeScript. Cada operación de la API es un método, con autocompletado en cada campo.

Obtener clave APIVer la guía
npm install famulor-sdk
  • Tipos desde la OpenAPI
  • ESM y CommonJS
  • Sin dependencias
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
Métodos

Métodos cortos para el día a día. client.api para todo lo demás.

Siete grupos cubren las tareas más comunes. Cada operación pública de la API es además un método tipado.

client.calls
Métodoslist()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)
Paginación

Todo tu historial de llamadas. Un solo bucle.

El iterador carga la siguiente página solo cuando la necesitas. Un break detiene la carga.

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

Las lecturas se reintentan. Las llamadas, nunca dos veces.

Ante 429, 502, 503 o 504 el SDK reintenta las lecturas. Las escrituras, como iniciar una llamada, nunca se repiten solas.

Lectura

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

Escritura

  1. POST /calls
  2. timeout
  3. retrysin segundo intento
  4. mayHaveExecutedComprueba el estado antes de reenviar.

Errores tipados

  • FamulorApiError

    Respuesta de la API con status, code y requestId.

  • FamulorTimeoutError

    Plazo agotado. mayHaveExecuted indica si pudo ejecutarse.

  • FamulorNetworkError

    Sin respuesta, también con mayHaveExecuted.

  • FamulorAbortError

    Tu AbortSignal canceló la petición.

Hecho para producción

Predecible en cualquier entorno.

Credenciales explícitas, un plazo fijo por petición y ningún estado global.

Tú pasas la clave

El SDK no carga archivos .env ni elige un workspace por ti. Cada cliente solo conoce su clave.

Un cliente por workspace

Una clave API pertenece a un workspace. Para varios workspaces, crea varios clientes.

También en tu dominio

Los partners white-label apuntan baseUrl a su propio dominio HTTPS con /api/v1.

OAuth para apps de usuario

En lugar de una clave, pasa un token OAuth o una función que devuelva el actual.

Un plazo por petición

timeoutMs cubre el token, los reintentos y la respuesta. Cancela cuando quieras con un AbortSignal.

Archivos y audio

Las subidas van como FormData. Grabaciones y muestras de voz vuelven como 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 o API

Cuatro caminos a Famulor. Elige el tuyo.

Los cuatro trabajan con el mismo workspace y los mismos datos.

Una operación, en todas partes

SDKclient.calls.create()
RESTPOST /api/v1/calls
CLIfamulor create-call
Esta página

Famulor SDK

Para TypeScript y JavaScript en tu backend.

  • Cada operación como método
  • Tipos desde la OpenAPI
  • ESM y CommonJS
Ver la guía

Famulor CLI

Para terminal, scripts, CI y agentes de código.

  • Un comando por operación
  • JSON, tabla o JSONL
  • Clave en el llavero del sistema
Ver Famulor CLI

MCP Connector

Para Claude, ChatGPT y otras herramientas de IA en el chat.

  • Una URL de servidor, acceso OAuth
  • Herramientas de Famulor en el chat
  • Sin instalación local
Ver MCP Connector

REST API

Para integraciones HTTP en cualquier lenguaje.

  • Especificación OpenAPI
  • Webhooks en tiempo real
  • Cualquier lenguaje o framework
Ver referencia API
Todo para desarrolladores
De un vistazo

Paquete pequeño. API completa.

Cobertura de la API

100%

Cada operación pública con client.api.

Dependencias

0

Usa el fetch de tu runtime de Node.js.

Formatos de módulo

2

ESM y CommonJS, con tipos para ambos.

Grupos de recursos

7

Asistentes, llamadas, campañas y más.

Para empezar

Tu primera llamada en tres pasos.

Instala, crea una clave y listo.

  1. 01

    Instalar

    npm install famulor-sdk. Funciona con Node.js 22 o superior, como ESM o CommonJS.

  2. 02

    Crear una clave

    Crea una clave en Settings → API & MCP y guárdala en el entorno o el gestor de secretos de tu servidor.

  3. 03

    Empezar

    new Famulor({ apiKey }) y luego client.assistants.list(). Tu editor muestra cada campo.

Combina con

Más funciones de la plataforma

Otros módulos que los equipos suelen combinar con esta función.

FAQ

Preguntas antes de salir a live

¿Qué es el Famulor SDK?

El Famulor SDK es el cliente oficial de TypeScript y JavaScript para la API pública de Famulor. Trae métodos cortos para asistentes, llamadas, campañas, contactos, voces, bases de conocimiento y tu cuenta. Con client.api llegas a cualquier otra operación, con tipos de la especificación OpenAPI.

¿Qué necesito para usar el SDK?

Node.js 22 o superior y un workspace con API Access a través de tu plan o un add-on. Se instala con npm install famulor-sdk. La clave API se crea en el panel en Settings → API & MCP.

¿Puedo usar el SDK en el navegador o en una app?

El SDK se ejecuta en tu servidor para que tu clave API siga siendo secreta. Para conversaciones en tu web, usa el widget web.

¿Puede iniciarse una llamada dos veces si se corta la conexión?

No por el SDK. Nunca repite escrituras de forma automática, ni siquiera tras un límite de uso. Tras un timeout, mayHaveExecuted indica si la petición pudo llegar. Comprueba el estado antes de enviarla otra vez.

¿Funciona con JavaScript sin TypeScript?

Sí. El paquete incluye ESM y CommonJS, así que puedes usar import o require('famulor-sdk'). Los proyectos TypeScript reciben los tipos automáticamente.

¿Funciona con varios workspaces y white-label?

Sí. Una clave API pertenece a un solo workspace, así que creas un cliente por workspace. Con tu propio dominio, define baseUrl, por ejemplo https://app.example.com/api/v1.

¿El SDK admite OAuth?

Sí. En lugar de apiKey pasas accessToken: un token o una función que devuelva el actual. Tu app gestiona el consentimiento y la renovación del token.

¿Cuándo uso el SDK, la CLI o el MCP Connector?

El SDK encaja en tu backend. La CLI es para terminal, scripts, CI y agentes de código. El MCP Connector lleva Famulor a herramientas de chat como Claude o ChatGPT. Los tres usan la misma API y el mismo workspace.

Empieza ahora

Tu primera llamada, a pocas líneas.

Consigue una clave API, instala famulor-sdk y empieza con client.assistants.list().

Obtener clave APIVer la guía

El Famulor SDK es gratuito y tiene licencia MIT. Necesita Node.js 22 o superior y un plan con API Access.