¿Cómo creo un pedido y disparo su llamada por API?

Objetivo: Usar la operación «Disparar una llamada» con los campos correctos y leer su respuesta.

Nivel: Avanzado · Duración: 3 min · Antes de esta lección: «¿Qué permisos le doy a cada llave de API y cómo pruebo sin gastar saldo?»

Dónde, en Talkyria: app.talkyria.com/integraciones/api

Gancho

Tu sistema crea un pedido y, segundos después, tu agente ya está llamando al cliente. Todo eso es una sola petición, y hoy vas a ver cada uno de sus campos.

Lo que vas a lograr

Vas a armar la petición «Disparar una llamada», elegir el agente, darle contexto y leer la respuesta: en cola, no llamada, duplicada o sin saldo.

Pasos en pantalla

1. La operación es POST a https://api.talkyria.com/api/v1/calls/trigger, con tu llave y un permiso para disparar llamadas. Tienes el ejemplo listo en «Tu primera llamada» de la documentación.
2. Obligatorios: externalId, que es el número del pedido en tu sistema, y customer con phone en formato internacional, por ejemplo +573001234567.
3. Para un agente de confirmación agrega lo que el agente dice: customer.name, products con nombre, cantidad y precio, totalPrice, currency y shippingAddress con dirección, ciudad y departamento.
4. Elige el agente: con agentId marcas uno concreto, y es obligatorio en un agente creado solo para la API. Sin agentId, envía estado con el estado del pedido en tu sistema y Talkyria usa el disparador que lo atiende.
5. Opcional: customVariables con claves que empiezan por cv_, hasta 25, para datos propios como un código de promoción.
6. Envía la petición. Si responde «201» con status queued, la llamada está en cola. Con not_called, lee notCalledReason: call_mode_manual, no_trigger_configured, agent_inactive y otros.
7. Si responde «402», no hay saldo ni minutos: recarga o activa la auto-recarga. Si responde «422» con agent_required, falta decir qué agente llama: la respuesta trae los candidatos.
8. Abre «Pedidos» en el panel: el pedido aparece con su canal y, cuando termine la llamada, con su resultado en «Contacto».

Error común y cómo resolverlo

Mandar el teléfono sin código de país o con espacios y letras. El agente no puede marcar un número mal escrito. Envía siempre el formato +código de país y número, sin espacios.

¿Y ahora qué?

¿Y si quieres que llame ya, o a una hora exacta? Lo ves en la microlección. Siguiente lección: «¿Cómo hago que la API llame ya o a una hora exacta?».