En una línea
Una tool es una pregunta. Un webhook es un aviso. Una tool es algo que el agente le pregunta a tu API a mitad de la conversación, y se queda esperando tu respuesta para seguir hablando. Un webhook es Ryvo contándote algo que ya pasó, después, sin que nadie espere.Una al lado de la otra
¿Cuál necesito?
Necesitas una tool cuando el agente tiene que saber algo para hacer su trabajo: consultar un saldo, buscar un pedido, confirmar disponibilidad, crear un ticket mientras el cliente sigue en la línea. Si la respuesta cambia lo que el agente dice a continuación, es una tool. Necesitas un webhook cuando tu sistema tiene que reaccionar a algo que Ryvo ya hizo: registrar la conversación, actualizar el deal, disparar un seguimiento, mandar la transcripción a tu almacén de datos. Si nadie está esperando la respuesta, es un webhook.No son excluyentes y la mayoría usa las dos. Un agente de ventas puede llamar
a tu CRM como tool para saber el plan del cliente a media llamada, y
recibir después un webhook de
conversation.ended para registrar el resultado.Por qué el nombre confunde, con honestidad
En el constructor, el tipo de tool que apunta a tu API se llama Solicitud API, pero por dentro su tipo guardado todavía eswebhook. Es un nombre
histórico que estamos corrigiendo. Si lo ves en una exportación o en una
respuesta de la API, es una tool: la llama el agente, no es un aviso.
Dos errores que vale la pena evitar
No verifiques firma en una tool. Las llamadas de tool no llevanX-Ryvo-Signature hoy. Si tu endpoint rechaza lo que no venga firmado, la
llamada del agente falla y la conversación se atora. Usa un bearer o una
cabecera con API key en la tool, que se configura junto con ella.
No hagas trabajo lento dentro de una tool. El agente espera, y la persona
en la llamada también. Si el trabajo tarda más de un par de segundos, que la
tool conteste de inmediato y el resto lo haces cuando llegue el webhook de
conversation.ended.