Talkyria API

Busca pedidos del shop. Requiere scope orders:read.

Detalle del pedido + sus llamadas. El transcript y la grabación de cada llamada requieren además el scope calls:read:content. Requiere scope orders:read.

Requiere scope calls:read (+ calls:read:content para transcript/grabación).

Encola una llamada manual para un pedido EXISTENTE (equivalente al botón "Llamar" del dashboard). Corre los mismos billing guards + rate-limit (1 llamada por pedido cada 5 min) y marca la llamada como manual (bypassa dedup). Para ingerir un pedido NUEVO + llamarlo usa POST /calls/trigger. Requiere scope calls:trigger. Saldo: sin saldo ni minutos (y sin auto-recarga), responde 402. Sandbox: claves tk_test_ simulan sin telefonía ni cobro.

Actualiza el estado logístico del pedido. Requiere scope orders:write. Sandbox: claves tk_test_ devuelven una respuesta simulada sin mutar.

Marca un pedido como confirmed o cancelled desde un sistema externo (ej. una confirmación por WhatsApp), suspende los reintentos y etiqueta el pedido en Shopify si aplica. First-write-wins: un pedido ya confirmado no se sobrescribe. Requiere scope orders:write. Sandbox: las claves tk_test_ simulan sin mutar el pedido real.

Lista global de llamadas del shop, paginada + filtrable. Requiere scope calls:read (+ calls:read:content para transcript/grabación, offers:read para el resultado de oferta). Nunca expone costos internos ni el resumen crudo.

Metadata/outcome de una llamada. Requiere scope calls:read (+ calls:read:content para transcript/grabación). Nunca expone costos internos ni el resumen crudo.

Crea un pedido y encola una llamada. Requiere scope calls:trigger. Acepta el shape plano (canónico) y el anidado (order:{}) legacy — ambos equivalen. Saldo: sin saldo ni minutos (y sin auto-recarga), responde 402. Sandbox: claves tk_test_ simulan sin telefonía ni cobro.

Los 20 batches más recientes del shop, con su progreso. Requiere scope calls:read.

Crea + inicia un batch de llamadas. Requiere scope calls:trigger. Provee orderIds (array de ids del shop) o status (todos los pedidos con ese status, opcional limit). El bulkCallWorker procesa SECUENCIALMENTE y re-valida cada pedido antes de llamar (se salta los ya confirmados). Tope: 500 pedidos/batch. Sandbox: claves tk_test_ simulan sin telefonía ni cobro.

Status + progreso (procesados/exitosos/fallidos) de un batch. Requiere scope calls:read. Shop-scoped.

Pausa, reanuda o cancela un batch en curso. Requiere scope calls:trigger. Transiciones válidas: pause (in_progress), resume (paused), cancel (pending/in_progress/paused). Shop-scoped.

Realiza una llamada de PRUEBA con un agente para validar tu configuración. Requiere scope calls:trigger. Body: agentTable (ShopifyAgent|ChateaProAgent|DropiAgent|SalesAgent), agentId (del shop), phoneNumber (E.164). La llamada se factura normal (wallet/minutos) y usa la misma resolución de número que las llamadas reales (verificado > dedicado). Sandbox: claves tk_test_ simulan sin telefonía ni cobro.

Lista los agentes del shop (todas las integraciones). Requiere scope agents:read. No expone el prompt.

Crea un agente de voz de cualquier integración (shopify | chateapro | dropi | sales, según integration, default shopify). Requiere scope agents:write. Reusa el core probado del dashboard (validación de voz/modelo, dedup por tipo/callType, creación del counterpart en el motor de voz + workflow canónico, con borrado del huérfano si el motor falla). Un agente sin número nace inactivo (Regla 87).

Configuración completa del agente. Requiere scope agents:read. El prompt personalizado solo aparece si el agente lo usa.

Edita campos del agente (voz, idioma, reintentos, nombre, estado, número, horarios, cupón, y los específicos de cada integración). La integración se resuelve automáticamente por el id (across shopify/chateapro/dropi/sales). Requiere scope agents:write. Solo se aceptan campos editables — cualquier otro se ignora (allowlist per-integración). Activar un agente (isActive:true) requiere que tenga número (Regla 87). Reusa el core probado del dashboard.

Borra permanentemente el agente (hard-delete, Regla 323) de cualquier integración — la integración se resuelve por el id. Dropi/Sales cascadean sus dependientes (smart-offers / leads). Requiere scope agents:write.

Los knobs avanzados de comportamiento de llamada (timbrado/silencio/duración/backchannel), buzón de voz, diccionario de palabras clave (boost STT), campos de análisis post-llamada y handbook de personalidad. De cualquier integración (resuelto por el id). Requiere scope agents:read.

Actualiza SOLO los campos enviados; los omitidos se preservan. Persiste en el snapshot del agente y sincroniza el motor de voz best-effort (si el motor falla, el cambio queda guardado y se reintenta en la próxima llamada → respuesta con warning). voicemail.action siempre es hangup. Requiere scope agents:write.

Devuelve el workflow_definition (máquina de estados conversacional) del agente, de cualquier integración (resuelto por el id). Requiere scope agents:read.

Reemplaza el workflow_definition completo. Requiere scope agents:write. El motor valida invariantes (exactamente 1 nodo de inicio, 1 nodo global, aristas con etiqueta/condición, variables de contexto canónicas). Un flujo que viola una invariante irrecuperable devuelve 422 con la lista exacta de errores — las llamadas nunca quedan mudas por un flujo malformado.

