Realizar llamadas de IA y gestionar Astra a través de la API

La API puede configurar y publicar Astra (tu agente de IA), conectarle un número y hacer que realice llamadas salientes: POST /v1/api/calls hace que tu agente publicado marque un número, mantenga la conversación y registre la llamada — con grabación, transcripción y resumen — en la línea de tiempo del contacto en tu bandeja de entrada, facturada en créditos de IA exactamente como una llamada entrante respondida por IA.

Antes de empezar

• Tu clave API necesita los alcances correctos — las opciones en Configuración → API de desarrollador: Gestionar agente de IA (agent:manage) para la configuración del agente y el enrutamiento de números, y Realizar llamadas de IA (calls:place) para las llamadas salientes. Las claves de acceso completo incluyen ambas. Consulta Obtener tu clave API de Ody.
• Las llamadas salientes requieren un plan activo, un agente publicado y habilitado, y al menos un número activo en tu espacio de trabajo.
• Los créditos funcionan exactamente como de costumbre: 100 créditos por llamada respondida por IA, llamadas de menos de 15 segundos gratuitas, y cada plan incluye 1,000 créditos al mes. Consulta Créditos y uso de Astra.

Configurar y publicar tu agente

GET /v1/api/agent devuelve la configuración del agente más tu uso de créditos del ciclo actual — útil para verificar el presupuesto antes de un lote de llamadas. PATCH /v1/api/agent lo actualiza: name, greeting, tone, voice, language, timezone, inHoursAction/offHoursAction (agent, voicemail, app, o forward), enabled, y jobs. Solo los campos que envías cambian, excepto jobs, que se reemplaza por completo cuando se proporciona:

curl -X PATCH https://api.ody.co/v1/api/agent \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "greeting": "Thanks for calling Acme Plumbing!",
    "tone": "Friendly",
    "jobs": [{"name": "Take a message", "instructions": "Collect the name, number, and reason for calling."}]
  }'

Los cambios se guardan como un borrador — el mismo borrador que verías en la pantalla del agente de IA en la aplicación. Publícalo con:

curl -X POST https://api.ody.co/v1/api/agent/publish \
  -H "Authorization: Bearer ody_live_…"

Conectar un número al agente

POST /v1/api/numbers/{number}/connect enruta uno de tus números al agente para que responda las llamadas entrantes (codifica la + en URL como %2B):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/connect" \
  -H "Authorization: Bearer ody_live_…"

Para enrutarlo de vuelta a tu equipo, usa …/disconnect con un mode de app (hacer sonar a tu equipo — el predeterminado), voicemail, o forward (con un número forwardTo):

curl -X POST "https://api.ody.co/v1/api/numbers/%2B15125550123/disconnect" \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"app"}'

Realizar una llamada saliente de IA

POST /v1/api/calls hace que tu agente publicado realice una llamada saliente y mantenga la conversación:

curl https://api.ody.co/v1/api/calls \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550199"}'

• to es obligatorio (E.164). from es opcional — Ody prefiere tu número conectado al agente, luego tu primer número activo; pasa from para elegir una línea específica que poseas.
• Los destinos internacionales siguen las reglas habituales de llamadas internacionales de tu espacio de trabajo — consulta Llamadas internacionales y límites.
• Cuando la llamada termina, aparece en la línea de tiempo del contacto en tu bandeja de entrada con una grabación, transcripción y resumen — la misma tarjeta "Agente de IA manejó esta llamada" que una llamada entrante de IA.
• Facturación: 100 créditos cuando la llamada es respondida, gratuita si dura menos de 15 segundos — y una llamada que nunca se responde es siempre gratuita.

Puedes tomar el control en cualquier momento

Todo lo que se hace a través de la API es el estado real de tu cuenta — no un entorno de pruebas de desarrollador separado. El agente que tu código publica es el que aparece en la pantalla de Agente de IA; el número que conecta está en Configuración → Números; las llamadas que realiza llegan a tu bandeja de entrada compartida. Esto significa que puedes intervenir cuando quieras: editar el saludo en la aplicación, responder en un hilo tú mismo o hacer clic en las opciones de enrutamiento de un número para enviar las llamadas de vuelta a tu equipo — sin necesidad de API.

Desde un asistente de IA (MCP)

Los asistentes de IA conectados obtienen los mismos poderes que las herramientas MCP: get_agent, configure_agent (pasa publish: true para publicarlo en un solo paso), connect_agent_to_number, y place_call. Consulta Conectar herramientas de IA con MCP.

Modo de prueba

Con una clave ody_test_…, POST /calls devuelve una llamada simulada (un ID sim_…, nada marcado, no se usan créditos) y POST /agent/publish se simula (tu configuración permanece como borrador). Los borradores guardados a través de PATCH /agent son reales en ambos tipos de clave. Consulta Construir de forma segura con el modo de prueba.

Artículos relacionados

• Conoce a Astra, tu recepcionista de IA
• Créditos y uso de Astra
• Comprar números y registrar mensajes de texto a través de la API
• Conectar herramientas de IA con MCP