Transferir llamadas

Guarda los números a los que un agente puede transferir y luego dirige a quienes llaman con una transferencia en frío, o mantente en la línea y preséntalos con una transferencia en caliente.

Un agente transfiere llamadas solo a sus números de transferencia: una lista de nombres y números de teléfono que guardas en el agente. El prompt se refiere a cada número por su nombre e indica cuándo transferir y si la transferencia debe ser en frío o en caliente. El agente solo ve los nombres, nunca los números. Un agente sin números de transferencia no puede transferir llamadas.

Si el agente omite el modo, la transferencia será en frío.

Configura las transferencias#

En el panel:

1. Abre Agentes de voz, selecciona el agente y abre Configuración.
2. En Números de transferencia, agrega cada destino con un nombre y un número de teléfono, como Billing y +1 415 555 2671. Un agente puede tener hasta 50 números de transferencia.
3. En el prompt, consulta cada destino por su nombre e indica cuándo usarlo y si debes usar el modo cold o warm, por ejemplo, "transfiere las preguntas de facturación a Billing". No creas una herramienta personalizada.
4. Para las transferencias cálidas, elige qué sucede Antes de conectar y, opcionalmente, qué debe decir el Resumen. Consulta Antes de conectar.
5. Si es necesario, configura Avanzado → Duración del timbre entre 5 y 120 segundos.
6. Selecciona Implementar.

Con la API, usa PATCH /v1/agents/{agent_id} para preparar transfer_destinations, el prompt y los elementos opcionales warm_transfer_style, warm_transfer_briefing y ring_duration_seconds, y luego POST /v1/agents/{agent_id}/deploy:

{
  "transfer_destinations": [
    {"name": "Billing", "number": "+14155552671"},
    {"name": "Front desk", "number": "+19375551234"}
  ],
  "warm_transfer_style": "introduce",
  "warm_transfer_briefing": "The caller's name and what they need."
}

Una operación de escritura reemplaza toda la lista, y [] elimina todos los números de transferencia. Consulta la API de agentes para conocer las reglas de los campos y los errores de validación.

Nombres y números#

• Nombre: de 1 a 60 caracteres, único en el agente sin distinguir mayúsculas de minúsculas. Esta es la palabra que usa el prompt.
• Número: un número de teléfono completo. Los números sin código de país se interpretan como números de EE. UU., y todos los números se almacenan en formato E.164. Se rechazan las extensiones y el rango ficticio del 555-0100 al 555-0199.
• Número variable: en lugar de un número de teléfono, una variable de llamada por sí sola, como {{rep_phone}}. Se completa con las variables de la llamada cuando esta comienza. Si falta la variable o no es un número válido en esa llamada, se rechaza una transferencia a ese nombre.

Qué números puede alcanzar una llamada#

Lo que puede alcanzar una transferencia depende de la línea que la transporta. Una transferencia transportada por la línea de ThunderPhone solo puede alcanzar números de EE. UU., excepto números de tarifa premium y otros números de servicios especiales. Una transferencia transportada por tu propio operador puede alcanzar cualquier número que hayas guardado.

Un número de tu propio operador realiza llamadas salientes y tramos en caliente únicamente a través del troncal saliente de su propia conexión: conexiones SIP manuales con un troncal saliente, conexiones de Twilio con llamadas salientes configuradas y conexiones de Telnyx. Sin ese troncal, el número no puede marcar llamadas salientes, por lo que solo admite transferencias en frío. Esas llamadas nunca recurren como alternativa a la línea de ThunderPhone.

Si tu organización no tiene números en su propio operador, guardar un número al que la línea de ThunderPhone no puede llegar falla con un error. Una vez que conectes tu propio operador, esos números se guardan y se marcan como funcionales solo en transferencias que transporte tu operador (platform_ok: false en la API). Un agente puede responder en ambos tipos de número, por lo que la verificación se ejecuta en cada llamada.

Antes de conectar#

Cada agente elige qué ocurre cuando la persona en el destino responde una transferencia en caliente. La configuración se aplica a cada transferencia en caliente que realice el agente.

