Conversaciones
Las reglas de un chat con un bot. Nunca escribe primero, Empezar manda /start, contesta por turnos y la persona lo puede detener.
Un chat con un bot sigue unas reglas simples. Entenderlas evita casi todos los errores.
El bot nunca escribe primero
Un bot solo puede escribirle a alguien que le escribió antes (cualquier mensaje) o que tocó Empezar. Si intenta escribir antes, la API responde FORBIDDEN con mensaje notAllowed.
Mientras la persona no empiece, en lugar del campo de texto la app muestra un botón Empezar con el aviso «Lo que le escribes a este bot lo lee quien lo maneja».
Quién puede hablar con un bot
Los bots no hablan con otros bots. De 16 a 17 años solo hablan con un bot que el equipo de Huwi marcó como apto (Apto 16-17 en el menú de @gepeto). Antes de los 16 no hablan con bots.
Empezar y el /start
Al tocar Empezar, la app manda /start como un mensaje más. Tu bot lo recibe como una novedad message con command: "start":
{
"type": "message",
"chatId": "107652219945181184",
"payload": { "text": "/start", "userId": "362387869790208", "command": "start", "messageId": "107652223229321216" }
}Si la persona llega por un enlace con carga útil, el texto trae lo que sigue: /start promo42. La carga útil sale del text (hasta 64 caracteres, sin espacios): text.split(" ")[1]. Sirve para saber de qué campaña o página vino.
Contesta por turnos
Cada mensaje de la persona o toque en un botón es un turno. Por cada turno, el bot tiene 5 mensajes de respuesta. No importa cuánto tarde: un webhook que contesta segundos o minutos después sigue siendo una respuesta.
persona escribe → turno nuevo → el bot puede mandar 5 mensajes
persona toca un botón → turno nuevo → otros 5Si el bot manda más allá de esos 5 sin un turno nuevo, esos mensajes cuentan contra un tope de 10 por día en ese chat. Pasado ese tope, la API responde TOO_MANY_REQUESTS con botRate.
| Situación | Qué pasa |
|---|---|
| La persona escribe y el bot contesta hasta 5 veces | Normal. |
| El bot manda mensajes sin que la persona haya escrito | Hasta 10 por día por chat. |
| El bot manda más de 5 mensajes en 5 segundos en un chat | botRate (ráfaga). Espera unos segundos. |
| La persona detuvo el bot | notAllowed. Si le vuelve a escribir, se reanuda. |
Pensando en avisos
Un aviso de tu servicio («tu pedido salió») es un mensaje sin turno nuevo: gasta el tope de 10 por día. Para avisos frecuentes, pídele a la persona que toque un botón o escriba de vez en cuando: cada vez abre un turno.
Comandos
Un comando es un mensaje que empieza con /. Tu bot los recibe con command en minúsculas y sin @: /help@aurora_bot hola llega con command: "help".
Los comandos que guardes con bot.setCommands aparecen en el menú Menú del chat y al escribir /, como en Telegram:
curl -s "https://huwi.app/api/trpc/bot.setCommands" \
-H "x-api-key: $HUWI_KEY" -H "content-type: application/json" \
-d '{"json":{"commands":[{"command":"help","description":"Qué puedo hacer"},{"command":"pedido","description":"Ver el estado de mi pedido"}]}}'El nombre del comando: de 1 a 32 caracteres, solo a-z, 0-9 y _. La descripción: hasta 80. Hasta 30 comandos. Mira el ejemplo completo.
Botones y toques
Los botones de un mensaje con components se comportan según su kind:
kind | Qué hace |
|---|---|
callback | Te llega una novedad action con el id del botón y data: null. |
submit | Igual, pero con lo que la persona escribió en los campos de un form: data: { campo: valor }. |
reply | Igual, con data: { text: <value> }. No escribe nada en el chat: lo decides tú. |
copy | Hoy la app lo trata como un botón común (llega action); todavía no copia al portapapeles. |
link | Abre value (una dirección) en otra pestaña. |
open | Abre value, una ruta de Huwi (/@usuario). |
checkout | Abre una dirección de pago en la web. En la app de iPhone y Android aparece deshabilitado. |
pay | Reservado para las monedas: hoy se muestra como Próximamente. |
El toque llega así:
{
"type": "action",
"chatId": "107652219945181184",
"payload": {
"action": "track",
"token": "9b8a5930-501a-4e71-a7dd-462a52640fd0",
"userId": "362387869790208",
"messageId": "107652303575408640",
"data": null
}
}Mientras el bot responde, el botón gira y los demás se apagan. Contesta con message.send (un toque es un turno) y, si quieres, con bot.answerAction pasando el token.
Estado de bot.answerAction
bot.answerAction responde { ok: true }, pero hoy, con la base de datos real, el aviso corto (toast) todavía no
llega a la pantalla de la persona. Contesta también con un mensaje.
Detener un bot
En la información del chat hay Detener bot. Al detenerlo:
- tu bot recibe una novedad
{ "type": "stopped", "payload": { "userId": "…" } }; - el bot ya no puede escribirle (
notAllowed); - si la persona vuelve a escribirle o toca Empezar, la conversación se reanuda.
Un bot también se bloquea y se denuncia como cualquier cuenta. Bloqueado, no puede contestar.
Un solo chat directo
Entre dos cuentas hay un solo chat directo. Si la persona abre el bot desde otro dispositivo, es el mismo chat.
Grupos
Mira Grupos: ahí no hay turnos y las reglas son distintas.