IA para llamadas de soporte: Vapi + Bland.ai, llamadas de voz en atención al cliente

El cliente llama → Vapi toma la llamada → STT (voz a texto) → LLM (piensa) → TTS (texto a voz) → el cliente escucha la respuesta

import requests
import json

VAPI_API_KEY = "your_vapi_key"

def create_support_agent(
    company_name: str,
    knowledge_base: str,
    transfer_phone: str  # Número del agente humano
) -> dict:
    """Crea un agente de voz de soporte con Vapi"""

    headers = {
        "Authorization": f"Bearer {VAPI_API_KEY}",
        "Content-Type": "application/json"
    }

    # Los nombres de campos y modelos en Vapi cambian: antes de lanzar, compara la configuración
    # con la documentación en docs.vapi.ai (modelo, voz, reconocimiento, transferencia de llamada)
    agent_config = {
        "name": f"{company_name} Support Agent",
        "model": {
            "provider": "anthropic",
            "model": "claude-sonnet-5-5",
            "messages": [{"role": "system", "content": f"""Eres agente de atención al cliente de la empresa {company_name}.

BASE DE CONOCIMIENTO:
{knowledge_base}

REGLAS:
1. Sé amable y profesional
2. Responde solo con la base de conocimiento: no inventes
3. Si no sabes la respuesta, dilo con honestidad y ofrece comunicar al cliente con un agente
4. Confirma siempre que el cliente haya entendido
5. Si el cliente está enojado, muestra empatía, no discutas

TRANSFERENCIA A UN AGENTE (dilo textualmente):
"Permítame comunicarlo con uno de nuestros especialistas, que le ayudará con esto. 
Un momento, por favor."

Habla con naturalidad. Haz pausas. No hables atropellado."""}],
            "temperature": 0.3,  # Menos variación para soporte
            # Transferencia de la llamada a un agente humano: la herramienta transferCall
            "tools": [{
                "type": "transferCall",
                "destinations": [{
                    "type": "number",
                    "number": transfer_phone,
                    "description": "Pasar la llamada a un agente si la IA no sabe la respuesta o el cliente pide hablar con una persona",
                    "message": "Lo comunico con un especialista"
                }]
            }]
        },
        "voice": {
            "provider": "11labs",  # ElevenLabs
            "voiceId": "ID_de_voz_de_ElevenLabs"  # elige una voz que hable bien español
        },
        "transcriber": {
            "provider": "deepgram",
            "language": "es"
        },
        "firstMessage": f"¡Hola! Se comunicó al soporte de {company_name}. ¿En qué le puedo ayudar?",
        "endCallMessage": "¡Gracias por llamar! Si tiene más preguntas, llámenos. ¡Hasta luego!",
        "maxDurationSeconds": 600  # Máximo 10 minutos
    }

    response = requests.post(
        "https://api.vapi.ai/assistant",
        headers=headers,
        json=agent_config
    )

    return response.json()


def assign_phone_number(assistant_id: str, phone_number: str) -> dict:
    """Asigna un número de teléfono al agente"""

    headers = {
        "Authorization": f"Bearer {VAPI_API_KEY}",
        "Content-Type": "application/json"
    }

    response = requests.post(
        "https://api.vapi.ai/phone-number",
        headers=headers,
        json={
            "assistantId": assistant_id,
            "number": phone_number,
            "provider": "twilio"  # o vonage, telnyx
        }
    )

    return response.json()


# Ejemplo: agente para una tienda en línea
knowledge_base = """
PREGUNTAS SOBRE PEDIDOS:
- Estado del pedido: pida el número de pedido y entre a track.example.com/[número]
- Tiempo de entrega: en la ciudad 1-2 días, resto del país 3-5 días, internacional 7-14 días
- Cambiar la dirección: se puede hasta que el pedido sale; después ya no

PREGUNTAS SOBRE PAGOS:
- Formas de pago: tarjeta Visa/MC, transferencia bancaria, pago contra entrega
- Devoluciones: 14 días, según nuestra política de devoluciones
- Comprobante: se envía al email automáticamente

PROBLEMAS TÉCNICOS:
- El sitio no funciona: intente borrar la caché del navegador
- No llegó el email: revise la carpeta de Spam
- No puede entrar a su cuenta: restablezca la contraseña en example.com/reset

SE NECESITA UN AGENTE:
- Quejas por la calidad del producto
- Preguntas legales
- Situaciones que requieren compensación
"""

