Skip to main content
Una herramienta HTTP permite consultar o modificar tu sistema durante la conversación. El agente decide cuándo ejecutarla según su descripción y las instrucciones. Tu endpoint devuelve información que el agente usa para continuar.

​
Elegí el tipo de agente

Agregá una herramienta Personalizada. Guardá y publicá el agente. Tu endpoint recibe un POST con call, tool_name y args.Configurar herramientas de voz · Ver campos de voz

​
Recorrido: consultar un pedido

1

Definí qué necesita tu API

Creá consultar_pedido con el parámetro obligatorio numero_pedido. Describí cuándo usarla y cómo pedir el dato faltante.
2

Separá parámetros y contexto

El número del pedido llega en args.numero_pedido. ContactShip agrega por separado el contexto call o thread. No hace falta pedirle al cliente IDs internos.
3

Consultá tu sistema

Tu receptor lee los argumentos, valida los datos y busca el pedido. Usá call.call_id o thread.id para relacionar registros de diagnóstico.
4

Devolvé el resultado útil

Respondé con JSON válido y datos concretos. Si no encontraste el pedido, indicá ese resultado. Evitá respuestas vacías que obliguen al agente a adivinar.
5

Probá la conversación completa

Verificá la conexión desde el configurador. Después, ejecutá un caso controlado con el agente y compará la petición real y su respuesta.
Los campos de respuesta son un ejemplo de tu contrato, no campos obligatorios de ContactShip. Configurá las instrucciones para interpretar ambos resultados.

​
Qué dato sale de dónde

El contexto depende del caso. En voz web los teléfonos pueden estar vacíos. En texto algunos datos del canal pueden faltar. Consultá los campos y ejemplos completos.

​
Qué demuestra cada prueba

Los botones de prueba HTTP envían peticiones reales. En voz, los headers configurados se usan en la prueba, pero la ejecución actual no los reenvía al endpoint. Si necesitás autenticación por header, coordiná la integración con soporte y verificá una llamada real.

​
Herramienta, webhook o automatización

Necesito un dato durante la conversación

Usá una herramienta y devolvé el resultado en la respuesta HTTP.

Necesito actuar cuando termina

Elegí el webhook correspondiente al evento y su contrato.

Necesito reaccionar a una regla del inbox

Configurá disparador, condiciones y acciones.

Necesito crear un seguimiento

Elegí el evento y mapeá los datos que deciden la acción.

​
Preguntas frecuentes

No. Configurá solo los argumentos que tu herramienta necesita extraer. ContactShip agrega el contexto correspondiente.
La herramienta espera una respuesta en esa ejecución. Para trabajos largos, devolvé un estado real como pendiente y una referencia propia. Diseñá por separado cómo informar el resultado final.
En los logs del endpoint o el historial del workflow. En texto, compará también el payload del configurador. El registro de webhooks posteriores a llamadas corresponde a otro evento.
Una conversación puede ejecutar la misma herramienta varias veces legítimamente. Para operaciones que crean o cobran, usá un identificador de operación de tu negocio y conservá su resultado.