Acciones: respuestas desde tu propio sistema

Una acción permite a tu bot consultar algo en tu propio sistema en mitad de un chat — dónde está un pedido, cuándo se entregará, si una reserva está confirmada. El cliente pregunta, el bot recoge lo que necesita, llama a tu API y responde a partir de lo que recibe, en el idioma del cliente.

Funciona en todos los sitios donde funciona tu bot: el widget web, el enlace y código QR de tu bot, y las aplicaciones de Android, iOS, React Native, Flutter e Ionic. No se instala ni se actualiza nada — la llamada se hace desde nuestros servidores, así que tus credenciales de API nunca llegan a un navegador ni a un teléfono.

Antes de empezar: cualquiera puede chatear con tu bot

Tu bot es un chat público. Si con solo el número de pedido basta para ver un pedido, cualquiera puede escribir números hasta que uno funcione.

El bot ayuda de tres maneras, pero ninguna sustituye esa comprobación: solo envía valores que el cliente realmente escribió, limita cuántas consultas puede hacer un chat o una dirección, y tú puedes elegir qué campos de la respuesta tiene permitido ver.

Configurar una

Abre Acciones en el panel y elige Nueva acción. Los propietarios y administradores pueden ver esta pantalla.

• Nombre — para ti, como «Estado del pedido».
• ¿Cuándo debe usarla el bot? — una frase, como se lo contarías a un nuevo compañero: «El cliente pregunta dónde está su pedido o cuándo llegará.»
• Dirección de tu API — GET o POST, y una dirección https://. Escribe {{order_id}} donde va un valor.
• Lo que el bot pide al cliente — hasta seis valores. Cada uno tiene una etiqueta con tus palabras («Número de pedido»), el nombre que usa tu API (order_id) y un tipo: cualquier texto, un número, una dirección de correo electrónico o un número de teléfono.
• Cabeceras — tu clave API o token. Se guarda cifrado y no vuelve a mostrarse.
• Compartir solo estos campos con el bot — opcional. Enumera las partes de la respuesta que el bot puede usar, como status, eta, items[].name. Todo lo demás se descarta antes de que la IA lo vea.

Pulsa Probar, escribe valores de ejemplo y verás la solicitud enviada y exactamente lo que recibiría el bot. Luego pruébalo de verdad en la pantalla Probar: «¿Dónde está mi pedido 48213? Mi correo es asha@example.com».

Lo que recibe tu API

Con GET, los valores que colocaste en la dirección se rellenan y el resto se añaden a la cadena de consulta:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Con POST, los valores son el cuerpo JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Cada solicitud lleva además tus propias cabeceras y estas:

Qué devolver

Responde en menos de 8 segundos con JSON, o con una línea corta de texto plano.

• 200 con los datos — el bot responde a partir de ellos. Mantenlo pequeño y usa nombres de campo claros: {"status":"shipped","eta":"2 October"} funciona mejor que códigos internos.
• 404 cuando nada coincide — el bot se lo dice al cliente y le pide que revise lo que escribió.
• Cualquier otra cosa, o sin respuesta a tiempo — el bot se disculpa, ofrece tus datos de contacto y el chat queda marcado para ti. El motivo se muestra en la pantalla Acciones.

No se siguen redirecciones, y una respuesta de más de 256 KB no se lee.

Comprobar la firma

Las solicitudes se firman al estilo de Standard Webhooks, así que puedes usar una biblioteca existente. Tu secreto de firma está en la pantalla Acciones.

A mano: une el id, la marca de tiempo y el cuerpo exacto con puntos, firma eso con HMAC-SHA256 usando el secreto (la parte después de whsec_, decodificada en base64) y compara.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

En una solicitud GET el cuerpo va vacío, así que el texto firmado termina en punto. Usa POST si quieres que los propios valores queden cubiertos por la firma.

Cómo la usa el bot

• Pide todo lo que falte, una pregunta corta cada vez, y recuerda lo que el cliente dijo antes en el chat.
• Nunca adivina un valor. Si el cliente no lo escribió, el bot lo pide.
• Una consulta por mensaje. Tus respuestas guardadas siguen teniendo prioridad, así que una pregunta que hayas respondido a mano nunca llama a tu API.
• Las respuestas de una consulta nunca se reutilizan para otro cliente.
• Una consulta cuenta como una respuesta, como cualquier otra respuesta que escribe la IA.

En Chats, una respuesta que vino de una consulta lo indica debajo: qué acción se ejecutó y cómo terminó. Los valores que escribió el cliente se quedan en la transcripción y en ningún otro sitio.

Límites

Las acciones leen información. No apuntes una a una dirección que cambie algo — cancelar un pedido o emitir un reembolso necesita un paso de confirmación que el bot aún no tiene.