Migrar de Telserv a Bird

Esta guía es para integraciones que llaman a la API de socio de Telserv, V1 o V2, para comprar, enrutar y liberar números, y que ahora migran a la Bird API.

La Bird API sirve a todos los productos de Bird, así que sus operaciones de números y voz siguen las convenciones propias de Bird en lugar de las de Telserv. La mayoría de las funciones que usa tu integración tienen una llamada equivalente en Bird. Los endpoints, payloads, identificadores y la autenticación son distintos, así que planifica reescribir la integración. Donde Bird hace una tarea de forma diferente, esta guía muestra cómo.

Esta guía es un trabajo en curso. Cubre lo que Bird hace hoy y crece a medida que avanza la migración. Si una operación de Telserv que usas no aparece aquí, aún necesita alcance y trabajo antes de poder añadirse; consulta con tu contacto de migración.

Antes de empezar

• Una organización de Bird con verificación de identidad completada, que la primera compra de número requiere.
• Una clave de API con los alcances que usan las recetas: numbers con nivel de escritura para números y pedidos, compliance con nivel de escritura para las operaciones independientes de documentación de titularidad, y voice_management con nivel de escritura para trunks de SIP, números de voz y números verificados. La llamada de prueba también necesita voice:write, y la lectura de tramos de llamada necesita voice:read.
• Saldo del monedero. Los pedidos se cobran del monedero. Cuando un pedido es rechazado explica los rechazos 402 y 412.

Los números que tu integración gestiona en Telserv no necesitan comprarse de nuevo. Una vez que tus números se trasladan a tu espacio de trabajo de Bird, aparecen en GET /v1/numbers. Tu contacto de migración confirma cuándo ocurre. Para obtener el identificador nda_ de un número trasladado, búscalo con GET /v1/numbers?number=<digits> indicando los dígitos con su código de país, y guarda el id como NUMBER_ID.

Los ejemplos leen tu clave de BIRD_API_KEY y su host regional de BIRD_API_URL: https://eu1.platform.bird.com para una clave de bk_eu1_, o https://us1.platform.bird.com para una clave de bk_us1_. Las demás variables, como TRUNK_ID y NUMBER_ID, contienen un identificador de una respuesta anterior; cada paso indica cuál establece.

Qué cambia en el contrato

La Bird API rechaza un parámetro de consulta que no reconoce con 422 y E01029. Elimina de tus solicitudes los filtros exclusivos de Telserv como city en lugar de enviarlos tal cual.

Dos identificadores para un mismo número

Un número con capacidad de voz asignado a tu espacio de trabajo tiene dos registros, cada uno con su propio identificador:

• La asignación, devuelta por GET /v1/numbers. Su id empieza por nda_ para un número dedicado y por nal_ para uno compartido, y el number_id de un pedido es el identificador nda_ del número que compró. Úsala para leer, nombrar y referenciar el número, y para liberar uno dedicado.
• El registro de voz, vnu_, devuelto por GET /v1/voice/numbers. Úsalo para leer y cambiar adónde van las llamadas entrantes del número. Un número sin capacidad de voz, como un número solo de SMS, no tiene registro de voz.

Las operaciones de voz rechazan un identificador nda_ o nal_ con 422. Para encontrar el registro de voz de un número, lista los números de voz con search configurado con los dígitos del número y toma la entrada cuyo provider.number_id sea igual al id de la asignación. Enrutar un número a tu trunk SIP muestra la solicitud, y Gestión de tus números de teléfono cubre la búsqueda.

El GET /numbers/{dnisId} de Telserv se convierte en dos lecturas en Bird: la asignación para el estado y la documentación de titularidad, y el registro de voz para la ruta.

Correspondencia de operaciones de Telserv con Bird

Cada tabla lista una tarea, la llamada de Telserv que la realizaba y la llamada de Bird que la realiza ahora. Las notas debajo de cada tabla cubren lo que cambia en la solicitud o la respuesta.

Compra