Voces disponibles para los agentes. Requiere scope voices:read.

Lista los leads de un agente de ventas (estado, outcome, venta). Requiere scope leads:read. Filtro status, paginado. NUNCA el fee interno ni el metadata crudo.

Encola un lead para que el agente de ventas lo llame (speed-to-lead). Requiere scope leads:write. Sandbox: claves tk_test_ simulan sin crear lead ni llamar. Rate-limit adicional de 60/min por shop.

Si el upsell/smart-offer se mostró, si el cliente aceptó, qué producto/cantidad/variante, cuánto revenue generó y si el line-item se agregó a Shopify. Requiere scope offers:read.

Config + stats de las smart-offers del shop (upsell/quantity/bundle). Requiere scope offers:read. ?integration=shopify|dropi filtra por integración; ?agentId= filtra las de Dropi por agente. Los agregados (timesShown/timesAccepted/revenueGenerated) son SOLO LECTURA (los escribe el worker).

Crea una smart-offer. Requiere scope offers:write. El body DEBE incluir integration ("shopify" | "dropi"). Shopify: oferta shop-global (el precio con descuento se recomputa server-side). Dropi: requiere agentId y habilita enableSmartOffers del agente (LOCK provider/warehouse). Los agregados NUNCA se pueden escribir.

Detalle de una smart-offer (resuelve Shopify y Dropi). Requiere scope offers:read. Shop-scoped.

Edita una smart-offer (incluye toggle vía isActive). Requiere scope offers:write. Dropi: agentId es inmutable. Shop-scoped.

Borra una smart-offer (hard delete). Requiere scope offers:write. Dropi: si era la última oferta activa del agente, apaga enableSmartOffers. Shop-scoped.

Métricas agregadas del shop (tasas de confirmación, breakdown de outcomes, serie temporal, heatmap por hora, por-producto/ciudad/agente, funnel, cart recovery, ofertas). Requiere scope analytics:read. NUNCA expone el costo interno de Talkyria — solo lo que se le cobra al merchant (Regla 387).

Lista los webhooks salientes del shop. Requiere scope webhooks:read. NUNCA devuelve el secret.

Registra una URL a la que Talkyria hace PUSH del resultado final de cada llamada (call.outcome_final), firmado con X-Talkyria-Signature: sha256=hmac(payloadRaw, secret), con reintentos (1/5/30 min) e idempotencia. Requiere scope webhooks:write. La URL se valida contra SSRF (bloquea IPs internas/metadata, resuelve DNS). El secret se genera server-side y se muestra UNA sola vez en la respuesta. Máximo 10 webhooks por shop.

Detalle de un webhook del shop (sin secret). Requiere scope webhooks:read.

Edita url (revalidada anti-SSRF), events, isActive o merchantExternalId. Con regenerateSecret: true rota el secreto (se muestra una vez). Requiere scope webhooks:write.

Borra un webhook del shop. Requiere scope webhooks:write.

Historial de entregas de un webhook saliente (status code, éxito, intento, respuesta del destino) para depurar. Requiere scope webhooks:read. Paginado. El secreto NUNCA aparece; responseBody se trunca a 2000 chars.

Saldo del wallet + tarifa por minuto + minutos gratis restantes + config de auto-recarga. Requiere scope billing:read. SOLO LECTURA — la recarga/transferencia NUNCA se expone por API (Stripe/dashboard/2FA). Nunca expone el costo interno de Talkyria.

Shop, workspace, país/moneda, plan, scopes y modo prueba de la clave. Requiere scope billing:read. Nunca secretos ni costo interno.

Números dedicados activos del workspace. Requiere scope phones:read. Nunca expone el carrier (Regla 119).

Compra el número phoneNumber (de GET /phones/available) y lo importa al motor de voz. Cobra $2.00 USD/mes al wallet del workspace. Requiere scope phones:write. Divergencias vs dashboard (seguridad programática): verifica saldo ANTES (402 si insuficiente), cuota máx 25/workspace (409), y una clave tk_test_ NO compra (respuesta simulada). El número se compra NEUTRAL — asígnalo con PATCH /agents/:id { phoneNumberId }.

Números US comprables. areaCode opcional (3 dígitos). Requiere scope phones:read. Read-only (sin costo).

Cambia el alias nickname. Requiere scope phones:write.

Lo desasigna de todos los agentes + lo libera en el motor/carrier. NO reembolsa. Requiere scope phones:write. Una clave tk_test_ no libera infra real.

Los números propios del merchant verificados (+ estado). Requiere scope verified_caller_ids:read.

Inicia la verificación del número propio phoneNumber (E.164). Telnyx lo llama (method:call) o textea (method:sms) con un código. Luego envíalo con POST .../:id/verify. Requiere scope verified_caller_ids:write. Sin costo. Una clave tk_test_ no dispara la verificación real.

Lo borra en el motor/carrier + limpia las asignaciones de agente. Requiere scope verified_caller_ids:write.

Envía el código (4-10 dígitos) que Telnyx dictó/texteó. Síncrono: OK ⇒ status:verified. Requiere scope verified_caller_ids:write. Luego asigna con PATCH /agents/:id { verifiedCallerIdId }.