Introduction à l'API - OurAiCalling

OurAiCalling expose une API REST sous le domaine de votre plateforme. Tout ce que vous pouvez faire depuis le tableau de bord — gérer les assistants, lancer des appels, exécuter des campagnes, consulter les transcriptions — est disponible par voie programmatique.

URL de base

https://app.famulor.io/api/v1

app.famulor.io est la plateforme hébergée. Si vous vous connectez sur un domaine locataire en marque blanche, utilisez ce domaine : l’API s’y exécute avec l’image de marque du locataire et les mêmes chemins s’appliquent.

Authentification

Toutes les requêtes nécessitent un jeton Bearer dans l’en-tête Authorization. Deux types de jetons sont acceptés :

Clés API (fam_...) — créez-les depuis Paramètres → Clés API. La clé complète ne s’affiche qu’une seule fois, au moment de la création ; seul un hachage est conservé ensuite. Vous pouvez éventuellement restreindre une clé à certaines portées (par exemple assistants:read, calls:write, campaigns:write, dashboards:read, dashboards:write, leads:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read) et lui définir une date d’expiration. Une clé sans restriction de portée dispose d’un accès complet ; une portée *:write inclut automatiquement le *:read correspondant. Idéal pour les intégrations serveur à serveur. Les endpoints du tableau de bord acceptent aussi calls:read/write, si bien que les clients OAuth utilisant les quatre portées standards restent compatibles.
Jetons d’accès OAuth 2.0 (fam_at_...) — émis via le flux OAuth de la plateforme (authorization code + PKCE, enregistrement dynamique des clients). Portée limitée et durée de vie courte (1 heure, avec jetons de rafraîchissement). Idéal pour les applications tierces agissant pour le compte d’un utilisateur.

curl https://app.famulor.io/api/v1/assistants \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Traitez vos clés API comme des mots de passe. Ne les intégrez jamais dans du code côté client — pour les cas d’usage navigateur, utilisez plutôt le flux OAuth.

Enveloppe de réponse

Chaque endpoint renvoie une enveloppe JSON cohérente. Les réponses réussies enveloppent la charge utile dans data (avec un meta optionnel) :

{
  "data": [ { "id": "…", "name": "Support Agent" } ],
  "meta": { "pagination": { "limit": 50, "offset": 0, "total": 1 } }
}

Ce que l’API renvoie — et ce qu’elle ne renvoie pas

L’API REST et le point de terminaison MCP renvoient la même vue délibérément sélectionnée des données de votre espace de travail : tout ce dont vous avez besoin pour développer, rien sur le fonctionnement interne de la plateforme. Absent de toutes les réponses :

Identifiants d’infrastructure — identifiants de session média, de salle, de trunk, de routage et d’opérateur de la couche téléphonie sous-jacente.
Chemins de stockage internes — les enregistrements sont fournis via une URL signée à durée limitée (GET /calls/{id}/recording), jamais sous forme de chemin de bucket.
Coûts de la plateforme et détails de facturation — coûts des fournisseurs, compteurs de tokens/caractères/secondes et suivi des débits. Votre propre consommation est exprimée dans les unités facturées : minutes et crédits (GET /balance, GET /transactions).
Détails internes des modèles — quel modèle a évalué un appel ou rédigé le résumé. Le verdict, le score et le résumé sont renvoyés ; le moteur qui les produit ne l’est pas.
Secrets — mots de passe, jetons et identifiants d’opérateur ne sont jamais relisibles après enregistrement ; vous obtenez au mieux un indice masqué.
Diagnostics d’exploitation — les événements d’appel internes (bascules de composants, erreurs de session, écritures de consommation) sont filtrés des événements de GET /calls/{id}.

Tout le reste vous est ouvert : transcriptions, résumés, verdicts d’analyse, champs extraits, scores QA, contacts, campagnes, numéros et la configuration complète de l’assistant.

Pagination

Les endpoints de liste se paginent avec les paramètres de requête limit et offset :

Paramètre	Par défaut	Max	Description
`limit`	`50`	`200`	Taille de page
`offset`	`0`	—	Nombre d’éléments à ignorer

Le meta.pagination.total de la réponse indique le nombre total de résultats (indépendamment de limit/offset), ce qui vous permet de paginer jusqu’à ce que offset + limit >= total :

