Conectar tu API
Parámetros, respuesta y pruebas paso a paso.
Qué recibe tu endpoint
Campos automáticos y JSON de voz y texto.
El catálogo
- Añadir abre Añadir herramienta. Las herramientas que solo admiten una instancia muestran Ya añadida. Las de calendario sin integración muestran Conéctala en Integraciones, ver Catálogo de integraciones.
- Cada fila de la lista tiene un menú con Editar y Quitar. Quitar pregunta “El agente dejará de poder usar . Puedes volver a añadirla más adelante.”
- Sin herramientas, la pestaña ofrece accesos directos a Transferencia de llamada, Personalizada y Google Calendar.
Transferencia, traspaso, personalizada y base de conocimiento forman parte del borrador: se aplican cuando publicás. Las de calendario no: “Las herramientas de calendario se aplican al instante. No forman parte del borrador ni esperan a la publicación.”
- Nombre: “Letras, números, guiones y guiones bajos. Sin espacios.” Hasta 64 caracteres y único dentro del agente. Es el nombre con el que la IA conoce la herramienta y el que insertás con
@en el prompt. - Descripción: hasta 2.000 caracteres. “Indica al agente cuándo debe recurrir a esta herramienta.” Es el criterio principal con el que el agente decide usarla.
- Hablar mientras se ejecuta con Qué decir (“El agente lo parafrasea, no lo lee literalmente.”), y Hablar al terminar (“El agente comenta el resultado cuando la herramienta responde.”).
Transferencia de llamada
Con Transferencia con aviso aparecen estas opciones:
Opciones avanzadas, plegadas al final del formulario:
Traspaso de agente
El traspaso mantiene la misma llamada y cambia el agente que la conduce. Es la base del patrón “agente de triage más agentes especializados”: un agente detecta la intención y traspasa a ventas, soporte o cobranzas.
Personalizada
Parámetros
Cada parámetro tiene un nombre en minúsculas, números y guiones bajos, un Tipo, una descripción y el interruptor Obligatorio, activado por defecto en los parámetros nuevos.
El constructor visual admite un nivel de anidamiento. Un esquema más profundo se muestra como “Tiene demasiados niveles para editarlo acá. Cambiá a raw para modificarlo.” El botón Raw muestra el esquema JSON completo: “Usa un objeto con type, properties y required opcional.” Al volver a Visual, la app valida el JSON. Sin parámetros, la ejecución real conserva
call y tool_name, con args: {}. El cuerpo inicial de Probar el endpoint es {}.
Los Headers también tienen vista Raw: “Pegá un objeto JSON o un header por línea, como Nombre: valor.”
Probar el endpoint
El panel Probar el endpoint “Envía una petición real con los headers y parámetros de arriba.” Muestra la URL de la petición y un Cuerpo de la petición de ejemplo, generado a partir de los parámetros, que podés editar. Enviar petición hace un POST desde los servidores de ContactShip conContent-Type: application/json si no definiste otro, y muestra el código de estado en verde si es menor que 400 o en rojo si no, la duración en ms, los Headers de la respuesta y el Cuerpo de la respuesta formateado. Si el cuerpo supera los 10 KB, avisa “La respuesta se cortó en 10 KB.” La petición no sigue redirecciones.
Comportamientos que hay que conocer:
- Si el endpoint no responde en 10 segundos, la prueba falla con “El endpoint no respondió en 10 segundos.”
- Las direcciones locales o privadas (localhost, redes internas, dominios .local o .internal) no se pueden probar: “Esa dirección no es alcanzable desde el servidor.” Usá una URL pública.
- La prueba no es una llamada: no consume créditos y no pasa por el agente.
Ejemplo: consultar el estado de un pedido
Una herramienta para una tienda que quiere que el agente informe el estado de un pedido.
Parámetros en vista Raw:
call, tool_name y args. Leé el pedido desde args.numero_pedido. Respondé con JSON. Respondé corto y en texto legible, por ejemplo {"estado": "En camino", "entrega_estimada": "jueves 12 de septiembre"}: el agente usa ese texto para contestar. Después, mencioná la herramienta en el prompt con @ y describí cuándo usarla, ver Instrucciones.
Base de conocimiento
La herramienta busca en las bases conectadas al agente en la pestaña Conocimiento. Si no hay ninguna conectada, el formulario queda deshabilitado y avisa “Sin base de conocimiento conectada. Esta herramienta no devolverá nada hasta que conectes una.” con el botón Conectar base. Si la organización no tiene bases, ofrece Ir a Recursos. En el prompt aparece como
knowledge-base. Cómo crear y cargar bases está en Base de conocimiento.
Cal.com
Requiere la integración Cal.com en estado activo, ver Cal.com. Antes de abrir el formulario, la app valida la integración; si falla, muestra “Hay que volver a conectar la integración.” Los cambios se aplican al instante, sin publicar.
Google Calendar
Requiere la integración Google Calendar activa, ver Google Calendar. La herramienta consulta la disponibilidad de los próximos 7 días y crea el evento cuando la persona confirma. Se aplica al instante, sin publicar.
Qué no existe todavía
- El formulario de la herramienta personalizada no tiene campos para query params ni para el tiempo de espera. Si la herramienta ya los tenía, se conservan.
- No hay herramientas nativas para enviar SMS, WhatsApp o correo durante la llamada. Se resuelve con una herramienta personalizada que llame a tu sistema.
- La transferencia va a un número o a una SIP URI. No transfiere a un usuario ni a una cola del contact center.
- Calendly no está disponible como herramienta de calendario.
Problemas frecuentes
Preguntas frecuentes
¿Cuándo transfiere el agente a una persona?
¿Cuándo transfiere el agente a una persona?
Cuando el prompt y la Descripción de la herramienta se lo indican: pedido explícito del cliente, un tema fuera de su alcance, un horario. Fuera de horario podés quitar la transferencia o pedirle que ofrezca una devolución de llamada. Con Transferencia con aviso, además puede explicarle el caso a quien recibe.
¿El agente puede cobrar dentro de la llamada?
¿El agente puede cobrar dentro de la llamada?
No toma datos de tarjeta. Lo habitual es una herramienta personalizada que genere un link de pago y lo envíe por WhatsApp, SMS o correo desde tu sistema; la confirmación llega por el webhook de tu proveedor de pagos.
¿Cómo registro los datos de la llamada en mi CRM o ERP?
¿Cómo registro los datos de la llamada en mi CRM o ERP?
En tiempo real, con una herramienta personalizada que envíe los datos durante la llamada. Al terminar, con el webhook de post llamada, que incluye transcripción, resumen y datos extraídos. Ver Post llamada.
¿Por qué falla el agendamiento con Cal.com?
¿Por qué falla el agendamiento con Cal.com?
Las causas más comunes: la zona horaria de la herramienta no coincide con la de Cal.com, el tipo de evento no tiene disponibilidad definida, o el agente no confirmó el correo del cliente antes de reservar. Pedile en el prompt que repita el correo antes de agendar.
¿Por qué el agente cortó diciendo que se agotaron las interacciones?
¿Por qué el agente cortó diciendo que se agotaron las interacciones?
Si el agente ejecuta la misma herramienta sin éxito más de 15 veces, la llamada se corta. Casi siempre es un endpoint que devuelve error o una descripción ambigua. Probá la herramienta con Probar el endpoint y ajustá la descripción.
¿El agente puede colgar solo?
¿El agente puede colgar solo?
Sí. Todo agente de voz puede terminar la llamada cuando las dos partes se despiden. No es una herramienta del catálogo y no se configura.
¿Conviene un agente único o varios?
¿Conviene un agente único o varios?
Varios agentes especializados con un agente de triage que derive con Traspaso de agente. Un “mega agente” con muchas tareas se equivoca más. Para el análisis de esas llamadas, elegí en Análisis posterior si se evalúan ambos agentes o solo el destino.