agent = create_support_agent(
    company_name="Mi Tienda",
    knowledge_base=knowledge_base,
    transfer_phone="+525512345678"
)

print(f"Agente creado: {agent.get('id')}")
print(f"Nombre: {agent.get('name')}")

import requests

BLAND_API_KEY = "your_bland_key"

def make_batch_calls(
    contacts: list[dict],  # [{"phone": "+52...", "name": "Juan", ...}]
    call_purpose: str,
    script_template: str
) -> dict:
    """Lanza una campaña de llamadas masivas con Bland.ai"""

    # El formato de las solicitudes de Bland cambia: compara los campos y la dirección con la documentación en docs.bland.ai
    headers = {
        "Authorization": BLAND_API_KEY,
        "Content-Type": "application/json"
    }

    # Armamos una tarea por cada contacto
    call_objects = []
    for contact in contacts:
        # Personalizamos el guion para cada persona
        personalized_script = script_template.format(**contact)

        call_objects.append({
            "phone_number": contact["phone"],
            "task": personalized_script
        })

    # Lanzamos el lote: la configuración común va en global, las llamadas en call_objects
    response = requests.post(
        "https://api.bland.ai/v2/batches/create",
        headers=headers,
        json={
            "global": {
                "task": script_template,           # guion de respaldo
                "voice": "ID_de_voz_del_panel",    # elige una voz en español en el panel de Bland
                "language": "es",                  # los códigos de idioma están en la documentación
                "max_duration": 2,                 # máximo 2 minutos
                "record": True                     # grabar la llamada (ver la advertencia abajo)
            },
            "call_objects": call_objects,
            "description": call_purpose[:60]
        }
    )

    return response.json()


# Ejemplo: recordatorios de cita
contacts_for_reminder = [
    {"phone": "+525511111111", "name": "Juan", "date": "mañana", "time": "14:00", "service": "corte de pelo"},
    {"phone": "+525522222222", "name": "María", "date": "el miércoles", "time": "11:30", "service": "manicure"},
]

reminder_script = """
¡Buenas tardes, {name}! Le llamamos del salón Belleza.
Le recordamos que {date} a las {time} tiene cita para {service}.
Si cambiaron sus planes, por favor llámenos o escríbanos por WhatsApp.
¡Lo esperamos! Hasta luego.
"""

result = make_batch_calls(
    contacts=contacts_for_reminder,
    call_purpose="Recordatorios de cita — 2026-10-15",
    script_template=reminder_script
)

print(f"Lote creado: {result.get('batch_id')}")
print(f"Llamadas programadas: {len(contacts_for_reminder)}")

import anthropic
from typing import Optional