• Búsqueda. country_code es obligatorio, así que una búsqueda cubre un solo país. prefix recibe los dígitos nacionales después del código de país: el prefix=3170 de Telserv pasa a ser country_code=NL&prefix=70. Filtra por código de área con prefix en lugar de city, y por number_type y capabilities en lugar de productId.
• Documentación en los resultados de búsqueda. Cada resultado incluye ownership_registration_required en lugar del filtro excludeNumbersRequireVerification. Un valor true significa que el número se factura desde la compra, pero no envía SMS ni cursa llamadas de voz entrantes o salientes hasta que se apruebe su documentación.
• Consultar un número. Se direcciona por su número E.164.
• Precios. Telserv devolvía pricing.staticPricing en las lecturas detalladas de un número y de un producto. En Bird, cada resultado de búsqueda incluye el precio para tu organización en pricing: setup_price en lugar de nrc, y recurring_price por recurring_period en lugar de mrc, con intervals_per_charge para indicar cuántos períodos cubre un cargo. Buscar y comprar un número con tu referencia describe los campos de precio.
• Comprar. Envía number y un reference opcional. El pedido se paga desde tu monedero. La mayoría de los pedidos responden 201; un pedido que espera a un operador responde 202, y lo consultas periódicamente.
• Reservar. Hacer el pedido del número lo reserva. Consulta un candidato primero y luego haz el pedido.

Números

• Listar. La lista contiene los números que tienes asignados ahora. Un número liberado que pediste en Bird sigue visible a través de su pedido en GET /v1/numbers/orders. Conciliar tus números describe los filtros.
• Leer. El estado, la documentación de titularidad y el precio están en la asignación, y la ruta está en el registro de voz. El objeto pricing de la asignación, con recurring_price por recurring_period y intervals_per_charge, reemplaza a pricing.staticPricing.mrc, y la lista también lo incluye, mientras que GET /numbers de Telserv no lo hacía.
• Modificar. name y reference están en la asignación, y la ruta está en el registro de voz. Configura un códec forzado y un límite de llamadas simultáneas en tu equipo SIP. destinationDistributionType pasa a ser priority de gateway en el trunk SIP: FailOver asigna a cada gateway un priority diferente, y RoundRobin les asigna el mismo.
• Liberar. DELETE conserva el número hasta el final del período que ya pagaste y lo libera entonces. POST …/release lo libera de inmediato. Ninguno acepta una fecha. Liberar un número muestra ambas solicitudes.

Destinos y perfiles

• Equipo SIP. Un gateway pertenece al trunk y atiende cada número enrutado hacia él, así que los números que necesitan listas de destino distintas necesitan trunks distintos. sortOrder se convierte en priority. Aplica el tiempo de timbre y las ventanas horarias en tu equipo SIP.
• Reenvío. Establece forward_to y forward_as. forward_to debe ser uno de tus números verificados; un número no verificado responde 412 con E21053. forward_as elige qué número muestra la llamada reenviada como identificador de quien llama. Un número tiene una sola ruta a la vez, así que para recurrir desde el equipo SIP a un número de teléfono, reenvía la llamada desde tu equipo SIP.
• Dejar de recibir llamadas. El número rechaza llamadas hasta que lo enrutes de nuevo. Para mantener un destino permanente en lugar de un perfil predeterminado, enruta el número a un trunk que contenga tus gateways predeterminados.
• Perfiles. distributionType pasa a ser priority: FailOver asigna a cada gateway un priority diferente, y RoundRobin les asigna el mismo. La distribución se configura por trunk, así que los números que necesitan distribución diferente necesitan trunks diferentes. El placeholder {dnis} pasa a ser {number} en destination_format, y un prefixCLIP pasa a ser el texto antes de {number} en origination_format.
• Aplicar un perfil. Un trunk se identifica por su identificador spt_, mientras que Telserv identificaba un perfil por nombre.

Documentos y datos de usuario final

