--- title: "Crear una llamada de voz" description: "Inicia una llamada saliente con una secuencia de voz publicada o una definición en línea a través de la API, inspecciona su resultado y conoce la vista previa de CLI y MCP." canonical: "https://bird.com/es-es/documentacion/guides/voice/create-calls" --- # Crear una llamada de voz > **Warning:** Voice sequences are in preview. Steps, entry data, and the sequence definition format can change in ways that break existing sequences and API requests. Usa [`POST /v1/voice/calls`](/docs/api/reference/create-voice-call) para llamar a un número de teléfono e iniciar una secuencia publicada, o una definición de secuencia enviada con la solicitud, cuando el destinatario conteste. La solicitud realiza una llamada real; se aplican los cargos habituales de llamada. **Vista previa de CLI y MCP:** Estas interfaces requieren un cliente compatible. Comprueba que tu servidor MCP exponga `voice_calls_create`, o ejecuta `bird voice --help` para listar los comandos de tu CLI. Comprueba si hay versiones más recientes con `bird update --check` y consulta [Instalación de CLI](/docs/cli). Si la herramienta o el comando no está disponible, usa la API HTTP o los SDK. En la vista previa, CLI y MCP preparan la misma llamada para que una persona la revise y ejecute en el navegador. El agente recibe el resultado de aceptación registrado después de que la persona ejecuta la solicitud. ## Antes de empezar Prepara estos recursos en el mismo espacio de trabajo: - Una secuencia para ejecutar: una [secuencia habilitada y no archivada con una publicación activa](/docs/guides/voice/sequences/publishing) creada en el panel, o una definición completa enviada con la solicitud. - Una [clave API](/docs/api/authentication) para solicitudes HTTP, o un inicio de sesión OAuth para CLI y MCP, con permisos de `voice_management:write` y `voice:write`. - Un número de llamada que el espacio de trabajo pueda presentar, como un [identificador de llamada](/docs/guides/voice/caller-ids) propio o verificado, y un [país de destino](/docs/guides/voice/destinations) habilitado. Usa preferiblemente un número del país del destinatario: algunas redes móviles rechazan una llamada que presenta un identificador de llamada extranjero. - Un destinatario que controles para la primera llamada. El objeto `sequence` acepta exactamente uno de `sequence.id` o `sequence.definition`. Ambos también necesitan `entry_node_id`, el paso **Start call** donde comienza la llamada, y `trigger_data`, un objeto que coincida con el esquema de datos de esa entrada. Usa `{}` cuando la entrada acepte datos vacíos. La [referencia de Create Call](/docs/api/reference/create-voice-call) documenta los límites de solicitud y el tiempo de espera de timbre opcional. ## Llamar a una secuencia creada en el panel Usa `sequence.id` para ejecutar una secuencia que [creaste](/docs/guides/voice/sequences/editor) y [publicaste](/docs/guides/voice/sequences/publishing) en el panel. Create Call siempre ejecuta su publicación activa. 1. Abre la secuencia en [**Sequences**](https://bird.com/dashboard/w/voice/sequences). 2. En **How to run this sequence**, selecciona **More details** junto a **Create a call**. 3. Si la secuencia tiene varias entradas, elige el **Call trigger** con el que iniciar. 4. Copia la solicitud. Contiene el ID de secuencia y el ID de entrada. Guarda el cuerpo de la solicitud como `call.json`, reemplazando los números de ejemplo con los tuyos: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "id": "YOUR_SEQUENCE_ID", "entry_node_id": "YOUR_ENTRY_NODE_ID", "trigger_data": {} } } ``` Rellena `trigger_data` con los campos que la entrada declara, incluidos objetos anidados y arrays. Create Call no acepta versiones históricas, borradores ni modo de prueba. Para probar un borrador guardado, usa los controles de [Realizar una llamada](/docs/guides/voice/sequences/testing) del panel. ## Ejecutar una secuencia en línea Usa `sequence.definition` para enviar una secuencia completa con la llamada. Bird la ejecuta una vez y no la guarda, por lo que la llamada no tiene ID de secuencia. Una definición en línea es adecuada para flujos que tu aplicación genera por llamada. Una definición en línea debe superar las mismas comprobaciones que la publicación de una secuencia. Su ejecución puede ejecutar como máximo 16 comandos, incluidos los prompts de recopilación; una llamada que necesite un 17.º termina con el error de traza `call_limit`. La [referencia de nodos](/docs/guides/voice/sequences/node-reference) enumera cada paso que puedes usar, con sus campos y resultados. Para partir de un flujo funcional, constrúyelo y publícalo en el panel, abre la secuencia y selecciona **Copy JSON** en **Definition JSON** bajo **Published version**. Este `call.json` pide al destinatario que pulse 1 para horario de atención o 2 para indicaciones. El silencio y cualquier otra tecla terminan la ejecución con sus propias razones de salida: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "entry_node_id": "start", "trigger_data": {}, "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "start", "type": "trigger.start_call", "type_version": 1, "config": {}, "input": {}, "connections": { "event": { "node_id": "menu", "port": "input" } } }, { "id": "menu", "type": "voice.gather", "type_version": 1, "config": {}, "input": { "prompts": [ { "type": "say", "text": "Press 1 for opening hours, or 2 for directions.", "language": "en" } ], "max_digits": 1, "timeout_seconds": 5, "inter_digit_timeout_seconds": 2, "finish_on_key": "#", "private": false, "matches": { "hours": "1", "directions": "2" } }, "connections": { "hours": { "node_id": "hours", "port": "input" }, "directions": { "node_id": "directions", "port": "input" }, "timeout": { "node_id": "no_input", "port": "input" }, "fallback": { "node_id": "other_input", "port": "input" } } }, { "id": "hours", "type": "voice.say", "type_version": 1, "config": {}, "input": { "text": "We are open Monday through Friday, nine to five.", "language": "en" }, "connections": { "next": { "node_id": "done", "port": "input" } } }, { "id": "directions", "type": "voice.say", "type_version": 1, "config": {}, "input": { "text": "Find directions on your appointment confirmation.", "language": "en" }, "connections": { "next": { "node_id": "done", "port": "input" } } }, { "id": "done", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "information_played" }, "input": { "output": {} } }, { "id": "no_input", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "no_input" }, "input": { "output": {} } }, { "id": "other_input", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "unrecognized_input" }, "input": { "output": {} } } ] } } } ``` El `connections` de cada nodo asigna un resultado al siguiente nodo. `matches` del menú nombra sus opciones, y `connections` usa los mismos nombres junto con los resultados integrados `timeout` y `fallback`. ### Personalizar una secuencia en línea Declara los campos que envías en `data_schema` de la entrada y luego léelos como `trigger.data.` en un valor `$expr`. Esta llamada saluda al destinatario por su nombre y confirma o señala su cita: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "entry_node_id": "start", "trigger_data": { "appointment_id": "apt_2048", "customer_name": "Sam", "appointment_time": "Tuesday at 10 AM" }, "definition": { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "start", "type": "trigger.start_call", "type_version": 1, "config": { "data_schema": { "type": "object", "additionalProperties": false, "required": ["appointment_id", "customer_name", "appointment_time"], "properties": { "appointment_id": { "type": "string", "minLength": 1 }, "customer_name": { "type": "string", "minLength": 1 }, "appointment_time": { "type": "string", "minLength": 1 } } } }, "input": {}, "connections": { "event": { "node_id": "confirm_menu", "port": "input" } } }, { "id": "confirm_menu", "type": "voice.gather", "type_version": 1, "config": {}, "input": { "prompts": [ { "type": "say", "text": { "$template": [ "Hello ", { "$expr": "trigger.data.customer_name" }, ". Press 1 to confirm your appointment on ", { "$expr": "trigger.data.appointment_time" }, ", or 2 if you need help." ] }, "language": "en" } ], "max_digits": 1, "timeout_seconds": 7, "inter_digit_timeout_seconds": 2, "finish_on_key": null, "private": false, "matches": { "confirm": "1", "help": "2" } }, "connections": { "confirm": { "node_id": "confirmed", "port": "input" }, "help": { "node_id": "help_requested", "port": "input" }, "timeout": { "node_id": "no_response", "port": "input" }, "fallback": { "node_id": "no_response", "port": "input" } } }, { "id": "confirmed", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "appointment_confirmed" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } }, { "id": "help_requested", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "appointment_help_requested" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } }, { "id": "no_response", "type": "logic.exit", "type_version": 1, "config": { "status": "failed", "reason": "appointment_no_response" }, "input": { "output": { "appointment_id": { "$expr": "trigger.data.appointment_id" } } } } ] } } } ``` `status` y `reason` de cada salida separan una confirmación, una solicitud de ayuda y la ausencia de respuesta. Un objeto `trigger_data` que no coincide con `data_schema` falla la validación, con su ubicación en `/sequence/trigger_data`, y no se realiza ninguna llamada. ## Envía la solicitud Elige uno de los métodos de solicitud a continuación para el `call.json` que guardaste. Elige una clave de idempotencia única y nueva una sola vez para esta llamada prevista. Conserva esa clave y la entrada original para reintentos o recuperación de confirmación. Elige otra clave cuando quieras realizar una nueva llamada independiente, después de resolver cualquier resultado desconocido de la llamada original. Para los ejemplos de shell, establece `IDEMPOTENCY_KEY` con el valor que elijas antes de enviar. Los ejemplos se detienen si no está definido o está vacío; no generan otra clave al repetirse. Para HTTP, establece `BIRD_API_KEY` con tu clave y `BIRD_API_URL` con su [URL base regional](/docs/api/regions), como `https://eu1.platform.bird.com` para una clave `eu1`, y luego envía la solicitud: ```bash curl --request POST "$BIRD_API_URL/v1/voice/calls" \ --header "Authorization: Bearer $BIRD_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \ --data-binary @call.json ``` Para la vista previa de [CLI](/docs/cli), inicia sesión con ambos permisos de escritura y prepara la llamada usando el mismo archivo: ```bash bird auth login --scope voice_management:write --scope voice:write bird voice calls create --body-file call.json \ --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" ``` El comando imprime un enlace de revisión en el navegador y espera a que se complete. Abre el enlace, verifica el llamante, el destinatario, la secuencia y los datos de entrada, y ejecuta la solicitud tú mismo. Preparar la solicitud no realiza la llamada. Añade `--dry-run` para inspeccionar la solicitud CLI sin crear una confirmación. Si la confirmación expira, se cancela o termina sin un resultado registrado, el comando sale con `5`; sigue la [guía de reintentos](#manejo-de-errores-y-reintentos) antes de hacer otra solicitud. Para la vista previa de [MCP](/docs/ai/mcp-server), llama a `voice_calls_create` con los campos de `call.json` y un `idempotency_key` obligatorio. Reemplaza `` con la clave que elijas: ```json { "from": "+12025550100", "to": "+12025550101", "sequence": { "id": "YOUR_SEQUENCE_ID", "entry_node_id": "YOUR_ENTRY_NODE_ID", "trigger_data": {} }, "idempotency_key": "" } ``` Sigue el enlace de revisión en el navegador devuelto para ejecutar la solicitud. En el endpoint dinámico MCP, selecciona `voice_calls_create` a través de `execute`. El consentimiento OAuth otorga permisos del espacio de trabajo; la revisión en el navegador ejecuta esta llamada específica. Una respuesta `202 Accepted` confirma la admisión. La secuencia comienza después de que el destinatario contesta. Publicar una versión más nueva después de la aceptación no cambia la definición seleccionada ni los datos de entrada de esta llamada. ## Lee el resultado de aceptación Conserva `id`, `initial_leg_id` y `sequence.run_id` de la respuesta para correlación. El `id` de nivel superior identifica la llamada a través de sus tramos; `initial_leg_id` identifica su primer tramo. La respuesta es una instantánea de aceptación inmutable. Sus `started_at` y `ended_at` son `null`, los booleanos de observación son `false` y `parties` está vacío. Estos campos describen la aceptación, por lo que no se convierten en un informe de estado en tiempo real cuando repites la solicitud. Abre [**Runs**](/docs/guides/voice/sequences/runs) de la secuencia para inspeccionar el progreso. Una llamada en línea no pertenece a ninguna secuencia, así que sigue su tramo en su lugar; si falla antes de que su tramo se registre, aún no hay forma de inspeccionarla. Una vez que exista el registro de tramo, usa [`GET /v1/voice/legs/{leg_id}`](/docs/api/reference/get-voice-leg) con `initial_leg_id`, o inspecciona el [registro de llamadas](/docs/guides/voice/call-log). Leer tramos requiere el permiso `voice:read`, que `voice:write` incluye. Un tramo con `status` `rejected` fue rechazado antes de conectarse, por lo que su secuencia no se ejecutó. Sin un motivo de rechazo, el extremo remoto declinó la llamada; consulta [Llamadas rechazadas](/docs/guides/voice/call-log#rejected-calls). Con CLI, `bird voice calls get YOUR_CALL_ID` muestra la llamada y sus participantes. `bird voice legs trace YOUR_LEG_ID` muestra qué pasos se ejecutaron, los dígitos recopilados salvo que el gather sea privado, y el estado y motivo de salida. La traza está disponible poco después de que la llamada termine; hasta entonces el comando devuelve un error, así que reintenta. La secuencia de un tramo rechazado nunca se ejecutó, por lo que puede no tener traza. La aceptación no garantiza la marcación, una respuesta ni un registro de llamada legible. Una llamada que falla antes del registro puede aparecer en el historial de ejecución sin un registro de tramo. Una llamada contestada tampoco confirma que la secuencia completó su tarea de negocio prevista. ## Manejo de errores y reintentos Para solicitudes directas HTTP, la idempotencia es opcional. Sin clave, cada solicitud acepta un nuevo intento de llamada. Los SDK generan una clave para reintentos automáticos. Para proteger reintentos entre llamadas independientes o solicitudes directas HTTP, proporciona una clave en el primer intento y reutilízala con los bytes exactos de la solicitud original. Consulta la [guía de idempotencia](/docs/guides/idempotency). Una repetición idéntica dentro de tres horas devuelve la aceptación original y `Idempotency-Replay: true`. Una entrada modificada con esa clave devuelve `409`. La autorización y el permiso de número de llamada se verifican de nuevo en la repetición. Después de la ventana de repetición, la clave puede admitir una nueva llamada, así que reconcilia el resultado original antes de reenviar. Para CLI y MCP, proporciona la clave de idempotencia en el primer intento. Repetir la misma solicitud y clave con la misma concesión OAuth devuelve la confirmación existente mientras su registro se conserva. Conserva la entrada original y el ID de confirmación. Cambiar la clave puede preparar otra llamada facturable. Si el comando CLI se interrumpe, reanuda con la entrada original, la clave y el ID de confirmación devuelto: ```bash bird voice calls create --body-file call.json \ --idempotency-key "${IDEMPOTENCY_KEY:?Set IDEMPOTENCY_KEY to the saved key for this intended call}" \ --confirmation-id YOUR_CONFIRMATION_ID ``` Para MCP, repite los argumentos originales de la herramienta, incluido el mismo `idempotency_key`, junto con el estado de solicitud devuelto. El estado identifica la confirmación y no reemplaza esos argumentos. Alternativamente, repite la misma herramienta y argumentos con el ID devuelto en los metadatos de solicitud `bird/confirmation-id`. Con MCP dinámico, repite la misma solicitud `execute` y coloca esos metadatos en ella. Reanudar lee la confirmación original y devuelve su resultado registrado cuando se completa. Una confirmación de Create Call expira después de 90 minutos. Una confirmación `pending` o `expired` sin resultado no demuestra que la llamada nunca se realizó. Inspecciona la ejecución de la secuencia original y cualquier registro de tramo antes de decidir realizar otra llamada; no crees una clave nueva para resolver un resultado desconocido. Una confirmación completada con un resultado `202` demuestra la aceptación, así que continúa con [las comprobaciones de aceptación](#lee-el-resultado-de-aceptación) para determinar el resultado de la llamada. | Síntoma | Qué verificar | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` o `422` | Lee los detalles de campo del error. Verifica el formato del número, la elegibilidad y propiedad del número de llamada, los ID de secuencia y entrada, el objeto de datos explícito y los límites de solicitud. | | `401` o `403` | Verifica tu clave API o inicio de sesión OAuth, ambos permisos de escritura requeridos y el acceso al espacio de trabajo. | | `404` | Verifica que la secuencia pertenece al espacio de trabajo seleccionado y que la creación de llamadas está disponible en el servicio regional. | | `409` | Verifica si hay un reintento con cuerpo modificado o una secuencia de producción activa no disponible. Publica o reanuda según sea necesario antes de iniciar una nueva llamada. | | `429` | Respeta la guía de reintentos de la respuesta. Si proporcionaste una clave, reutilízala para el mismo intento de llamada. | | Aceptada, luego falló | Inspecciona la ejecución y cualquier registro de tramo en busca de destino, límites, saldo o errores de ejecución antes de decidir realizar otra llamada. | ## Próximos pasos - [Referencia API de Create Call](/docs/api/reference/create-voice-call). - [Definir datos de entrada de secuencia](/docs/guides/voice/sequences/data). - [Inspeccionar ejecuciones de secuencia](/docs/guides/voice/sequences/runs). - [Recibir eventos de llamada](/docs/guides/voice/events). ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)