# Un sistema RAG sencillo para el agente de voz
def create_rag_support_handler(
    documents: list[str],  # Lista de documentos de la base de conocimiento
) -> callable:
    """Crea un manejador de preguntas que busca en la base de conocimiento"""

    client = anthropic.Anthropic()

    # En un proyecto real aquí iría una base de datos vectorial (Pinecone, Chroma)
    # Para simplificar, pasamos todos los documentos en el contexto
    knowledge_context = "\n\n---\n\n".join(documents)

    def handle_voice_query(
        user_query: str,
        conversation_history: list[dict],
        customer_info: Optional[dict] = None
    ) -> dict:
        """Procesa una solicitud del agente de voz"""

        system_prompt = f"""Eres agente de soporte. Responde ÚNICAMENTE con base en la base de conocimiento.
Si no tienes la información, di con honestidad que no lo sabes y ofrece comunicar al cliente con un agente.

IMPORTANTE PARA LA RESPUESTA DE VOZ:
- La respuesta debe sonar natural al decirse en voz alta
- No uses viñetas (•, -, *): no suenan bien
- Escribe los números con palabras: no "14:00", sino "a las dos de la tarde"
- Máximo 3-4 oraciones por respuesta

BASE DE CONOCIMIENTO:
{knowledge_context}"""

        messages = conversation_history + [{
            "role": "user",
            "content": user_query
        }]

        response = client.messages.create(
            model="claude-sonnet-5-5",
            max_tokens=200,  # Las respuestas de voz son cortas
            system=system_prompt,
            messages=messages
        )

        answer = "".join(b.text for b in response.content if b.type == "text")

        # Detectamos si hace falta transferir a un agente
        transfer_signals = [
            "no lo sé", "no puedo ayudar", "necesita un especialista",
            "lo comunico con un agente", "voy a pasar su caso"
        ]
        needs_transfer = any(signal in answer.lower() for signal in transfer_signals)

        return {
            "response_text": answer,
            "needs_human_transfer": needs_transfer,
            "transfer_reason": "La IA no pudo responder" if needs_transfer else None
        }

    return handle_voice_query


# Ejemplo de uso
faq_documents = [
    """DEVOLUCIONES
    Puede devolver un producto dentro de los catorce días posteriores a la compra.
    El producto debe estar en su empaque original y sin señales de uso.
    El dinero se reembolsa en un plazo de tres días hábiles a la tarjeta con la que pagó.""",

    """ENVÍOS
    Dentro de la ciudad entregamos en uno a dos días.
    Al resto del país, de tres a siete días.
    El envío es gratis en pedidos desde cincuenta dólares.
    Puede rastrear su pedido en el sitio, en la sección Mis pedidos.""",

    """PAGOS
    Aceptamos tarjetas Visa y MasterCard.
    También puede pagar por transferencia bancaria o en efectivo al recibir.
    Ofrecemos meses sin intereses con un banco asociado a tres, seis o doce meses."""
]

handler = create_rag_support_handler(faq_documents)

# Prueba de conversación
conversation = []
queries = [
    "quiero devolver un producto que compré hace una semana",
    "¿y si ya no tengo el empaque?"
]

for query in queries:
    print(f"\nCliente: {query}")
    result = handler(query, conversation)
    print(f"IA: {result['response_text']}")
    if result['needs_human_transfer']:
        print("⚠️ TRANSFERENCIA A UN AGENTE")

    # Actualizamos el historial de la conversación
    conversation.append({"role": "user", "content": query})
    conversation.append({"role": "assistant", "content": result['response_text']})

def analyze_call_transcripts(transcripts: list[str]) -> dict:
    """Analiza un lote de transcripciones de llamadas y encuentra patrones"""

    client = anthropic.Anthropic()

    # Unimos las transcripciones con separadores
    combined = "\n\n=== LLAMADA ===\n\n".join(transcripts[:20])  # Las primeras 20

    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1000,
        messages=[{
            "role": "user",
            "content": f"""Analiza las transcripciones de las llamadas a soporte.

TRANSCRIPCIONES:
{combined}

Necesito:
1. **Las 10 preguntas** más frecuentes (con porcentaje)
2. **Los 5 problemas** que la IA no pudo resolver (se necesitó una persona)
3. **Duración promedio de la llamada** por categoría
4. **Tono emocional**: cuántos clientes enojados/satisfechos/neutrales
5. **Recomendaciones**: qué agregar a la base de conocimiento para que la IA resuelva más
6. **Focos rojos**: qué hay que corregir con urgencia en el producto/servicio

Formato: un reporte estructurado con cifras."""
        }]
    )

    return "".join(b.text for b in response.content if b.type == "text")