• Requisitos. El catálogo de condiciones de Telserv cubría todos los productos a la vez; Bird lee un formulario cada vez. Pide los requisitos de un número con subject_kind=number, su identificador nda_ como subject_id y su country_code, o lee un formulario antes de comprar con program establecido en el tipo de número y sin subject_id. Cada entrada de fields sustituye a una condición o etiqueta de usuario final de Telserv: su key es la clave bajo la que respondes, y data_type document marca una que requiere un archivo.
• Documentos. Sube el archivo como multipart/form-data en lugar de un fileContent en base64; Sube cada documento lista los archivos aceptados. Subir el mismo archivo dos veces devuelve el mismo adjunto. Una subida por sí sola no presenta nada: lo presenta el envío que cita su attachment_id.
• Datos de usuario final y documentos juntos. Telserv aceptaba cada documento en su propia llamada, y los datos de usuario final como una lista de etiquetas en otra. Bird acepta todas las respuestas, escritas y documentos, en un solo envío, y no hay borradores: la solicitud presenta las respuestas para su revisión. Después sigue ownership.next, que indica el reenvío de correcciones y un envío nuevo solo cuando hace falta (Envía todas las respuestas).
• Sustituciones. Envía solo las respuestas que sustituyes; las demás conservan su revisión. Telserv aceptaba un archivo nuevo para una condición mientras el número estaba pendiente de verificación, y ese archivo reiniciaba la revisión de la condición. Bird sustituye una respuesta rechazada, caducada o aún no aportada, y rechaza una que sigue en revisión o ya está aceptada, salvo una respuesta marcada como editable_for_verifier_repair mientras haya abierta una corrección que hayamos solicitado (Corregir una respuesta rechazada).
• Progreso. ownership.status y ownership.next informan del estado del número. Cada respuesta tiene su propio state, y una rechazada incluye el reason del revisor. Bird también envía cada resultado por correo electrónico a los propietarios de tu organización y a la persona que presentó o corrigió el envío por última vez. ownership suele ser null cuando el número no requiere documentación.

Presentar la documentación de titularidad muestra las solicitudes, y Presentar la documentación de titularidad de un número cubre todo el flujo, incluida la presentación desde el panel y junto con el pedido.

Productos y datos maestros

Cada resultado de búsqueda describe su producto con number_type, capabilities y ownership_registration_required, y lleva el precio para tu organización en lugar del pricing.staticPricing del producto (nrc y mrc). Los precios estándar de Bird están en la página de precios de números de teléfono. El sessionPricing por minuto de Telserv no tiene equivalente en estas lecturas; las tarifas de voz están en la página de precios de voz.

Los tipos de número de Telserv se corresponden con el number_type de Bird de esta forma:

Qué funciona de forma diferente hoy

Estas tareas de Telserv se realizan de forma diferente en Bird. Planifícalas antes de mover una integración que dependa de alguna.

• Documentación. Presenta los documentos y los datos de usuario final de un número en un solo envío, sin borradores, y corrige las respuestas rechazadas con un reenvío de datos.
• Reservas. Pide el número cuando lo hayas elegido; el pedido lo reserva.
• Ajustes de llamada por número. Aplica un códec forzado, un límite de llamadas simultáneas, tiempo de timbre y ventanas horarias en tu equipo SIP.
• Fecha de liberación. Bird libera un número al final de su período pagado o de inmediato, no en una fecha que tú elijas. Conserva en tu lado las fechas de cancelación que enviaste a Telserv y actúa sobre cada una cuando llegue el momento.
• Saldo del monedero. Consulta el saldo y recárgalo en el panel.

Buscar y comprar un número con tu referencia

Busca en un solo país. Combina number_type, capabilities y prefix para acotar los resultados:

curl "$BIRD_API_URL/v1/numbers/available?country_code=NL&number_type=mobile&capabilities=voice&limit=10" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Cada resultado incluye un objeto pricing con el precio que tu organización paga por el número, neto de impuestos y en tu moneda de facturación, con los precios que hayas acordado con Bird ya aplicados:

• setup_price se cobra una vez al pedir el número. Una tarifa publicada de cero tiene un amount de "0". El campo en sí es null cuando no hay tarifa de alta, y también siempre que recurring_price sea null, porque ese número no se puede pedir.
• recurring_price es la tarifa por recurring_period.
• intervals_per_charge indica cuántos recurring_period factura un solo cargo. El cargo recurrente antes de impuestos es recurring_price multiplicado por intervals_per_charge, y se cobra cuando el número se asigna a tu espacio de trabajo y en cada renovación; la tarifa de alta es aparte. En un pedido que espera a un operador, la asignación se produce cuando el pedido se completa.

La referencia de API muestra un resultado de ejemplo. Un resultado con pricing.recurring_price: null no indica un precio recurrente. Contacta con ventas para obtener un precio para ese país y tipo de número antes de hacer el pedido.

El panel y API usan el mismo precio de la organización, incluida la conversión a tu moneda de facturación. Una lectura de precio no fija una cotización: los cambios de tarifa o de tipo de cambio antes de un cobro posterior pueden modificar su importe. Si la consulta falla, la búsqueda devuelve 503 con E14009. Reintenta la lectura con retroceso exponencial; un fallo de consulta nunca significa que el número no cueste nada.

