Llamadas con agentes

talkHero permite iniciar llamadas salientes a números de Colombia desde el panel o la API. El agente asignado al canal escucha la respuesta, utiliza su versión publicada y devuelve una respuesta por voz. Marcar cero solicita atención humana.

Configuración

1. En Central → Proveedores y reglas → Nueva cuenta, selecciona Conectar llamadas y elige Twilio Voice o Plivo Voice.
2. Registra una cuenta habilitada, su número propio y auth_token. Twilio utiliza Account SID y Phone Number SID; Plivo utiliza Auth ID y requiere indicar la moneda de su cuenta. La comprobación consulta la identidad y el número sin realizar llamadas.
3. Comprueba y habilita la cuenta. Registra su tarifa por minuto con fuente y moneda; publica las reglas de Llamadas. Puedes usar cuentas distintas por cliente. Una llamada conserva su número y proveedor; no cambia de identidad cuando una cuenta falla.
4. Habilita Llamadas y, si usarás un agente, Agentes en el contrato publicado del cliente. Asigna saldo y los límites correspondientes.
5. En Panel → Canales → Producción, agrega un canal de Llamadas con esa cuenta y su número. Asigna un agente publicado y verifica el canal.
6. En el detalle del canal configura el saludo, número de transferencia de Colombia, duración máxima y llamadas simultáneas. Informa en el saludo que atiende una IA y que marcar cero solicita una persona.
7. Agrega el contacto, su identidad telefónica y la evidencia de consentimiento para la finalidad de la llamada. Servicio y marketing se autorizan por separado.

La API necesita una URL pública HTTPS alcanzable por el proveedor. Los callbacks de cada llamada se asignan automáticamente. El despliegue local solo acepta HTTP en loopback para las pruebas; esa dirección no permite que un proveedor externo se conecte.

Llamar y finalizar

En Panel → Llamadas, selecciona Nueva llamada, canal, contacto y finalidad. talkHero reserva el saldo de la duración máxima antes de solicitar la llamada. El consentimiento, contrato, disponibilidad del proveedor y reglas se comprueban nuevamente al despachar.

El detalle muestra el estado, duración confirmada, minutos reservados, minutos consumidos y cargo final. Finalizar llamada cancela una solicitud en cola o solicita detener la llamada activa. El saldo se liquida cuando se obtiene la duración del proveedor.

Marcar cero o pedir explícitamente una persona genera una transferencia al número configurado. El historial y la solicitud quedan en Bandeja. Si no hay número de transferencia, se registra la solicitud y termina la llamada. La respuesta XML de transferencia se emite una vez; si su recepción fue ambigua, se evita iniciar un segundo tramo automáticamente.

API

Una clave de producción necesita calls:write para iniciar/finalizar y calls:read para consultar. La configuración de canales utiliza channels:read y channels:write. Estas rutas no admiten claves del entorno de pruebas.

POST /v1/calls
Authorization: Bearer <clave con calls:write>
Idempotency-Key: llamada-soporte-001
Content-Type: application/json

{
  "channel_account_id": "<UUID del canal>",
  "recipient_identity_id": "<UUID de identidad del contacto>",
  "purpose": "service"
}

Consulta con GET /v1/calls o GET /v1/calls/{id}. Finaliza con POST /v1/calls/{id}/stop. Conserva la misma clave y cuerpo cuando reintentes una solicitud cuya respuesta se perdió. Una clave utilizada con otro cuerpo se rechaza.

Medición y fallos

El cargo de talkHero usa minutos iniciados y las condiciones conservadas al crear la llamada. La duración original en segundos permanece disponible. Una llamada de 61 segundos consume dos minutos; su importe depende del contrato, sin tarifas predeterminadas de telefonía.

Central → Llamadas muestra el cargo al cliente y los costos informados por el proveedor, separados entre llamada principal y transferencia. Estos costos de telefonía no incluyen automáticamente modelos, reconocimiento ni síntesis. Un precio o duración ausente se muestra pendiente, nunca como cero.

Si se pierde la aceptación del proveedor, la operación queda por confirmar, conserva su reserva y no inicia otra llamada. Los callbacks verifican firma, cuenta, número, llamada y secuencia. El consumo se concilia mediante el registro del proveedor; un callback aislado no impone el cargo final.

Alcance

Esta versión incluye llamadas salientes, agentes existentes, transferencia humana, límite de duración, concurrencia, API y consumo. La recepción telefónica entrante, grabaciones, conferencias, SIP/WebRTC y campañas de llamadas no están habilitadas en este corte. Las pruebas locales con proveedores sintéticos no sustituyen la aceptación con cuentas y números reales.