> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usar el SDK

> Métodos de recursos, operaciones API, paginación, respuestas tipadas y archivos

Los siguientes ejemplos usan un `client` configurado según el [Inicio rápido](/es/sdk/quickstart). 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`.

```typescript theme={null}
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](/es/api-reference/introduction) lo permita.

## Cargar páginas cuando las necesites

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

```typescript theme={null}
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](/es/api-reference/introduction) como métodos tipados. Las entradas se agrupan en `path`, `query`, `body` y `headers`, sin mezclar parámetros distintos.

```typescript theme={null}
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:

```typescript theme={null}
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](/es/mcp/tools-and-scopes) 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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](/es/sdk/reference) para la cancelación, las clases de error y los reintentos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.