Introducción a la API - OurAiCalling

OurAiCalling expone una API REST bajo el dominio de tu plataforma. Todo lo que puedes hacer desde el Panel —gestionar asistentes, iniciar llamadas, ejecutar campañas, leer transcripciones— está disponible mediante programación.

URL base

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

app.famulor.io es la plataforma alojada. Si inicias sesión en un dominio de tenant de marca blanca, usa ese dominio: la API funciona bajo él con la marca del tenant y se aplican las mismas rutas.

Autenticación

Todas las solicitudes requieren un token Bearer en el encabezado Authorization. Se aceptan dos tipos de tokens:

Claves de API (fam_...) — créalas en Configuración → Claves de API. La clave completa se muestra una única vez al crearla; después solo se guarda un hash. Opcionalmente puedes restringir las claves a permisos concretos (por ejemplo, assistants:read, calls:write, campaigns:write, dashboards:read, dashboards:write, leads:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read) y asignarles una fecha de caducidad. Una clave sin restricciones de permisos tiene acceso completo; un permiso *:write incluye automáticamente el *:read correspondiente. Es la mejor opción para integraciones servidor a servidor. Los endpoints del Panel también aceptan calls:read/write, así que los clientes OAuth que usan los cuatro permisos estándar siguen siendo compatibles.
Tokens de acceso OAuth 2.0 (fam_at_...) — se emiten a través del flujo OAuth de la plataforma (authorization code + PKCE, registro dinámico de clientes). Tienen permisos acotados y vida corta (1 hora, con refresh tokens). Son la mejor opción para apps de terceros que actúan en nombre de un usuario.

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

Trata las claves de API como contraseñas. Nunca las incluyas en código del lado del cliente — para casos de uso en el navegador, usa el flujo OAuth.

Estructura de la respuesta

Todos los endpoints devuelven una estructura JSON coherente. Las respuestas correctas envuelven el payload en data (más un meta opcional):

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

Qué devuelve la API y qué no

La API REST y el endpoint MCP devuelven la misma vista deliberadamente curada de los datos de tu espacio de trabajo: todo lo que necesitas para construir, nada sobre cómo funciona la plataforma internamente. No se incluye en ninguna respuesta:

Identificadores de infraestructura: identificadores de sesión de medios, sala, troncal, enrutamiento y operador de la pila de telefonía subyacente.
Rutas de almacenamiento internas: las grabaciones se sirven como URL firmada con caducidad (GET /calls/{id}/recording), nunca como ruta del bucket.
Costes de plataforma e interioridades de facturación: costes de proveedores, contadores de tokens/caracteres/segundos y estado de los cargos. Tu propio consumo se informa en las unidades que se te facturan: minutos y créditos (GET /balance, GET /transactions).
Detalles internos de modelos: qué modelo evaluó una llamada o escribió el resumen. Se devuelven el veredicto, la puntuación y el resumen, no el motor que los generó.
Secretos: contraseñas, tokens y credenciales de operador nunca se pueden volver a leer una vez guardados; como máximo obtienes una pista enmascarada.
Diagnóstico operativo: los eventos internos de llamada (conmutaciones de componentes, errores de sesión, registros de consumo) se filtran de los eventos de GET /calls/{id}.

Todo lo demás está a tu disposición: transcripciones, resúmenes, veredictos de análisis, campos extraídos, puntuaciones de QA, contactos, campañas, números y la configuración completa del asistente.

Paginación

Los endpoints de listado se paginan con los parámetros de consulta limit y offset:

Parámetro	Valor por defecto	Máximo	Descripción
`limit`	`50`	`200`	Tamaño de página
`offset`	`0`	—	Elementos a omitir

El meta.pagination.total de la respuesta indica el número total de coincidencias (sin tener en cuenta limit/offset), así que puedes seguir paginando hasta que offset + limit >= total:

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

Errores

Los fallos devuelven una estructura de error con un code estable y legible por máquina, y un message legible para humanos:

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

Estado	Código	Significado
`400`	`invalid_request`	Cuerpo o parámetros de la solicitud no válidos
`401`	`unauthorized`	Token ausente, no válido, caducado o revocado
`403`	`forbidden`	Falta el permiso necesario, o tu plan no incluye esta función
`404`	`not_found`	Recurso no encontrado (o no te pertenece)
`409`	`conflict`	El recurso está en un estado conflictivo (por ejemplo, detener una campaña que no está en ejecución)
`429`	`rate_limited`	Se superó el límite de solicitudes — reduce la frecuencia y vuelve a intentarlo
`500`	`internal_error`	Error inesperado del servidor

Límites de solicitudes

Se aplican límites de uso razonable por cuenta. Si los superas, la API responde con 429 Too Many Requests; reduce la frecuencia y vuelve a intentarlo con un retraso exponencial. Los límites publicados por plan se documentarán aquí.

MCP: usa la API como herramientas de IA

Todo lo que aparece en esta referencia también está disponible a través del endpoint MCP de la plataforma (Model Context Protocol, HTTP en streaming):

https://app.famulor.io/mcp

Conecta Claude, ChatGPT, Cursor o cualquier cliente MCP y usa las mismas funciones como herramientas de IA: los mismos servicios, la misma validación (límites del plan, catálogo de modelos, comprobaciones DNC) y el mismo modelo de permisos (claves de API u OAuth). Requiere la función de plan Connect AI / MCP. Guía de configuración completa: endpoint MCP. Conexión rápida — Claude y ChatGPT descubren la autenticación automáticamente (OAuth); otros clientes pueden pasar una clave de API como encabezado Bearer estático:

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"]
    }
  }
}

Herramientas MCP disponibles

Área	Herramientas
Asistentes	`list_assistants`, `get_assistant`, `create_assistant`, `update_assistant`, `delete_assistant`
Voces	`get_voices`
Llamadas	`list_calls`, `get_call`, `make_call`
Historial	`list_history`, `get_email_history_item`
Configuración del espacio de trabajo	`list_email_senders`, `get_custom_domain`, `add_custom_domain`, `verify_custom_domain`, `remove_custom_domain`, `get_memory_settings`, `update_memory_settings`
Campañas	`list_campaigns`, `get_campaign`, `create_campaign`, `update_campaign`, `delete_campaign`, `start_campaign`, `stop_campaign`
Leads	`list_leads`, `add_lead`, `add_leads`, `delete_lead`
Números de teléfono	`list_phone_numbers`, `search_phone_numbers`, `buy_phone_number`, `release_phone_number`, `assign_phone_number`
Troncales SIP	`list_sip_trunks`, `get_sip_trunk`, `create_sip_trunk`, `delete_sip_trunk`
Bases de conocimiento	`list_knowledge_bases`, `get_knowledge_base`, `create_knowledge_base`, `delete_knowledge_base`, `add_document`
Cuenta y facturación	`get_balance`, `get_me`, `get_usage_summary`

​URL base

​Autenticación

​Estructura de la respuesta

​Qué devuelve la API y qué no

​Paginación

​Errores

​Límites de solicitudes

​MCP: usa la API como herramientas de IA

​Herramientas MCP disponibles

URL base

Autenticación

Estructura de la respuesta

Qué devuelve la API y qué no

Paginación

Errores

Límites de solicitudes

MCP: usa la API como herramientas de IA

Herramientas MCP disponibles