Parámetros de entrada, body template, headers y mapeo de respuesta

Cómo definir los datos que el agente envía a tu API y cómo extraer de la respuesta solo el valor que necesita.

Jun 26, 2026

Mira este paso en el video · Acciones personalizadas: parámetros, variables y prueba

Para qué sirve esta configuración

Una vez creada la acción, estos cuatro bloques definen qué le manda el agente a tu API y qué te devuelve a la conversación: los parámetros de entrada, el body template, los headers y el mapeo de respuesta. Configurarlos bien es lo que hace que la integración sea fiable.

Parámetros de entrada (input_schema)

Son los datos que el modelo debe completar antes de llamar al endpoint. En la sección Parámetros de entrada pulsa Agregar parámetro y define para cada uno:

  • Nombre: identificador del campo (p. ej. email, plan_id).
  • Tipo: string, number, boolean, email o phone.
  • Descripción: explica qué es; el modelo la usa para rellenar el valor correcto.
  • Requerido: marca la casilla si el agente no puede llamar la acción sin ese dato.

El modelo deduce estos valores de la conversación. Por eso una buena descripción (p. ej. "correo del cliente para buscar su pedido") mejora mucho la precisión.

Body template

Es el cuerpo que se envía en métodos POST, PUT o PATCH (en GET no se usa). Se escribe en JSON y admite variables que se reemplazan al ejecutar:

{
  "email": "{{input.email}}",
  "canal": "{{contact.email}}"
}
  • {{input.nombre}} inserta un parámetro de entrada.
  • {{contact.email}} y otros campos del contacto insertan datos de quien chatea.

Si declaras un header Content-Type: application/json, el body se envía como JSON; en caso contrario se manda como texto plano.

Headers

En Headers pulsa Agregar header y añade pares clave/valor. El más común es la autenticación:

  • Authorization → Bearer TU_TOKEN
  • Content-Type → application/json

Puedes definir hasta 20 headers. Los valores también admiten variables {{...}}.

Campo a extraer (response_mapping)

Tu API suele responder un JSON grande, pero al agente solo le interesa un valor. En Campo a extraer (response_mapping) indica la ruta con puntos hacia ese dato:

  • Respuesta {"data": {"plans": [...]}} → escribe data.plans.
  • Si lo dejas vacío, el agente recibe la respuesta completa.

Esto mantiene el contexto del modelo limpio y enfocado solo en lo útil.

Verificación

  • Cada parámetro requerido aparece con su casilla Requerido marcada.
  • El Body template es JSON válido (llaves balanceadas) y usa solo variables que existen.
  • Tras Guardar acción, usa Probar para confirmar que tu API recibe los campos y que el Campo a extraer apunta al dato correcto.

Si no funciona

  • Llega vacío un dato: revisa que el nombre de la variable {{input.x}} coincida exactamente con el Nombre del parámetro.
  • Tu API rechaza el body: añade el header Content-Type: application/json y valida que el JSON esté bien formado.
  • El agente devuelve "demasiada información": define el Campo a extraer para quedarte solo con el valor necesario.

Tip: empieza con pocos parámetros y solo los Requeridos imprescindibles. Cuantos menos datos tenga que adivinar el modelo, más fiable es.

Tip: nunca pongas tokens en la URL; ponlos en Headers (Authorization).

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp