Karai atiende por cinco canales. Dos se conectan en minutos y no dependen de nadie más. Los tres de Meta —WhatsApp, Messenger e Instagram— pasan por trámites que no controlamos ni podemos apurar. Acá está todo: qué te hace falta antes de empezar, qué se pega en cada campo del panel, cómo verificar que quedó bien y qué es lo que más se rompe.
Cinco cosas que valen para todos los canales. Si las tenés claras, el resto de la página es copiar y pegar.
Entrás al panel en /admin con tu cuenta y vas a la pestaña
Canales. Ahí están los cinco, uno debajo del otro, con su
botón de Guardar y su botón de Probar.
Hace falta una cuenta con rol admin: un operador atiende
conversaciones desde la bandeja, pero no toca credenciales.
Cuando volvés a abrir el panel, ningún secreto se muestra: en su lugar ves
puntitos con los últimos cuatro caracteres (••••7777). No es
una molestia de diseño, es lo que hace que un token de panel filtrado no
se convierta en acceso a tu ERP y a tus cuentas de Meta.
Dejar un campo de contraseña vacío significa «no lo toques», no «borralo». Como el panel nunca pudo mostrarte el valor, tampoco puede devolvértelo. Así, cambiar el nombre visible del remitente no te borra la contraseña del correo.
WhatsApp, Messenger e Instagram funcionan con webhooks: Meta le pega a una URL tuya cada vez que alguien te escribe. Esa URL tiene que ser https con certificado válido — Meta no acepta http ni certificados autofirmados. El correo y el chat web no tienen este requisito: el correo sale a buscar los mensajes y el chat web viaja en tu propia página.
Si es Karai como servicio, la URL ya está y el panel te la muestra hecha. Si
lo instalaste en tu servidor, es lo que hayas puesto en
SA_PUBLIC_BASE_URL.
Cuando das de alta el webhook, Meta hace una llamada de verificación y espera que le devuelvas un desafío. Karai sólo lo responde si ya tiene guardado ese verify token. Si configurás primero del lado de Meta, la verificación falla con un 403 y parece un problema que no es.
No hace falta reiniciar nada. Karai cachea 60 segundos a qué empresa pertenece cada número y cada página, y guardar en el panel limpia ese caché en el acto.
Es el único canal que no depende de la aprobación de nadie, el que se instala pegando una línea, y el único que no te cobra por mensaje además del plan. Si estás evaluando Karai, empezá por acá: podés tenerlo andando en el sitio de tu empresa antes de que Meta te conteste el primer trámite.
/admin → Canales → Chat web.
Arriba de todo, porque es el que no requiere nada.
</body>.
Si tu gestor de contenidos tiene una caja de «scripts
personalizados» o «código en el pie», va ahí.
<script src="https://tu-stack/widget.js"
data-org="el id de tu empresa"
data-channel="el id del canal web"
data-api="https://tu-stack"
data-color="#2B6BF6"></script>
Los cuatro primeros los completa el panel. Los otros son opcionales y se agregan a mano si querés cambiar cómo se presenta.
| Atributo | Qué es | Si no lo ponés |
|---|---|---|
data-org |
El identificador de tu empresa. | Obligatorio. Sin él el widget no se dibuja. |
data-channel |
El identificador del canal web. | Obligatorio. Sin él el widget no se dibuja. |
data-api |
La dirección de tu instalación de Karai. | El widget queda sin a dónde escribir. |
data-color |
El color de la burbuja, la cabecera y tus mensajes. | #2B6BF6 |
data-title |
El título de la ventanita. | Ventas |
data-subtitle |
La línea de abajo del título. | Respondemos al instante |
data-greeting |
El primer mensaje, antes de que la persona escriba. | ¡Hola! ¿En qué te puedo ayudar hoy? |
/console, con
las consultas que hizo el agente intercaladas.faltan data-org o data-channel, tu gestor de contenidos comió
los atributos al guardar — pasa con los editores que «limpian» el HTML.
Buscá la opción de insertar código sin filtrar.Karai revisa cada tanto tu casilla de ventas y contesta por el servidor de tu empresa, con tu propia dirección. No hace falta abrir puertos, ni tener dominio público, ni contratar un servicio de correo aparte: si tu casilla tiene IMAP y SMTP —y las tienen todas— alcanza.
myaccount.google.com/apppasswords. No sirve la contraseña
con la que entrás al correo.
Karai marca como leídos los correos que procesa. Si lo
apuntás a la casilla que una persona usa todos los días, le vas a mover
los no leídos. Lo natural es una dirección tipo
ventas@ o consultas@.
imap.gmail.com puerto
993, y smtp.gmail.com puerto 587.
/admin → Canales → Correo y completá los
campos de la tabla de acá abajo.| Campo del panel | Qué va | Ejemplo |
|---|---|---|
| Servidor IMAP | El host desde el que se leen los correos. Obligatorio. | imap.gmail.com |
| Puerto (IMAP) | Viene en 993, que es IMAP sobre SSL. | 993 |
| Servidor SMTP | El host por el que se responde. Obligatorio. | smtp.gmail.com |
| Puerto (SMTP) | Viene en 587, que es SMTP con STARTTLS. | 587 |
| Usuario | La dirección completa con la que se autentica. Obligatorio. | ventas@empresa.com.py |
| Contraseña | La de la casilla, o la contraseña de aplicación si es Gmail. Obligatorio. | xxxx xxxx xxxx xxxx |
| Remitente | La dirección que ve tu cliente. Obligatorio, y conviene que sea la misma casilla que se sondea: es el dato con el que Karai reconoce que un correo entrante es tuyo. | ventas@empresa.com.py |
| Nombre visible | El nombre que aparece antes de la dirección. Opcional. | Ventas Empresa |
Buzón distinto de INBOX, otro intervalo de sondeo, SMTP en el
puerto 465 con SSL directo o un usuario de envío distinto al de lectura:
Karai los soporta, pero no están en el formulario del panel porque casi
nadie los necesita. Se cargan del lado del servidor; pedilos y te los
dejamos configurados.
Probar credenciales hace el recorrido completo, no un ping: se conecta al IMAP, inicia sesión, abre el buzón y cuenta los mensajes; después abre el SMTP, negocia el cifrado y se autentica. Si sale todo, contesta algo como «Buzón accesible (312 mensajes) y envío autenticado». Si falla, te muestra el error tal como lo devolvió el servidor de correo, sin traducirlo a un «no se pudo conectar» que no te sirve para nada.
COMPOSE_PROFILES=email make up.Es el canal que más vende en Paraguay y el que más trabajo cuesta conectar, y las dos cosas son por el mismo motivo: es de Meta. Karai usa la Cloud API oficial, que es la única forma legítima de que un sistema conteste WhatsApp. Lo demás son atajos que terminan con el número bloqueado.
1. El número no puede estar en uso en la app de WhatsApp. Un número que está en la aplicación común, o en la de WhatsApp Business del celular, no se puede dar de alta en la Cloud API. Hay que sacarlo de ahí primero —y perdés el historial de ese teléfono— o, lo que hace casi todo el mundo, usar un número nuevo dedicado al agente.
2. A partir del 1 de octubre de 2026, Meta cobra cada respuesta. Ese costo es de Meta y va aparte de tu plan de Karai: nosotros no lo cobramos ni lo podemos bajar. Es la razón por la que vale la pena tener también el chat en tu sitio, que no cuesta por mensaje.
Nada de esto se hace desde Karai: son pantallas de Meta. Es donde se cae la mitad de la gente, y no porque sea difícil sino porque son cinco pantallas ajenas seguidas.
/admin → Canales → WhatsApp y completá
los campos de la tabla de abajo.https://tu-stack/whatsapp/webhook
messages.
Sin la suscripción, el webhook queda verificado y mudo:
no llega un solo mensaje. Es una falla silenciosa y desconcertante.
| Campo del panel | De dónde sale | Obligatorio |
|---|---|---|
| Phone number ID | Del panel de WhatsApp de tu app en Meta, al lado del número. No es el teléfono. | Sí |
| Versión de API | Viene puesto en v25.0. No lo toques salvo que te lo pidamos. | Ya viene |
| Access token | El token permanente del usuario del sistema. | Sí |
| App secret | Configuración → Básica de la app de Meta. | Sí |
| Verify token | Lo elegís vos. Tiene que ser idéntico acá y en el webhook de Meta. | Sí |
| Plantilla de reenganche | El nombre de una plantilla ya aprobada por Meta, para escribirle a alguien pasadas las 24 h. Ver más abajo. | No |
| URL del webhook | Sólo lectura: el panel la arma y vos la copiás a Meta. | — |
/console, está todo conectado.
Es una regla de Meta, no de Karai, y conviene entenderla porque explica comportamientos que si no parecen fallas.
Mientras hayan pasado menos de 24 horas desde el último mensaje del cliente, se puede responder libremente. Cada mensaje nuevo que él manda reabre la ventana, así que en una conversación en curso el tema no aparece nunca. Pasadas las 24 horas, Meta ya no deja mandar texto libre: sólo plantillas aprobadas por ellos de antemano.
Karai hace dos cosas distintas según lo que hayas configurado. Si cargaste una plantilla de reenganche, la usa para reabrir la conversación. Si no, pasa la conversación a la bandeja con el texto que quería mandar, para que una persona decida qué hacer. Lo que no hace nunca es dar por enviado algo que Meta rechazó.
messages. Verificar
el webhook y suscribirse a los eventos son dos pasos distintos en la misma
pantalla, y el segundo se olvida.Todo lo de arriba existe porque hoy es la única manera. Ya está construido el alta embebida de Meta: un botón «Conectar WhatsApp» en el panel que abre una ventana de Facebook donde elegís tu cuenta de WhatsApp Business y tu número, y al volver deja todo configurado —el token, el webhook, la suscripción a los eventos y el registro del número— sin que copies un solo dato a mano.
Para poder ofrecerlo, Meta tiene que aprobar nuestra cuenta como Tech Provider. Es un trámite de ellos y no depende de nosotros, así que no prometemos fecha. El día que se apruebe, el botón aparece en el panel y el formulario manual queda para el que prefiera usar su propia app de Meta —que es lo habitual cuando Karai está instalado en el servidor de la empresa.
Los mensajes que llegan a tu página de Facebook. Comparte la app de Meta y las credenciales con Instagram: se cargan una sola vez y valen para los dos. Lo único distinto entre ambos es a qué cuenta apuntan.
/admin → Canales → Messenger e Instagram.https://tu-stack/meta/messenger/webhook
El campo muestra las dos, la de Messenger y la de
Instagram, una debajo de la otra. Cada una va en su producto.
messages, que es el que
trae lo que escribe el cliente.| Campo del panel | De dónde sale | Compartido con Instagram |
|---|---|---|
| Page ID (Messenger) | El identificador de tu página de Facebook. | No: Instagram tiene el suyo. |
| Access token de la página | Generado desde el producto Messenger de tu app. | Sí |
| App secret | Configuración → Básica de la app de Meta. | Sí |
| Verify token | Lo elegís vos. | Sí |
| URLs de webhook | Sólo lectura: las dos, para copiar a Meta. | — |
Messenger e Instagram se guardan por separado —«Guardar Messenger» y «Guardar Instagram»— porque son dos canales distintos con dos cuentas distintas. Pero los tres secretos son los de la misma app de Meta: se cargan una vez y el panel los aplica a los dos. Si vas a conectar los dos, cargá los secretos, guardá uno y guardá el otro.
Probar le pregunta a Meta por la página con las credenciales que cargaste y te devuelve el nombre que Meta reporta — «Conectado a «Ferretería del Este»». Ver el nombre correcto es la confirmación de que el Page ID y el token van juntos y son los tuyos. Si falla, aparece el motivo textual de Meta.
Messenger tiene tres tramos, y es una mejora respecto de WhatsApp:
La consecuencia práctica es directa: acá la bandeja de operador vale más que en WhatsApp. Un mensaje que entró anteayer se puede contestar, pero lo tiene que escribir una persona.
Todo lo de arriba es la forma manual, que es la que corresponde cuando Karai está instalado en el servidor de tu empresa y usás tu propia app de Meta. En la versión en la nube hay un botón «Conectar mi página»: se abre una ventana de Facebook, elegís la página de tu empresa, y al volver quedan configurados Messenger e Instagram de una sola vez —el token, el app secret, el webhook y la suscripción a los eventos— sin que copies un solo dato.
Si tu página tiene una cuenta profesional de Instagram vinculada, los dos canales quedan andando juntos. Si no la tiene, o si en la ventana no aceptaste los permisos de Instagram, Messenger queda funcionando igual y el panel te dice exactamente qué faltó y por qué.
A diferencia de WhatsApp, acá no hace falta que Meta nos apruebe como Tech Provider —ese programa es sólo de WhatsApp—. Lo que sí hace falta es que Meta apruebe los permisos de mensajería de nuestra app, una sola vez y para todos los clientes.
Los mensajes directos de tu cuenta de Instagram. Usa exactamente la misma app de Meta, el mismo token, el mismo app secret y el mismo verify token que Messenger: si ya conectaste Messenger, acá te falta un solo dato.
/admin → Canales → Messenger e Instagram, completá
«Page ID (Instagram)» y apretá Guardar Instagram.
Los otros tres campos —token, app secret y verify token—
son los mismos de Messenger y ya están cargados. Si conectás sólo Instagram,
cargalos igual.
https://tu-stack/meta/instagram/webhook, la segunda línea del
campo de sólo lectura del panel— con el mismo verify token, y suscribite a
los mensajes.
| Campo del panel | Qué va |
|---|---|
| Page ID (Instagram) | El identificador de tu cuenta profesional de Instagram, tal como lo da Meta. Es lo único propio de este canal. |
| Access token de la página | El mismo de Messenger. |
| App secret | El mismo de Messenger. |
| Verify token | El mismo de Messenger. |
Probar hace lo mismo que en Messenger: le pregunta a Meta por la cuenta y te devuelve el nombre o el usuario que Meta reporta, «Conectado a «tunegocio»». Si ves el nombre de tu cuenta, el identificador y el token son los correctos.
Por el chat de tu sitio. Se instala hoy, no depende de la aprobación de nadie y no te cobra por mensaje. Con eso andando ya tenés el agente contestando y podés ver cómo trabaja mientras arrancan los trámites de Meta, que son los que llevan días.
Después el correo, que son quince minutos y tampoco depende de terceros. Y en paralelo, arrancá la verificación del negocio en Meta: es lo primero que conviene poner en marcha porque es lo último que se destraba.