Documentación / v1
Conecta tu integración.
La autenticación de personas y la transferencia de archivos usan HTTP. Los comandos, consultas y eventos de mensajes usan WebSocket. Los clientes Go y web del repositorio también permiten abrir las claves y descifrar el contenido.
1. Prepara los accesos
- Entra en la consola con tu invitación y crea tu cuenta. Guarda el código de recuperación.
- Vincula un número de prueba. Concede la clave del historial solo a las cuentas que deban leerlo.
- Para una integración con acceso de lectura, genera un par de claves con
wsctl service-key, registra la clave pública mediante una invitación de servicio y concede acceso al número. - Crea un token con el alcance necesario. Selecciona la cuenta de servicio de la integración y configura sus permisos por número.
El token se muestra una sola vez. Guárdalo en el almacén de secretos de tu sistema. No incluyas tokens en URL, repositorios ni código público del navegador.
2. Abre el WebSocket
wss://api.wappie.thehappie.co/v1/wsEl primer frame es hello. Usa api_key para integraciones o session para una sesión de persona. El servidor responde welcome antes de los demás comandos.
{"t":"hello","r":"connect","p":{"api_key":"SEU_TOKEN"}}
{"t":"devices.list","r":"numbers","p":{}}
{"t":"subscribe","r":"events","p":{"live_only":true}}t identifica el comando; r correlaciona la respuesta; p contiene los parámetros. Usa un identificador distinto por solicitud. Los eventos espontáneos no necesitan r.
Para recuperar eventos, usa since_seq con la última secuencia procesada. Gestiona los frames replay.begin, replay.end y lag; si hay retraso o desconexión, continúa desde el último evento confirmado por tu aplicación.
| Operación | Comandos | Requisito |
|---|---|---|
| Descubrir números | devices.list, device.info | Acceso al número |
| Consultar mensajes | chats.list, chat.page, message.get, message.history | Permiso de lectura y clave concedida |
| Seguir eventos | subscribe | Lectura de los números suscritos |
| Enviar | message.send, message.send.media, message.react, message.poll.create, message.send.location, message.event.create, chat.start | Envío |
| Gestionar dispositivo | device.start, device.stop, device.rename, device.mode, history.backfill, group.create, group.participants.update, group.leave | Gestión |
| Gestionar tokens | apikeys.list, apikeys.create, apikeys.revoke | Propietario o administrador |
Referencia completa de tipos, parámetros y respuestas (TypeScript) · Contrato Go
chat.start · group.create · group.participants.update · group.leave · message.poll.create →
message.send.media · forwarded · forwarding_score →
message.react · Unicode emoji →
Errores y reconexión
{"t":"error","r":"request-id","p":{"code":"not_authorized","message":"..."}}Una revocación, caducidad o cambio de acceso puede cerrar la conexión con el código 1008. Actualiza la autenticación y los permisos antes de reconectar. Usa esperas progresivas entre intentos y no repitas automáticamente envíos de resultado desconocido.
3. Usa los endpoints HTTP
Base: https://api.wappie.thehappie.co. Las operaciones autenticadas reciben Authorization: Bearer TOKEN. Las rutas de gestión requieren una sesión de persona; una clave de API no administra usuarios.
| Método | Ruta | Finalidad |
|---|---|---|
| POST | /v1/auth/challenge, /v1/auth/login | Obtener parámetros de derivación e iniciar sesión |
| POST | /v1/auth/signup | Crear una cuenta con invitación y claves generadas en el cliente |
| GET | /v1/auth/me | Cuenta y concesiones cifradas |
| GET | /v1/auth/workspaces | Espacios de trabajo de la identidad |
| POST | /v1/auth/workspaces/session | Nueva sesión en el espacio indicado por tenant_id |
| POST | /v1/auth/workspaces/accept-invite | Aceptar un invite con una cuenta existente |
| GET / PUT | /v1/auth/workspaces/members / members/{userID} | Listar y cambiar rol y estado |
| POST | /v1/auth/workspaces/invites | Invitación con email y role |
| GET / PUT | /v1/auth/workspaces/devices/{deviceID}/permissions | Permisos de lectura, envío y gestión |
| GET | /v1/auth/workspaces/capacity | Plazas configuradas y ocupadas |
| GET | /v1/media/{uid} | Bytes cifrados de un adjunto autorizado |
| POST | /v1/upload?device=UUID&type=image | Preparar un adjunto para enviar; consulta el contrato de carga |
Contratos de gestión, ejemplos y códigos HTTP · Cliente de autenticación y cifrado · Contrato de carga
4. Entiende los permisos
Una identidad puede participar en varios espacios de trabajo. Los roles, números, permisos y tokens pertenecen al espacio. Los propietarios y administradores gestionan dispositivos; ese rol por sí solo no da acceso a las conversaciones.
La lectura requiere permiso y una clave concedida. Se puede autorizar el envío sin lectura. Los alcances de token read, send y full son límites acumulativos; cuando un token actúa como una cuenta de servicio, los permisos independientes de esa cuenta restringen cada número.
Los tokens heredados sin cuenta de servicio pueden acceder al contenido cifrado del espacio según su alcance. Es preferible usar cuentas de servicio para restringir integraciones por número. Eliminar una concesión impide nuevos accesos, pero no borra claves ni mensajes ya descargados.
Alojamiento propio
El repositorio incluye servidor Go, CLI, cliente Vue e instrucciones para PostgreSQL 18. La administración básica funciona sin el módulo comercial. El alojamiento oficial usa cuatro direcciones; una instalación propia puede servir el cliente y la API desde el mismo origen.
Abrir guía de instalación →API v1 · piloto