Haga su primera llamada por API
Esta guía muestra cómo iniciar una llamada saliente con la API de voz de demostración y seguir su estado. Todo es ficticio: la llamada es una simulación mientras no haya un proveedor configurado.
Actualizado el
Antes de empezar
- Una clave de prueba. En esta guía: tq_test_EXEMPLE, un valor ficticio que no da acceso a nada.
- Un proyecto. En esta guía: prj_EXEMPLE_A («Proyecto A»).
- Dos números en formato E.164, sin espacios. En esta guía: +33199001234 (quien llama) y +33199005678 (quien recibe), de un rango ficticio.
- curl, o cualquier cliente HTTP que pueda enviar cabeceras.
Iniciar la llamada
- Genere un valor único para la cabecera Idempotency-Key (un UUID). Es obligatoria en toda solicitud POST.
- Envíe POST /calls con from, to y project_id. Añada flow_id si quiere asociar un escenario de llamada.
- Guarde el id de la respuesta: lo usará para encontrar la llamada en el registro.
curl -X POST https://api.example.test/v1/calls \
-H "Authorization: Bearer tq_test_EXEMPLE" \
-H "Idempotency-Key: 3f1c2a9e-5b7d-4e08-9a41-6d2b8c0e7f15" \
-H "Content-Type: application/json" \
-d '{"from":"+33199001234","to":"+33199005678","project_id":"prj_EXEMPLE_A"}'Leer la respuesta
La API responde de inmediato con la llamada creada. El estado ringing indica que se solicitó el timbre, no que alguien haya contestado. El campo simulated: true recuerda que no se emitió ninguna comunicación real.
{
"id": "call_EXEMPLE_001",
"status": "ringing",
"simulated": true
}Seguir el estado de la llamada
Los estados posibles son ringing, connected, completed y failed. Consulte el registro con GET /calls para ver la evolución, o suscríbase por webhook a call.ringing, call.connected, call.completed y call.failed.
El registro distingue la duración de conversación (duration_seconds) de la duración facturable (billable_seconds). Son dos valores distintos. No los confunda con el tiempo de timbre.
curl "https://api.example.test/v1/calls?limit=5" \
-H "Authorization: Bearer tq_test_EXEMPLE"Errores frecuentes
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| 400 invalid_request | Número con espacios o sin el signo más, campo ausente, falta Idempotency-Key. | Envíe los números en E.164 sin espacios y añada la cabecera Idempotency-Key. |
| 401 unauthorized | Clave ausente o mal copiada, o cabecera Authorization mal formada. | Revise el esquema Bearer y el valor de la clave. |
| 403 forbidden | La clave no tiene acceso al proyecto solicitado. | Use una clave asociada al proyecto correcto. |
| 409 idempotency_conflict | Se usó la misma clave de idempotencia con un cuerpo distinto. | Genere una clave nueva para una operación nueva. Repita una clave solo para reenviar exactamente la misma solicitud. |
| 429 rate_limited | Demasiadas solicitudes en poco tiempo. | Espere el tiempo indicado por la cabecera Retry-After antes de reintentar. |
| Estado failed | La llamada no se completó. | El estado no indica la causa. No la suponga: consulte el detalle de la llamada y los registros. |
Lo que esta guía no hace
- No hace ninguna llamada real: mientras no haya un proveedor configurado, todo es simulado.
- No garantiza que una llamada se complete. Las capacidades dependen del país, del proveedor elegido y del contrato.
- No cubre la grabación, la transcripción ni los comandos de llamada avanzados (menú de voz, conferencia), que dependen del proveedor.
- Una llamada puede generar varias líneas de consumo según el contrato. Vea la guía «Leer su consumo».
Preguntas frecuentes
¿Puedo repetir la misma solicitud sin crear dos llamadas?
Sí, si reenvía la misma Idempotency-Key con el mismo cuerpo. Para eso sirve la cabecera: un doble clic o un reintento de red no crea una segunda llamada.
¿Para qué sirve flow_id?
Asocia la llamada a un escenario de llamada diseñado en la consola. Es opcional: sin él, la llamada simplemente conecta los dos números.