curl "https://app.famulor.io/api/v1/calls?limit=100&offset=200" \
  -H "Authorization: Bearer fam_XXXXXXXXXXXX"

Erreurs

Les échecs renvoient une enveloppe d’erreur avec un code stable et lisible par une machine, ainsi qu’un message lisible par un humain :

{
  "error": {
    "code": "invalid_request",
    "message": "\"to_number\" is required (E.164 format, e.g. +4930123456)."
  }
}

Statut	Code	Signification
`400`	`invalid_request`	Corps de requête ou paramètres invalides
`401`	`unauthorized`	Jeton manquant, invalide, expiré ou révoqué
`403`	`forbidden`	Portée manquante, ou fonctionnalité non incluse dans votre plan
`404`	`not_found`	Ressource introuvable (ou qui ne vous appartient pas)
`409`	`conflict`	La ressource est dans un état conflictuel (par exemple, arrêter une campagne qui n’est pas en cours)
`429`	`rate_limited`	Limite de débit dépassée — patientez avant de réessayer
`500`	`internal_error`	Erreur serveur inattendue

Limites de débit

Des limites de débit d’utilisation équitable s’appliquent par compte. Si vous les dépassez, l’API répond 429 Too Many Requests ; patientez puis réessayez avec un backoff exponentiel. Les limites par plan seront documentées ici dès leur publication.

MCP — utiliser l’API comme outils IA

Tout ce qui figure dans cette référence est également exposé via l’endpoint MCP de la plateforme (Model Context Protocol, streamable HTTP) :

https://app.famulor.io/mcp

Connectez Claude, ChatGPT, Cursor ou n’importe quel client MCP, et utilisez les mêmes fonctionnalités en tant qu’outils IA : mêmes services, même validation (limites de plan, catalogue de modèles, contrôles DNC) et même modèle d’autorisation (clés API ou OAuth). Nécessite la fonctionnalité de plan Connect AI / MCP. Guide de configuration complet : Endpoint MCP. Connexion rapide — Claude et ChatGPT détectent automatiquement l’authentification (OAuth) ; les autres clients peuvent transmettre une clé API via un en-tête Bearer statique :

claude mcp add --transport http voice-ai https://app.famulor.io/mcp \
  --header "Authorization: Bearer fam_XXXXXXXXXXXX"

{
  "mcpServers": {
    "voice-ai": {
      "url": "https://app.famulor.io/mcp",
      "headers": { "Authorization": "Bearer fam_XXXXXXXXXXXX" }
    }
  }
}

{
  "mcpServers": {
    "voice-ai": {
      "command": "npx",
      "args": ["mcp-remote", "https://app.famulor.io/mcp"]
    }
  }
}

Outils MCP disponibles

Domaine	Outils
Assistants	`list_assistants`, `get_assistant`, `create_assistant`, `update_assistant`, `delete_assistant`
Voix	`get_voices`
Appels	`list_calls`, `get_call`, `make_call`
Historique	`list_history`, `get_email_history_item`
Paramètres de l’espace de travail	`list_email_senders`, `get_custom_domain`, `add_custom_domain`, `verify_custom_domain`, `remove_custom_domain`, `get_memory_settings`, `update_memory_settings`
Campagnes	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign`, `start_campaign`, `stop_campaign`
Leads	`list_leads`, `add_lead`, `add_leads`, `delete_lead`
Numéros de téléphone	`list_phone_numbers`, `search_phone_numbers`, `buy_phone_number`, `release_phone_number`, `assign_phone_number`
Trunks SIP	`list_sip_trunks`, `get_sip_trunk`, `create_sip_trunk`, `delete_sip_trunk`
Bases de connaissances	`list_knowledge_bases`, `get_knowledge_base`, `create_knowledge_base`, `delete_knowledge_base`, `add_document`
Compte et facturation	`get_balance`, `get_me`, `get_usage_summary`

​URL de base

​Authentification

​Enveloppe de réponse

​Ce que l’API renvoie — et ce qu’elle ne renvoie pas

​Pagination

​Erreurs

​Limites de débit

​MCP — utiliser l’API comme outils IA

​Outils MCP disponibles

URL de base

Authentification

Enveloppe de réponse

Ce que l’API renvoie — et ce qu’elle ne renvoie pas

Pagination

Erreurs

Limites de débit

MCP — utiliser l’API comme outils IA

Outils MCP disponibles