> ## 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.

# Utiliser le SDK

> Méthodes de ressources, opérations API, pagination, réponses typées et fichiers

Les exemples suivants utilisent un `client` configuré selon le [Démarrage rapide](/fr/sdk/quickstart). Remplacez les ID par ceux de votre espace de travail.

## Raccourcis de ressources

Les groupes suivants proposent des méthodes concises. Utilisez `client.api` pour les opérations absentes de ce tableau.

| Groupe | Méthodes | Ressource |
| - | - | - |
| `client.assistants` | `list`, `create`, `get`, `update`, `delete`, `iterate` | Assistants |
| `client.calls` | `list`, `create`, `get`, `recording`, `iterate` | Appels et enregistrements |
| `client.campaigns` | `list`, `create`, `get`, `update`, `delete`, `start`, `stop`, `iterate` | Campagnes |
| `client.contacts` | `list`, `create`, `iterate` | Contacts de l’audience de l’espace de travail |
| `client.voices` | `list`, `preview`, `iterate` | Catalogue vocal et aperçus |
| `client.knowledgeBases` | `list`, `create`, `get`, `delete`, `iterate` | Bases de connaissances |
| `client.account` | `me` | Compte et espace de travail actuels |

Les prospects propres à une campagne sont accessibles via `client.api.listLeads`, avec l’ID de campagne dans `path.id`, ou `famulor list-leads <campaign-id>` dans la CLI. `client.contacts` gère l’audience partagée de l’espace de travail.

## Lire les réponses

Les méthodes de ressources conservent l’enveloppe de réponse de l’API : le résultat se trouve dans `data`, et les listes peuvent inclure `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);
```

Utilisez le chaînage optionnel pour les métadonnées et les champs pouvant valoir `null`. Certains résultats, comme un résumé d’appel ou un enregistrement, ne sont disponibles qu’après traitement. Omettre un champ facultatif et envoyer `null` sont deux actions différentes ; envoyez `null` uniquement lorsque la [Référence API](/fr/api-reference/introduction) l’autorise.

## Charger les pages à la demande

Utilisez l’itérateur asynchrone pour les ressources paginées compatibles :

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

`limit` correspond à la taille d’une page, pas au nombre total d’éléments parcourus. L’itérateur conserve les filtres et avance le décalage jusqu’à la fin. Quitter la boucle arrête le chargement de nouvelles pages. La pagination par décalage n’est pas un instantané : des ajouts ou modifications simultanés peuvent changer le contenu des pages. Pour définir une limite de sécurité, passez par exemple `{ maxPages: 100 }` comme deuxième argument. Atteindre cette limite avant la fin produit une erreur, sans renvoyer silencieusement un résultat partiel.

Pour contrôler les pages manuellement, appelez `client.calls.list()` avec `limit` et `offset`, puis consultez `meta.pagination`. Les listes classiques renvoient 50 éléments par défaut et en acceptent jusqu’à 200 ; respectez les limites de chaque opération.

La commande CLI équivalente est `famulor list-calls --status completed --limit 50` ; ajoutez `--all` pour charger toutes les pages.

## Utiliser toute opération de l’API publique

`client.api` expose les ID d’opération de la [Référence API](/fr/api-reference/introduction) sous forme de méthodes typées. Les entrées sont regroupées dans `path`, `query`, `body` et `headers` au lieu de mélanger différents paramètres.

```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);
```

Pour un appel sortant, la méthode API complète est :

```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);
```

Le raccourci de ressource est `client.calls.create(body)`. Les deux méthodes utilisent la même API et conservent les mêmes réponses et autorisations.

| Méthode SDK | Opération REST | Commande 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>` |

Utilisez l’autocomplétion de votre éditeur pour découvrir les méthodes. Consultez [Outils MCP et portées](/fr/mcp/tools-and-scopes) pour utiliser les fonctions correspondantes dans un assistant IA.

## Télécharger les réponses binaires

Les opérations audio renvoient un `ArrayBuffer`, sans enveloppe JSON `data`. Par exemple, téléchargez un aperçu Full Duplex existant au format 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));
```

Choisissez un ID de voix Full Duplex opaque dans le catalogue. Votre espace doit avoir accès au mode vocal correspondant. Un aperçu absent produit une erreur API ; cette requête ne crée pas de nouvel échantillon.

## Téléverser des fichiers

Passez un corps `FormData` aux opérations acceptant les fichiers multipart. Le SDK définit le type de contenu multipart et sa délimitation :

```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,
});
```

Les avatars acceptent PNG, JPEG ou WebP, avec une taille maximale de 1 Mo à l’envoi. Respectez les exigences de chaque opération. Les commandes CLI équivalentes pour ces deux exemples sont :

```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
```

## Adapter une requête

Les options de requête sont le dernier argument, après les paramètres de la méthode. Les méthodes générées de `client.api` reçoivent d’abord l’entrée groupée, puis les options. Les raccourcis de ressources ont des nombres d’arguments différents. Une liste reçoit par exemple la requête, puis les options :

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

Pour modifier un assistant, placez les options après l’ID et le corps ; pour télécharger de l’audio, après l’ID et la requête ; pour `account.me()`, comme seul argument. Une requête vide conserve les valeurs par défaut. Remplacez les ID avant l’exécution ; modifier un assistant change sa configuration.

```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);
```

Voir [Configuration et erreurs](/fr/sdk/reference) pour l’annulation, les classes d’erreur et les répétitions.


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