Usa Presentar en la línea salvo que la persona que responde necesite poder rechazar llamadas o deba saber sobre quien llama antes de que esté en la línea. Preguntar primero le permite rechazarla, pero mantiene a quien llama en espera más tiempo, y el buzón de voz, el silencio o un rechazo devuelven a quien llama al agente. Susurrar le da el contexto en privado sin preguntar; el buzón de voz devuelve a quien llama al agente.

El resumen#

La configuración de Resumen determina lo que el agente le dice a la persona que responde sobre quien llama. Con Presentar en la línea, esa es la presentación que ambos escuchan una vez que se conectan. De forma predeterminada, es muy breve: quién llama y por qué, por ejemplo, "Hola, tengo a Alex en la línea por un pedido. Alex, adelante." Con Preguntar primero, es la frase privada antes de que se conecte a quien llama y termina preguntando si puede atender la llamada; la presentación después de que acepte sigue la misma idea. Con Susurro, es la frase privada antes de que se conecte a quien llama, por ejemplo, "Tengo a Alex llamando por un pedido retrasado; lo estoy comunicando ahora." Es una afirmación, no una pregunta.

Para cambiar lo que dice, escribe una instrucción de Resumen en el agente (warm_transfer_briefing, hasta 300 caracteres), por ejemplo, "El nombre de quien llama, su número de cuenta y lo que necesita." El agente la sigue cuando redacta cada presentación o resumen. Limítala a los pocos datos importantes: una presentación o frase de Susurro de más de unas 40 palabras, o un resumen de Preguntar primero de más de unas 25 palabras, se reemplaza por una frase estándar breve. Déjala en blanco para usar la opción predeterminada.

Qué sucede durante una transferencia cálida#

Con Presentar en la línea (la opción predeterminada):

1. El agente informa a quien llama que iniciará la transferencia. La grabación de la llamada se detiene y ThunderPhone comienza a llamar al destino desde el número que gestiona la llamada de inmediato, mientras el agente aún está hablando.
2. Mientras suena el destino, quien llama espera brevemente en silencio. No hay música de espera en este estilo.
3. En cuanto el destino responde, quien llama ya está en la línea, por lo que escucha el saludo desde la primera palabra.
4. Cuando la persona que respondió ha terminado y espera una respuesta, el agente presenta a quien llama en una o dos frases que ambos escuchan, por ejemplo: "Hola, tengo a Alex en la línea por un pedido. Alex, adelante." El agente determina esto por lo que dijo la persona, no por una pausa: un aviso de grabación o "por favor, espere" no marca el final de su turno; "¿Cómo puedo ayudarle?" sí. Si no dice nada, el agente comienza después de unos 3 segundos. Si empieza a hablar durante la presentación, el agente se detiene, deja que termine y lo dice de nuevo. Después de unos 15 segundos, por ejemplo, ante un menú telefónico largo, el agente presenta a quien llama de todos modos. Una presentación ausente o demasiado larga se reemplaza por una frase estándar breve, dicha en el idioma de la llamada.
5. El agente se desconecta automáticamente; no dice nada más.

Quien responda queda conectado. Si es un saludo de buzón de voz, el agente no dice nada y se desconecta, para que quien llama pueda dejar un mensaje. Si el destino no responde, está ocupado, no se puede realizar la llamada o la persona que respondió cuelga antes de que termine la presentación, ThunderPhone finaliza esa llamada y quien llama regresa al agente. El agente recibe el resultado y continúa la conversación original. Puede tomar un mensaje, sugerir otra opción o realizar una transferencia en frío si quien llama aún la desea.

Con Preguntar primero#