Para confirmar un candidato y su precio antes de pedirlo, léelo con GET /v1/numbers/available/{number}. Un 404 significa que ya no está a la venta.

Pide el número con la referencia que usabas en Telserv y elige una clave de idempotencia que conserves para cualquier reintento de esta compra:

curl --request POST "$BIRD_API_URL/v1/numbers/orders" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-CUST-778812" \
  --data '{"number": "+31612345678", "reference": "CUST-778812"}'

Una respuesta 201 tiene status: completed y un number_id, el identificador nda_ del número. Consérvalo como NUMBER_ID. Una respuesta 202 significa que el pedido espera a un operador: consulta el pedido hasta que su status sea completed o failed. Una tarifa de alta ya cobrada no se reembolsa si el pedido falla después. La referencia se asigna al número cuando el pedido se completa. Admite hasta 100 caracteres y no necesita ser única.

Reintentar un pedido de un número que tu espacio de trabajo ya tiene asignado devuelve el pedido existente, así que un reintento no cobra dos veces. Comprar y liberar un número explica los rechazos.

Para establecer o cambiar una referencia más adelante, envía reference (y opcionalmente name) a PATCH /v1/numbers/{number_id}. Envía null para borrar un campo.

Comprobar que un número puede cursar llamadas

Un número cuyo status es pending_ownership_registration está asignado y facturado, pero no envía SMS y rechaza las llamadas de voz entrantes y salientes hasta que se apruebe su documentación de titularidad. Antes de enrutar un número o hacerle una llamada de prueba, léelo con GET /v1/numbers/{number_id} y comprueba que status sea active. Si está pendiente, presenta la documentación de titularidad. El estado de un número asignado explica cada valor.

Los ejemplos siguientes usan un número móvil neerlandés. Comprueba el status de tu propio número del mismo modo, sea cual sea su país.

Presentar la documentación de titularidad

Telserv recibía la documentación de un número con un POST /numbers/{dnisId}/documents por documento y un POST /numbers/{dnisId}/enduserdata para todas las etiquetas. Bird recibe ambos en un solo envío, después de que subas los documentos.

1. Lee el country_code del número y guárdalo como COUNTRY_CODE. El comando lo extrae con jq; léelo manualmente si no usas jq:

   Ejemplo de código

   COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

2. Lee lo que exige el país del número. Cada entrada de fields tiene el key bajo el que respondes, un data_type y required, que indica si debes responderla. Guarda el program que indica la respuesta como PROGRAM:

   Ejemplo de código

   curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
     --header "Authorization: Bearer $BIRD_API_KEY"

   Un 422 con E19001 significa que no hay formulario de titularidad para ese país.

3. Sube cada documento que pida un campo document, como archivo en lugar de fileContent en base64. Guarda el id de la respuesta, el identificador tca_ del adjunto, como ATTACHMENT_ID:

   Ejemplo de código

   curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --form "file=@registration-certificate.pdf"

4. Envía todas las respuestas a la vez: una entrada por cada campo cuyo required sea true, y por cada campo opcional para el que tengas una respuesta real, con los datos de usuario final como value y cada documento como attachment_id. Omite un campo opcional en lugar de inventarle un valor. El ejemplo muestra dos respuestas; añade el resto de las obligatorias antes de enviarlo. Esta solicitud presenta las respuestas para su revisión. Guarda el id de la respuesta, el identificador csb_ del envío, como SUBMISSION_ID:

   Ejemplo de código

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-CUST-778812" \
     --data '{"subject_kind": "number", "subject_id": "'"$NUMBER_ID"'", "program": "'"$PROGRAM"'", "country_code": "'"$COUNTRY_CODE"'", "answers": [{"key": "business_registration_number", "value": "90012768"}, {"key": "business_registration_certificate", "attachment_id": "'"$ATTACHMENT_ID"'"}]}'

   Una respuesta 201 devuelve el envío. Un 422 no presenta nada: corrige el cuerpo y envíalo con una clave de idempotencia nueva, porque la clave reproduce el rechazo. Enviar todas las respuestas explica cada rechazo.

