Documentación de WhtsAPI
WhtsAPI es creada por Carras Technologies LLC. Esta guía explica cómo conectar WhatsApp, crear credenciales y usar la API aunque no tengas experiencia técnica.
Sesión de WhatsApp
Es el vínculo entre tu workspace y un número de WhatsApp. Se conecta como dispositivo vinculado usando QR.
API key
Es una credencial privada. Nunca la publiques en páginas web, apps móviles o repositorios públicos.
Mensaje
Es una solicitud para enviar texto a un número. El sistema lo encola y lo procesa con reintentos.
Webhook
Es una notificación automática hacia tu sistema cuando ocurre un evento importante.
Primeros pasos
Haz esto en orden para dejar el gateway listo.
1. Crea o entra a tu cuenta
Tu cuenta pertenece a un workspace. El workspace es el espacio donde vivirán tu número, API keys y webhooks.
2. Conecta WhatsApp
Ve a Conectar WhatsApp, presiona Conectar o reconectar y escanea el QR desde WhatsApp en tu teléfono.
3. Crea una API key
La API key es la contraseña técnica que usará tu web, CRM o backend para llamar al gateway.
4. Prueba un mensaje
Envía un mensaje simple a tu propio número antes de conectar sistemas reales de clientes.
5. Activa webhooks
Si tu sistema necesita saber cuándo algo fue enviado o falló, configura una URL de webhook.
Cómo conectar WhatsApp
El número se conecta desde el teléfono dueño de la cuenta de WhatsApp.
Abre WhatsApp en el teléfono, entra a Dispositivos vinculados, toca Vincular dispositivo y escanea el QR que aparece en el dashboard.
Cuando el estado diga connected, tu sistema ya puede enviar mensajes por API.
Si cambias de teléfono, eliminas el dispositivo vinculado o cierras sesión, vuelve a conectar con un QR nuevo.
Cómo capturar mensajes de grupos
Después de conectar WhatsApp puedes elegir exactamente de qué grupos se guardarán mensajes y archivos.
Primero conecta WhatsApp y espera a que el estado diga connected.
En Conectar WhatsApp, presiona Sincronizar grupos. La app traerá los grupos disponibles del número conectado.
Marca solo los grupos que quieres monitorear. Desde ese momento se guardan mensajes de texto y metadatos de imágenes, audios, videos y documentos entrantes en la sección Messages.
Autenticación de la API
Todas las llamadas técnicas usan el header Authorization con tu API key.
Header requerido
Authorization: Bearer WG_API_KEY Content-Type: application/json
Endpoints principales
Cambia la URL base por el dominio donde tengas instalada la aplicación.
POSTEnviar mensaje
/api/v1/messages/send
Body
{
"to": "+13055551234",
"message": "Tu pedido fue confirmado.",
"type": "notification"
}Respuesta esperada
{
"success": true,
"data": {
"messageId": "msg_..."
}
}GETConsultar mensaje
/api/v1/messages/{id}
Body
No requiere body.
Respuesta esperada
{
"success": true,
"data": {
"id": "msg_...",
"status": "sent"
}
}POSTEnviar OTP
/api/v1/otp/send
Body
{
"to": "+13055551234",
"purpose": "login"
}Respuesta esperada
{
"success": true,
"data": {
"otpId": "otp_..."
}
}POSTVerificar OTP
/api/v1/otp/verify
Body
{
"to": "+13055551234",
"code": "123456",
"purpose": "login"
}Respuesta esperada
{
"success": true,
"data": {
"valid": true
}
}GETEstado de WhatsApp
/api/v1/sessions/status
Body
No requiere body.
Respuesta esperada
{
"success": true,
"data": {
"status": "connected",
"phoneNumber": "13055551234"
}
}Ejemplo completo con curl
Ideal para que tu equipo técnico pruebe desde terminal.
Enviar un mensaje
curl -X POST https://tu-dominio.com/api/v1/messages/send \
-H "Authorization: Bearer WG_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+13055551234",
"message": "Hola, tu cita fue confirmada.",
"type": "notification"
}'Webhooks
Usa webhooks si quieres que tu sistema reciba avisos automáticos sin estar preguntando cada minuto.
Eventos disponibles
Firma de seguridad
Valida este header antes de confiar en un webhook recibido.
X-WG-Signature: sha256=<hmac> La firma se calcula con el secret del webhook. Si la firma no coincide, ignora la solicitud.
Errores comunes
Qué significan y qué debe revisar el cliente.
401 Unauthorized
La API key falta, está mal escrita o pertenece a otro workspace.
429 Too Many Requests
Se alcanzó un límite de uso. Espera o revisa el plan del workspace.
SESSION_DISCONNECTED
WhatsApp no está conectado. Vuelve a escanear el QR desde Conectar WhatsApp.
INVALID_PHONE_NUMBER
El número no tiene formato válido. Usa código de país, por ejemplo +1, +52 o +57.