Inicio rápido del SDK

Esta guía empieza con una lectura. Cuando la conexión funcione, podrás iniciar una llamada saliente desde otro script.

Instalar el paquete

En tu proyecto de servidor, ejecuta:

npm install famulor-sdk

Usa Node.js 22 o posterior. El paquete admite TypeScript y JavaScript, tanto ESM import como CommonJS require.

Crear una clave API del espacio de trabajo

Selecciona el espacio deseado en Famulor, abre Configuración → API & MCP y crea una clave. Copia el valor completo mientras esté visible; solo se muestra una vez.El espacio necesita Acceso a la API mediante su plan o un complemento. Una clave creada en el panel tiene todos los permisos. Para restringirlos, consulta Seguridad de las claves API.

Guardar la clave en tu servidor

Para el desarrollo local, coloca la clave en un archivo .env:

FAMULOR_API_KEY=fam_your_workspace_key

Añade .env a .gitignore. En aplicaciones alojadas, usa el gestor de secretos o la configuración de entorno de servidor de tu proveedor. El SDK recibe la clave explícitamente; no carga archivos .env ni selecciona un espacio de trabajo automáticamente.

Leer tus asistentes

Guarda este archivo como 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);
}

Ejecútalo con la compatibilidad de Node para archivos de entorno:

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

Una lista vacía confirma la conexión si tu espacio aún no tiene asistentes. Si la solicitud falla, consulta Solución de problemas.

Iniciar una llamada saliente

Elige un asistente activo con un número asignado que permita llamadas salientes. Usa un destino al que quieras llamar en formato E.164, por ejemplo +4915123456789.

El siguiente script realiza una llamada saliente real y puede consumir créditos. Sustituye ambos argumentos por el ID de tu asistente y el destino deseado.

Guarda este archivo como 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>

La respuesta contiene el ID de la llamada creada y su estado inicial. Una creación correcta no significa que el destinatario haya contestado. Guarda el ID y consulta el resultado más tarde:

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

Para recibir el resultado final, utiliza preferiblemente el webhook del asistente que se envía al terminar la conversación; consulta Webhooks. Los comandos equivalentes de la CLI son:

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

Usar tu propio dominio

Para un espacio con marca blanca, usa el dominio donde inicias sesión y añade /api/v1:

import { Famulor } from 'famulor-sdk';

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

Cada clave API pertenece a un único espacio de trabajo. Usa una clave y un cliente distintos para cada espacio. Un dominio propio no añade permisos ni cambia las rutas de la API. Continúa con Usar el SDK para la paginación y el acceso completo, o Configuración y errores para gestionar solicitudes de forma fiable.

​Iniciar una llamada saliente

​Usar tu propio dominio

Iniciar una llamada saliente

Usar tu propio dominio