Iniciar llamada - Agents Studio Docs

Las llamadas salientes se orquestan con la tool voice.calls. Usa la acción startCall para marcar inmediatamente a la persona usuaria.

Autenticación requerida: API Key con permiso tools:execute y header X-Workspace-Id.

Ejecutar con el SDK

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
baseUrl: process.env.API_BASE_URL!,
workspaceId: process.env.WORKSPACE_ID!,
apiKey: process.env.API_KEY!,
});

const response = await client.tools.execute(
"voice.calls",
{
agentId: "11111111-2222-3333-4444-555555555555",
action: "startCall",
args: {
to: "+525500000000",
metadata: {
reason: "confirmar cita",
customerId: "cust-789",
},
},
},
{
idempotencyKey: `call-${Date.now()}`,
}
);

console.log(response.result.callId);

curl --request POST \
  --url "$API_BASE_URL/v1/tools/voice.calls/execute" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: call-$(date +%s)" \
  --data '{
    "agentId": "11111111-2222-3333-4444-555555555555",
    "action": "startCall",
    "args": {
      "to": "+525500000000",
      "metadata": {
        "reason": "confirmar cita",
        "customerId": "cust-789"
      }
    }
  }'

Parámetros clave

agentId: agente de voz habilitado para usar la tool.
action: debe ser exactamente startCall.
args.to: número en formato E.164.
args.metadata: datos opcionales que se propagan a la llamada.
Header Idempotency-Key: evita duplicados en reintentos.

Respuesta esperada

{
  "status": "ok",
  "result": {
    "callId": "call_01hb7t5y7z9m0j3g5n42w0j9p2",
    "agentId": "11111111-2222-3333-4444-555555555555",
    "action": "startCall"
  },
  "metadata": {
    "provider": "voice.calls",
    "triggeredAt": "2025-10-30T19:21:14.610Z"
  }
}

Errores comunes

400: payload inválido o acción distinta a startCall.
401/403: credenciales inexistentes o sin permisos.
409: llamada duplicada detectada por la clave de idempotencia.
429: límite de ejecución de tools excedido.
500: error interno.

Para seguir el estado de la llamada suscríbete a los eventos descritos en Notificaciones → Configurar webhook.