5. Cuando un revisor rechaza una respuesta, reemplaza solo esa respuesta, como describe Corregir una respuesta rechazada:

   Ejemplo de código

   curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: ownership-fix-1-CUST-778812" \
     --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Para presentar la documentación al comprar, envía el mismo answers en el bloque compliance de POST /v1/numbers/orders. Ese pedido usa el alcance numbers existente con nivel de escritura, también cuando incluye documentación.

Sigue la revisión con ownership.status en GET /v1/numbers/{number_id}. Las respuestas son una declaración legal hecha en nombre de tu empresa, así que presenta solo respuestas que haya confirmado alguien responsable de ellas. Presentar la documentación de titularidad de un número explica cada solicitud, la revisión y la presentación junto con el pedido.

Enrutar un número a tu trunk SIP

Un número nuevo no tiene ruta propia, así que sigue la ruta predeterminada de tu espacio de trabajo. Esa ruta empieza como reject, pero en un espacio de trabajo que ya configuró una, el número nuevo responde las llamadas según ella en cuanto se asigna. Para entregar sus llamadas a tu equipo, crea un trunk SIP con las llamadas entrantes activadas, añádele un gateway y apunta el número al trunk. Trunks SIP explica cómo conectar tu equipo al trunk.

1. Crea el trunk con las llamadas entrantes activadas. Guarda el id de la respuesta, el identificador spt_ del trunk, como TRUNK_ID:

   Ejemplo de código

   curl --request POST "$BIRD_API_URL/v1/voice/trunks" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: trunk-production-pbx" \
     --data '{"name": "Production PBX", "inbound_enabled": true}'

2. Añade un gateway. Por defecto, el gateway recibe los números marcado y llamante en E.164 con su +. Si tu equipo espera números sin el +, como hacía el placeholder {dnis} de Telserv, establece destination_format para el número marcado y origination_format para el número llamante a {number}:

   Ejemplo de código

   curl --request POST "$BIRD_API_URL/v1/voice/trunks/$TRUNK_ID/gateways" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --header "Idempotency-Key: gateway-pbx-primary" \
     --data '{"sip_uri": "sip:pbx.example.com:5060", "priority": 0, "destination_format": "{number}", "origination_format": "{number}"}'

   Para conmutación por error, añade un segundo gateway; Lo que necesita un gateway explica priority y los formatos de número. Crear el mismo gateway otra vez sin una clave de idempotencia responde 409 con E21047.

3. Busca el registro de voz del número. Busca con los dígitos del número y toma el id de la entrada cuyo provider.number_id sea el id de la asignación. Guárdalo como VOICE_NUMBER_ID:

   Ejemplo de código

   curl "$BIRD_API_URL/v1/voice/numbers?search=31612345678" \
     --header "Authorization: Bearer $BIRD_API_KEY"

4. Apunta el número al trunk:

   Ejemplo de código

   curl --request PATCH "$BIRD_API_URL/v1/voice/numbers/$VOICE_NUMBER_ID" \
     --header "Authorization: Bearer $BIRD_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"inbound_configuration": {"route": {"type": "trunk", "trunk_id": "'"$TRUNK_ID"'"}}}'

   Una respuesta 200 muestra la nueva ruta. Un trunk con las llamadas entrantes desactivadas responde 412 con E21052.

Desactivar las llamadas entrantes en un trunk, o eliminarlo, devuelve cada número enrutado a él a la ruta predeterminada de tu espacio de trabajo, y volver a activarlas no restaura esas rutas. Entregar llamadas a un trunk SIP explica esto y las rutas trunk, forward y reject.

Conciliar tus números

Recorre la lista con el tamaño de página más grande. Pasa el next_cursor de cada página como NEXT_CURSOR para leer la siguiente, hasta que next_cursor sea null. La lista no devuelve un conteo total.

curl "$BIRD_API_URL/v1/numbers?limit=100" \
  --header "Authorization: Bearer $BIRD_API_KEY"

curl "$BIRD_API_URL/v1/numbers?limit=100&starting_after=$NEXT_CURSOR" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Los filtros de lista de Telserv se corresponden con los de Bird así:

Buscar un número en tu lista detalla cada filtro.