1. El agente le dice a quien llama que iniciará la transferencia; luego, quien llama escucha música de espera mientras suena el destino.
2. Cuando el destino responde, el agente deja que la persona que responde termine primero su saludo, evaluado de la misma forma que se indicó arriba. Si el anuncio de consentimiento del agente está activado, la persona que responde lo escucha primero. Luego, el agente dice su resumen y pregunta si puede atender la llamada. Quien llama, en espera, no escucha nada de esto.
3. La persona puede hacer preguntas, que el agente responde con base en la conversación hasta ese momento. Si acepta, se conecta a quien llama, el agente presenta a quien llama en una o dos frases que ambos escuchan, y se desconecta.
4. Si rechaza la llamada, no responde o la llamada llega al buzón de voz, ThunderPhone finaliza esa llamada y quita a quien llama de espera. El agente recibe el resultado, incluido cualquier mensaje que la persona le haya pedido transmitir, y continúa con quien llama.

Con este estilo, la transferencia no detiene la grabación de la llamada. Si el agente graba llamadas, se graban tanto la conversación privada con la persona que responde como la llamada conectada. Si la grabación de llamadas está desactivada para el agente, no se graba ninguna de las dos.

Con Susurro#

1. El agente le dice a quien llama que iniciará la transferencia; luego, quien llama escucha música de espera mientras suena el destino.
2. Cuando el destino responde, el agente espera a que la persona que responde termine su saludo. Si el anuncio de consentimiento del agente está activado, la persona que responde lo escucha primero. Luego, el agente le dice, en una breve frase, quién llama y por qué. No pregunta si puede atender la llamada. Quien llama, en espera, no escucha nada de esto.
3. Se conecta a quien llama y el agente se desconecta. No se dice nada en la línea.
4. Si la llamada llega al buzón de voz, el agente cuelga y quita a quien llama de espera. Si el destino no responde, está ocupado o no se puede realizar la llamada, quien llama también vuelve al agente. El agente recibe el resultado y continúa con quien llama.

La grabación funciona como con Preguntar primero: si el agente graba llamadas, se graban tanto la frase privada como la llamada conectada.

Indica al agente cómo transferir correctamente#

Incluye las reglas de enrutamiento en el prompt del agente y nombra cada destino exactamente como aparece en Números de transferencia. No escribas números de teléfono en el prompt; el agente transfiere por nombre. Especifica el modo de transferencia para cada ruta y proporciona al agente una alternativa para las transferencias en caliente fallidas.

Transfer policy
 
Confirm the caller's name and reason for calling before any transfer.
 
| Caller needs | Destination | Transfer mode |
| --- | --- | --- |
| A new purchase or plan change | Sales | warm |
| Help with an existing order | Order support | warm |
| The main office | Front desk | cold |
 
For a warm transfer:
- Keep the introduction to one or two short sentences: who is calling and
  why.
- Do not plan to speak after the introduction because you will be dropped.
- If the target does not answer or is busy, tell the caller what happened,
  then offer to take a message or try another route. Do not cold-transfer
  unless the caller asks.

El agente proporciona estos campos cuando llama a la acción integrada:

No necesitas definir ni adjuntar una herramienta personalizada llamada transfer_call. La descripción de la acción sigue la configuración de Antes de conectar e Información previa del agente, por lo que el prompt no necesita repetirla.

Cuando se rechaza una transferencia#

ThunderPhone verifica cada transferencia antes de realizarla. Rechaza una transferencia cuando el nombre no es uno de los números de transferencia del agente, cuando un número variable no tiene un valor válido en esta llamada o cuando una transferencia realizada a través de la línea de ThunderPhone llegaría a un número fuera de Estados Unidos o a un número de tarifa premium.

Una transferencia rechazada no finaliza la llamada. El agente no anuncia la transferencia, recibe el motivo (incluida la lista de nombres válidos cuando el nombre no coincidió) y sigue hablando con quien llama. Indícale en el prompt qué hacer en su lugar, como tomar un mensaje. El rechazo aparece como un error de herramienta en el historial de la llamada.

Transferencias con susurro#

“La transferencia con susurro” es un nombre común en la industria para una transferencia asistida en la que el destino escucha contexto privado antes de conectar a quien llama, sin que se le pregunte si desea tomar la llamada. Esa es la configuración Susurro en Antes de conectar.

Esto es diferente de POST /v1/calls/{id}/whisper. Ese endpoint permite que un miembro del personal o propietario envíe orientación privada por texto al agente de IA durante una llamada en vivo. No llama ni proporciona contexto a un destino de transferencia.

