Autenticación

Todas las solicitudes a la API de watsi requieren un token Bearer. Esta guía explica cómo crear claves de API, autenticar solicitudes y mantener seguras sus credenciales.

Cómo crear una clave de API

Inicie sesión en el panel de watsi
Vaya a Settings → API Keys
Haga clic en Generate new key
Copie la clave de inmediato — solo se muestra una vez

Importante: Almacene su clave de API en un lugar seguro, como una variable de entorno o un gestor de secretos. Nunca incluya claves de API en el control de versiones.

Cómo usar su clave de API

Incluya la clave de API en el encabezado Authorization de cada solicitud utilizando el esquema Bearer:

curl https://api.watsi.ai/api/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

Si la clave falta o no es válida, la API devuelve una respuesta 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

Alcances de las claves de API

Cada clave de API está limitada a un único espacio de trabajo. La clave hereda los permisos del usuario que la creó y puede acceder a todos los recursos dentro de ese espacio de trabajo.

Alcance	Acceso
`conversations`	Listar, leer y administrar conversaciones
`customers`	Listar, leer, crear y actualizar contactos
`messages`	Enviar mensajes dentro de conversaciones abiertas
`templates`	Listar y administrar plantillas de mensajes de WhatsApp
`tags`	Crear, listar y asignar etiquetas a contactos
`users`	Listar a los miembros del equipo del espacio de trabajo

Autenticación de MCP

La misma clave de API funciona para las conexiones de MCP (Model Context Protocol). Agréguela a la configuración de su cliente de MCP:

{
  "mcpServers": {
    "watsi": {
      "url": "https://mcp.watsi.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

El servidor de MCP ahora refleja la superficie de acciones de la API pública publicada para contactos, conversaciones, citas, incrustaciones de calendario, campañas, conocimiento y analítica. Esto permite que los clientes de IA utilicen la misma clave del espacio de trabajo tanto para flujos de lectura como de escritura, en lugar de depender de una ruta de integración privada aparte.

Contactos: herramientas para listar, buscar, obtener, crear, actualizar, eliminar, gestionar canales e importar por lotes
Conversaciones: herramientas para actualizar, cerrar/reabrir, CRUD de notas y resúmenes, además de las funciones de lectura/búsqueda existentes
Programación: citas, tipos de cita, espacios de calendario, metadatos de incrustación del widget y rotación de tokens de iCal
Campañas / conocimiento / analítica: herramientas de ejecución, ciclo de vida y exportación alineadas con los endpoints REST públicos

Cuando una herramienta espera un cuerpo de solicitud, pase el mismo payload JSON que enviaría al endpoint REST correspondiente. Las cargas de archivos se admiten mediante contenido en base64 junto con los campos de nombre de archivo y tipo de contenido.

Buenas prácticas de seguridad

Rote las claves con regularidad — genere una nueva clave y revoque la anterior de forma periódica
Use variables de entorno — nunca codifique las claves directamente en el código fuente de la aplicación
Restrinja el uso al lado del servidor — nunca exponga las claves de API en código del lado del cliente ni en solicitudes del navegador
Supervise el uso — revise la actividad de las claves de API en el panel y revoque las claves que ya no necesite
Use solo HTTPS — todas las solicitudes a la API deben realizarse por HTTPS. Las solicitudes HTTP sin cifrar son rechazadas

Límites de tasa

La API permite 100 solicitudes por minuto por clave de API. Cuando supera el límite, la API devuelve 429 Too Many Requests con un encabezado Retry-After que indica cuántos segundos debe esperar.

Consulte la guía de manejo de errores para conocer estrategias de reintento.