# Costo vs. retorno (ROI)
def calculate_roi(
    current_calls_per_month: int,
    avg_call_duration_minutes: float,
    operator_hourly_cost: float,
    ai_cost_per_minute: float,  # la suma de los cinco renglones del costo por minuto; calcúlala con tu stack
    ai_deflection_rate: float = 0.75  # supuesto del ejemplo: mídelo con tus llamadas
) -> dict:
    """Calcula el ROI de implementar IA de voz (todos los números del ejemplo son inventados)"""

    # Gasto actual
    total_minutes = current_calls_per_month * avg_call_duration_minutes
    current_cost = (total_minutes / 60) * operator_hourly_cost

    # Con IA
    ai_handled = current_calls_per_month * ai_deflection_rate
    human_handled = current_calls_per_month * (1 - ai_deflection_rate)

    ai_cost = ai_handled * avg_call_duration_minutes * ai_cost_per_minute
    human_cost = (human_handled * avg_call_duration_minutes / 60) * operator_hourly_cost

    new_total_cost = ai_cost + human_cost
    savings = current_cost - new_total_cost

    return {
        "current_monthly_cost": round(current_cost, 2),
        "new_monthly_cost": round(new_total_cost, 2),
        "monthly_savings": round(savings, 2),
        "annual_savings": round(savings * 12, 2),
        "ai_handled_calls": int(ai_handled),
        "human_calls_freed": int(ai_handled),
        "roi_percent": round((savings / new_total_cost) * 100, 1)
    }

# Ejemplo de cálculo
roi = calculate_roi(
    current_calls_per_month=2000,
    avg_call_duration_minutes=4.5,
    operator_hourly_cost=15,   # supuesto del ejemplo: pon el costo real
    ai_cost_per_minute=0.20    # supuesto del ejemplo: pon la suma de tu stack
)

print("=== ANÁLISIS DE ROI ===")
for k, v in roi.items():
    print(f"{k}: {v}")

# Entra a vapi.ai
# Crea una cuenta
# Obtén la clave de API en Dashboard → API Keys
# Guárdala en .env:

echo "VAPI_API_KEY=your_key_here" >> .env

# setup_agent.py
import os
import requests
from dotenv import load_dotenv

load_dotenv()
VAPI_API_KEY = os.environ["VAPI_API_KEY"]

# Creamos el agente
agent = requests.post(
    "https://api.vapi.ai/assistant",
    headers={"Authorization": f"Bearer {VAPI_API_KEY}"},
    json={
        "name": "Agente de soporte de prueba",
        "model": {
            "provider": "anthropic",
            "model": "claude-sonnet-5-5",
            "messages": [{"role": "system", "content": """Eres agente de soporte de una tienda de prueba.

Sabes que:
- Envío: 2-5 días en todo el país, gratis desde $50
- Devoluciones: 14 días, producto en su empaque
- Pagos: tarjetas, transferencia bancaria, efectivo al recibir
- Horario: lunes a viernes de 9 a 18, sábado de 10 a 15

Si la pregunta no es de estos temas, di que comunicas con un agente.
Habla breve y al grano. Sé amable."""}]
        },
        "voice": {
            "provider": "11labs",
            "voiceId": "ID_de_voz_de_ElevenLabs"
        },
        "firstMessage": "¡Buen día! Soporte de prueba. ¿En qué le puedo ayudar?"
    }
).json()

print(f"ID del agente: {agent['id']}")
print(f"Enlace para la llamada de prueba desde el navegador:")
print(f"Usa Dashboard → Test Phone Call")

# get_call_analytics.py
import requests
import os

VAPI_API_KEY = os.environ["VAPI_API_KEY"]

# Obtenemos la lista de las últimas llamadas
calls = requests.get(
    "https://api.vapi.ai/call",
    headers={"Authorization": f"Bearer {VAPI_API_KEY}"},
    params={"limit": 10}
).json()

for call in calls.get("results", []):
    print(f"\nLlamada: {call.get('id')}")
    print(f"Duración: {call.get('duration', 0)} s")
    print(f"Estado: {call.get('status')}")
    if call.get('transcript'):
        print(f"Transcripción:\n{call['transcript'][:300]}...")