Requisitos, límites y pruebas#

Webhooks y motivos de finalización#

La carga útil de finalización registra el destino en transfer_number y usa uno de estos motivos de finalización:

Un intento en caliente sin respuesta, ocupado o fallido no es una transferencia completada. Quien llama regresa al agente, por lo que el motivo de finalización final refleja lo que finaliza la llamada original.

Para una transferencia en caliente exitosa, el evento de finalización y el motivo de finalización de la llamada de IA se registran cuando la IA se retira, justo después de que las partes se conectan. Con Presentar en la línea, la grabación cubre la llamada hasta la transferencia y termina allí (recording_stopped_at); la conversación entre las dos personas no se graba ni se transcribe. Con Preguntar primero y Susurrar, la grabación (cuando el agente graba llamadas) continúa hasta que finaliza la llamada conectada.

Consulta Webhooks de finalización para ver la carga útil completa y el comportamiento heredado.

Solución de problemas#

La llamada se corta cuando el agente transfiere#

Verifica el país de destino. Las llamadas en números de ThunderPhone solo admiten transferencias a números de Estados Unidos. El operador puede rechazar una transferencia a otro país, lo que desconecta a quien llama, y la llamada igualmente termina con ai_transfer. Para llegar a otros países, conecta tu propio operador y enruta la llamada a través de un número importado desde él. El operador debe aceptar transferencias de llamadas y permitir llamadas a ese país. En un troncal SIP de Twilio, activa Transferencias de llamadas y Habilitar transferencias de llamadas a la PSTN.

El agente realiza una transferencia en frío en lugar de una cálida#

Verifica que la llamada use un número que pueda realizar llamadas salientes: un número VoIP verificado e importado con enrutamiento saliente funcional, o un número de ThunderPhone con llamadas salientes aprobadas. El modo asistido se elimina de las opciones de la herramienta para otros números y para sesiones que no son telefónicas. También especifica el modo en la tabla de enrutamiento del prompt.

El destino nunca responde#

Confirma que tu troncal VoIP puede realizar llamadas salientes al destino y que sus reglas de autenticación y enrutamiento estén actualizadas. Revisa el número guardado en Números de transferencia. Aumenta ring_duration_seconds si 45 segundos es demasiado poco tiempo para una transferencia con consulta.

El destino llega al buzón de voz#

Con Presentar en la llamada, quien llama se conecta con quien responda, incluido un saludo de buzón de voz. El agente reconoce el saludo, no dice nada en el buzón y se desconecta, y quien llama puede dejar un mensaje. Con Preguntar primero y Susurrar, el agente cuelga al detectar el buzón de voz y quien llama regresa al agente. Si un destino suele ir al buzón de voz, indícale al agente otra ruta para ese caso en el prompt.

Una transferencia en frío espera antes de conectarse#

Si usas el webhook heredado de una sola URL, verifica si devolvió {"transfer_ready": false}. Quien llama escucha música de espera mientras ThunderPhone espera. Actualiza el estado de transferencia lista de la llamada cuando el destino esté preparado.

El agente dice que no puede transferir#

Verifica que el agente tenga números de transferencia y que el prompt use los mismos nombres. Un agente sin números de transferencia no tiene ninguna acción de transferencia. Si la transferencia se realiza a través de la línea de ThunderPhone (consulta Qué números puede alcanzar una llamada), el destino debe ser un número de Estados Unidos que no sea de tarifa premium. Para un número variable, verifica que las variables de la llamada incluyan un número de teléfono válido para él.

La implementación falla con un error de número de transferencia#

Cada implementación vuelve a verificar los números de transferencia guardados. Un número fuera de Estados Unidos guardado mientras tu organización tenía un número con su propio operador no supera la verificación cuando esa organización ya no tiene uno. Elimina el número o vuelve a conectar tu propio operador.

El susurro al personal no inicia una transferencia#

El susurro en llamadas en vivo solo orienta a la IA. Agrega instrucciones de transferencia al prompt del agente y deja que llame a transfer_call. Consulta Monitorear llamadas en vivo.