Démarrage rapide du SDK

Ce guide commence par une lecture. Une fois la connexion établie, vous pouvez lancer un appel sortant depuis un script distinct.

Installer le paquet

Dans votre projet serveur, exécutez :

npm install famulor-sdk

Utilisez Node.js 22 ou une version ultérieure. Le paquet prend en charge TypeScript et JavaScript, avec ESM import et CommonJS require.

Créer une clé API d’espace de travail

Sélectionnez l’espace de travail voulu dans Famulor, ouvrez Paramètres → API & MCP et créez une clé. Copiez sa valeur complète tant qu’elle est visible ; elle n’est affichée qu’une fois.L’espace de travail doit disposer d’Accès API via son forfait ou un module complémentaire. Une clé créée dans le tableau de bord possède toutes les portées. Pour limiter les autorisations, consultez Sécurité des clés API.

Stocker la clé sur votre serveur

Pour le développement local, placez la clé dans un fichier .env :

FAMULOR_API_KEY=fam_your_workspace_key

Ajoutez .env à .gitignore. Pour une application hébergée, utilisez le gestionnaire de secrets ou les paramètres d’environnement serveur de votre hébergeur. Vous fournissez explicitement la clé au SDK ; il ne charge pas les fichiers .env et ne sélectionne pas automatiquement un espace de travail.

Lire vos assistants

Enregistrez ce fichier sous le nom 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);
}

Exécutez-le avec la prise en charge des fichiers d’environnement de Node :

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

Une liste vide confirme la connexion lorsque votre espace de travail ne contient pas encore d’assistants. En cas d’échec, consultez Dépannage.

Lancer un appel sortant

Choisissez un assistant actif auquel un numéro compatible avec les appels sortants est attribué. Utilisez une destination que vous souhaitez appeler au format E.164, par exemple +4915123456789.

Le script suivant lance un véritable appel sortant et peut consommer des crédits. Remplacez les deux arguments par votre ID d’assistant et la destination voulue.

Enregistrez ce fichier sous le nom 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 réponse contient l’ID de l’appel créé et son statut initial. Une création réussie ne signifie pas que le destinataire a répondu. Conservez l’ID et consultez le résultat plus tard :

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

Privilégiez le webhook de fin de conversation de l’assistant pour le résultat final ; voir Webhooks. Les commandes CLI équivalentes sont :

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

Utiliser votre propre domaine

Pour un espace de travail en marque blanche, utilisez le domaine de connexion et ajoutez /api/v1 :

import { Famulor } from 'famulor-sdk';

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

Chaque clé API appartient à un seul espace de travail. Utilisez une clé et un client distincts pour chacun. Un domaine personnalisé n’ajoute pas d’autorisations et ne modifie pas les chemins de l’API. Poursuivez avec Utiliser le SDK pour la pagination et l’accès complet à l’API, ou Configuration et erreurs pour traiter les requêtes de manière fiable.

​Lancer un appel sortant

​Utiliser votre propre domaine

Lancer un appel sortant

Utiliser votre propre domaine