> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Iniciar llamada

> Ejecuta la tool de voz `voice.calls` usando la acción `startCall`.

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

<Info>
  Autenticación requerida: API Key con permiso <code>tools:execute</code> y
  header <code>X-Workspace-Id</code>.
</Info>

## Ejecutar con el SDK

<CodeGroup>
  ```ts theme={null}
  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);

  ```

  ```bash theme={null}
  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"
        }
      }
    }'
  ```
</CodeGroup>

## Parámetros clave

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

## Respuesta esperada

```json theme={null}
{
  "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

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

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