Usar el SDK - Famulor

Los siguientes ejemplos usan un client configurado según el Inicio rápido. Sustituye los ID por los de tu espacio de trabajo.

Métodos abreviados de recursos

Estos grupos ofrecen métodos concisos. Usa client.api para las operaciones que no aparecen aquí.

Grupo	Métodos	Recurso
`client.assistants`	`list`, `create`, `get`, `update`, `delete`, `iterate`	Asistentes
`client.calls`	`list`, `create`, `get`, `recording`, `iterate`	Llamadas y grabaciones
`client.campaigns`	`list`, `create`, `get`, `update`, `delete`, `start`, `stop`, `iterate`	Campañas
`client.contacts`	`list`, `create`, `iterate`	Contactos de la audiencia del espacio
`client.voices`	`list`, `preview`, `iterate`	Catálogo de voces y vistas previas
`client.knowledgeBases`	`list`, `create`, `get`, `delete`, `iterate`	Bases de conocimiento
`client.account`	`me`	Cuenta y espacio actuales

Los leads propios de una campaña están disponibles mediante client.api.listLeads, con el ID de campaña en path.id, o famulor list-leads <campaign-id> en la CLI. client.contacts gestiona la audiencia compartida del espacio.

Leer las respuestas

Los métodos de recursos conservan la estructura de respuesta de la API: el resultado está en data, y las listas pueden incluir meta.pagination.

const response = await client.calls.list({
  status: 'completed',
  limit: 20,
  offset: 0,
});

console.log(response.data);
console.log(response.meta?.pagination);

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

Usa encadenamiento opcional para los metadatos y campos que puedan valer null. Algunos resultados, como un resumen de llamada o una grabación, solo están disponibles tras el procesamiento. Omitir un campo opcional y enviar null son acciones distintas; envía null solo cuando la Referencia de la API lo permita.

Cargar páginas cuando las necesites

Usa el iterador asíncrono para los recursos paginados compatibles:

for await (const call of client.calls.iterate({
  status: 'completed',
  limit: 50,
})) {
  console.log(call.id, call.status);
}

limit es el tamaño de página, no un límite del total de elementos recorridos. El iterador conserva tus filtros y avanza el desplazamiento hasta el final. Salir del bucle detiene la carga de páginas nuevas. La paginación por desplazamiento no es una instantánea: las inserciones o cambios simultáneos pueden modificar el contenido de las páginas. Para establecer un límite de seguridad, pasa por ejemplo { maxPages: 100 } como segundo argumento. Alcanzarlo antes del final produce un error, sin devolver silenciosamente un resultado parcial. Para controlar las páginas manualmente, llama a client.calls.list() con limit y offset, y consulta meta.pagination. Las listas habituales devuelven 50 elementos por defecto y permiten hasta 200; respeta los límites de cada operación. El comando equivalente de la CLI es famulor list-calls --status completed --limit 50; añade --all para cargar todas las páginas.

Usar cualquier operación de la API pública

client.api expone los ID de operación de la Referencia de la API como métodos tipados. Las entradas se agrupan en path, query, body y headers, sin mezclar parámetros distintos.

const { data: account } = await client.api.getMe();

const { data: calls } = await client.api.listCalls({
  query: { status: 'completed', limit: 10 },
});

const { data: call } = await client.api.getCall({
  path: { id: 'call-id' },
});

console.log(account, calls.length, call.status);

Para una llamada saliente, el método completo de la API es:

const result = await client.api.createCall({
  body: {
    assistant_id: '11111111-1111-4111-8111-111111111111',
    to_number: '+4915123456789',
  },
});

console.log(result.data.id);

El método abreviado del recurso es client.calls.create(body). Ambos usan la misma API y conservan la misma respuesta y los mismos permisos.

Método del SDK	Operación REST	Comando de la CLI
`client.api.getMe()`	`GET /api/v1/me`	`famulor get-me`
`client.api.listCalls()`	`GET /api/v1/calls`	`famulor list-calls`
`client.api.getCall()`	`GET /api/v1/calls/{id}`	`famulor get-call <id>`
`client.api.createCall()`	`POST /api/v1/calls`	`famulor create-call --assistant-id <id> --to-number <number>`

Usa el autocompletado del editor para descubrir todos los métodos. Consulta Herramientas y permisos MCP para usar las funciones correspondientes en un asistente de IA.

Descargar respuestas binarias

Las operaciones de audio devuelven un ArrayBuffer, sin estructura JSON data. Por ejemplo, descarga una vista previa Full Duplex existente en formato WAV:

import { writeFile } from 'node:fs/promises';

const preview = await client.api.getVoicePreview({
  path: { id: 'voice-id' },
  query: { realtime_variant: 'full_duplex' },
});

await writeFile('preview.wav', new Uint8Array(preview));

Elige un ID de voz Full Duplex opaco del catálogo. Tu espacio debe tener acceso al modo de voz correspondiente. Una vista previa inexistente produce un error de API; esta solicitud no crea una muestra nueva.

Subir archivos

Pasa un cuerpo FormData a las operaciones que acepten cargas multipart. El SDK establece el tipo de contenido multipart y su delimitador:

import { readFile } from 'node:fs/promises';

const file = await readFile('avatar.png');
const form = new FormData();
form.set('file', new Blob([new Uint8Array(file)], { type: 'image/png' }), 'avatar.png');

await client.api.setAssistantAvatar({
  path: { id: 'assistant-id' },
  body: form,
});

Los avatares admiten PNG, JPEG o WebP, con un tamaño máximo de entrada de 1 MB. Respeta los requisitos de cada operación. Los comandos equivalentes de la CLI para ambos ejemplos son:

famulor get-voice-preview <voice-id> --realtime-variant full_duplex --output-file preview.wav
famulor set-assistant-avatar <assistant-id> --file avatar.png

Ajustar una solicitud

Las opciones son el último argumento, después de los parámetros de entrada del método. Los métodos generados de client.api reciben primero la entrada agrupada y después las opciones. Los métodos abreviados de recursos tienen distintos números de argumentos. Por ejemplo, una lista recibe la consulta y luego las opciones:

const response = await client.assistants.list(
  { limit: 10 },
  { timeoutMs: 10_000, maxRetries: 0 },
);

Al modificar un asistente, coloca las opciones después del ID y el cuerpo; al descargar audio, después del ID y la consulta; y en account.me(), como único argumento. Una consulta vacía conserva los valores por defecto. Sustituye los ID antes de ejecutar los ejemplos; modificar un asistente cambia su configuración.

const controller = new AbortController();
const options = { signal: controller.signal, timeoutMs: 10_000, maxRetries: 0 };

await client.assistants.update('assistant-id', { name: 'Support' }, options);
const recording = await client.calls.recording('call-id', {}, options);
const preview = await client.voices.preview('voice-id', {}, options);
const account = await client.account.me(options);

await client.api.getMe(undefined, options);

Consulta Configuración y errores para la cancelación, las clases de error y los reintentos.

​Métodos abreviados de recursos

​Leer las respuestas

​Cargar páginas cuando las necesites

​Usar cualquier operación de la API pública

​Descargar respuestas binarias

​Subir archivos

​Ajustar una solicitud