Cada entrada incluye pricing, con recurring_price por recurring_period y intervals_per_charge. A menos que el precio esté fijado para el número, recurring_price es la tarifa actual de tu organización, y cada renovación cobra la tarifa vigente en el momento de renovar, por lo que un cargo ya facturado puede diferir de ella. Listar todos los números que tienes explica en qué moneda se cobra cada número, cuándo pricing o sus precios son null y qué hacer cuando pricing.error está definido.

Un número liberado desaparece de esta lista, y leerlo por number_id responde 404. Si lo pediste en Bird, su pedido completado permanece en GET /v1/numbers/orders.

Liberar un número

Ambas solicitudes se aplican a un número dedicado, por su identificador nda_; un número compartido se rechaza con E14002. Para conservar el número hasta el final del período que ya pagaste, cancélalo:

curl --request DELETE "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: cancel-CUST-778812"

Una respuesta 202 devuelve el número con releases_at, el final de su período pagado. El número conserva su estado actual hasta entonces, su suscripción no se renueva y se libera en ese momento. Pedirlo de nuevo devuelve el mismo releases_at, y una cancelación no se puede deshacer. Un número sin suscripción asociada se libera de inmediato, y la respuesta es 200 con el status del número establecido en released.

Para liberar el número ahora, incluido uno ya programado para cancelación:

curl --request POST "$BIRD_API_URL/v1/numbers/$NUMBER_ID/release" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Idempotency-Key: release-CUST-778812"

Una respuesta 204 significa que el número está liberado, con efecto inmediato. El resto del período actual no se reembolsa.

Mientras un pago de renovación del número esté vencido, ambas solicitudes responden 409 con E03015 hasta que se pague.

Ninguna solicitud acepta una fecha, así que conserva en tu lado el calendario que enviaste a Telserv como requestedCancelDate. Para conservar un número hasta su fecha, cancélalo cuando la fecha caiga dentro de su período de facturación actual: se libera cuando ese período termina, en la fecha o después. Para liberarlo exactamente en la fecha, libéralo ese día. Liberar un número explica qué hace cada solicitud con el número, sus cargos y un reintento.

Hacer una llamada de prueba a tu número

Para verificar una ruta de extremo a extremo, haz una llamada al número desde otro número que tu espacio de trabajo pueda presentar como identificador de llamante. El país del número debe estar habilitado en tus destinos de voz, o la llamada no se completa. La solicitud de abajo ejecuta una secuencia en línea que cuelga cuando la llamada es respondida, así que no se necesita una secuencia guardada. Realiza una llamada real, y se aplican los cargos normales de llamada.

Guarda la solicitud como test-call.json. Pon en from el identificador de llamante que presentas, un número propio o verificado de tu espacio de trabajo, y en to el número que quieres probar:

{
  "from": "+31612345679",
  "to": "+31612345678",
  "sequence": {
    "definition": {
      "schema_version": 1,
      "expression_environment": "bird.cel.v1",
      "nodes": [
        {
          "id": "entry",
          "type": "trigger.start_call",
          "type_version": 1,
          "config": {},
          "input": {},
          "connections": { "event": { "node_id": "end", "port": "input" } }
        },
        { "id": "end", "type": "voice.hangup", "type_version": 1, "config": {}, "input": {} }
      ]
    },
    "entry_node_id": "entry",
    "trigger_data": {}
  }
}

Envíala:

curl --request POST "$BIRD_API_URL/v1/voice/calls" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${TEST_CALL_KEY:?Set TEST_CALL_KEY once for this test call}" \
  --data-binary @test-call.json

Asigna a TEST_CALL_KEY un valor nuevo en cada prueba, y reutilízalo cuando reintentes la misma prueba tras agotarse el tiempo de espera o tras un resultado ambiguo: la misma clave y solicitud en un plazo de tres horas reproducen la primera aceptación en lugar de realizar una segunda llamada. Una respuesta 202 acepta la llamada y devuelve su initial_leg_id. La aceptación no demuestra que la llamada se conectó: lee el tramo con GET /v1/voice/legs/{leg_id}, o lista los tramos realizados al número con GET /v1/voice/legs y su filtro to, y comprueba que tu equipo recibió la llamada. Crear una llamada de voz cubre los requisitos de identificador de llamante y destino, y las reglas de reintento.

Próximos pasos

• Comprar y liberar un número
• Gestionar tus números de teléfono
• Presentar la documentación de titularidad de un número
• Recibir llamadas
• Trunks SIP
• Idempotencia