Documentación API REST

Integra WhatsApp en tu software, CRM o tienda en línea usando ZapWhat. API rápida, estable y diseñada para escalar.

Base URL: https://zapwhat.com/api

Endpoints disponibles

Enviar mensajes — texto, imágenes, videos, audios, documentos, stickers, contactos
Enviar ubicaciones — coordenadas GPS con dirección
Listar instancias — consulta el estado de tus conexiones
Webhooks — recibe mensajes entrantes en tiempo real
Autenticación segura mediante API Token

Autenticación

Todas las llamadas requieren tu API Token en el header Authorization usando el formato Bearer.

Tu token único se genera automáticamente al crear tu cuenta. Puedes verlo en la sección API Docs de tu Panel de Control.

Authorization: Bearer TU_API_TOKEN_AQUI

Importante: Mantén tu token en secreto. No lo compartas en repositorios públicos o código del lado del cliente.

Códigos de Error

La API utiliza códigos de estado HTTP estándar para indicar el resultado de cada solicitud.

Código	Significado	Descripción
`200`	OK	Solicitud exitosa.
`400`	Bad Request	Faltan parámetros requeridos o el JSON es inválido.
`401`	Unauthorized	Token de API faltante o inválido.
`403`	Forbidden	No tienes permiso para usar esta instancia.
`404`	Not Found	Instancia o recurso no encontrado.
`500`	Internal Server Error	Error interno del servidor. Contacta a soporte si persiste.

{
  "error": "Descripción del error"
}

Listar Instancias

Obtén la lista de tus instancias de WhatsApp conectadas y su estado en tiempo real.

GET https://zapwhat.com/api/instances

Headers

Header	Valor
`Authorization`	`Bearer TU_API_TOKEN`

Respuesta

[
  {
    "id": 1,
    "session_id": "zapwhat_u1_User_MyPhone",
    "phone_number": "+5215512345678",
    "status": "connected",
    "created_at": "2026-06-01 12:00:00"
  }
]

Enviar Mensaje de Texto

Envía un mensaje de texto simple a cualquier número de WhatsApp.

POST https://zapwhat.com/api/send

Parámetro	Tipo	Requerido	Descripción
`instance_id`	String	Sí	ID de tu sesión de WhatsApp (lo encuentras en tu panel).
`to`	String	Sí	Número del receptor con código de país (ej: 5215512345678). Sin + ni espacios.
`message`	String	Sí	Contenido del mensaje. Soporta emojis y saltos de línea.

Ejemplos de Integración

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://zapwhat.com/api/send',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    "instance_id" => "TU_INSTANCE_ID",
    "to" => "5215512345678",
    "message" => "¡Hola desde ZapWhat API!"
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer TU_API_TOKEN_AQUI',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
echo $response;

const axios = require('axios');

const data = {
  instance_id: "TU_INSTANCE_ID",
  to: "5215512345678",
  message: "¡Hola desde ZapWhat API!"
};

axios.post('https://zapwhat.com/api/send', data, {
  headers: {
    'Authorization': 'Bearer TU_API_TOKEN_AQUI',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

import requests, json

url = "https://zapwhat.com/api/send"
payload = json.dumps({
  "instance_id": "TU_INSTANCE_ID",
  "to": "5215512345678",
  "message": "¡Hola desde ZapWhat API!"
})
headers = {
  'Authorization': 'Bearer TU_API_TOKEN_AQUI',
  'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)

curl --location 'https://zapwhat.com/api/send' \
--header 'Authorization: Bearer TU_API_TOKEN_AQUI' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "to": "5215512345678",
    "message": "¡Hola desde ZapWhat API!"
}'

Enviar Archivo / Media

Envía imágenes, videos, audios, documentos, stickers o tarjetas de contacto a cualquier número de WhatsApp. Todos los tipos de media se envían al mismo endpoint.

POST https://zapwhat.com/api/send-media

Parámetro	Tipo	Requerido	Descripción
`instance_id`	String	Sí	ID de tu sesión de WhatsApp.
`to`	String	Sí	Número del receptor con código de país.
`type`	String	Sí	Tipo de archivo: `image`, `video`, `audio`, `document`, `sticker`, `contact`
`url`	String	Sí*	URL pública del archivo. No necesario si `type=contact`.
`caption`	String	No	Texto descriptivo (aplica para image y video).
`filename`	String	No	Nombre del archivo a mostrar (útil para `document`).
`contact_name`	String	Sí*	Nombre del contacto (requerido si `type=contact`).
`contact_phone`	String	Sí*	Teléfono del contacto (requerido si `type=contact`).

Los audios se envían como nota de voz. Los stickers deben estar en formato WebP.

Ejemplos de Integración

// Ejemplo: enviar imagen con caption
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://zapwhat.com/api/send-media',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    "instance_id" => "TU_INSTANCE_ID",
    "to" => "5215512345678",
    "type" => "image",
    "url" => "https://ejemplo.com/imagen.jpg",
    "caption" => "Mira esta imagen!"
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer TU_API_TOKEN',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);

// Ejemplo: enviar sticker
$payload = json_encode(array(
  "instance_id" => "TU_INSTANCE_ID",
  "to" => "5215512345678",
  "type" => "sticker",
  "url" => "https://ejemplo.com/sticker.webp"
));

// Ejemplo: enviar contacto
$payload = json_encode(array(
  "instance_id" => "TU_INSTANCE_ID",
  "to" => "5215512345678",
  "type" => "contact",
  "contact_name" => "Juan Pérez",
  "contact_phone" => "5215598765432"
));

const axios = require('axios');

// Enviar imagen con caption
const data = {
  instance_id: "TU_INSTANCE_ID",
  to: "5215512345678",
  type: "image",
  url: "https://ejemplo.com/imagen.jpg",
  caption: "Mira esta imagen!"
};

axios.post('https://zapwhat.com/api/send-media', data, {
  headers: {
    'Authorization': 'Bearer TU_API_TOKEN',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

// Enviar documento
const docData = {
  instance_id: "TU_INSTANCE_ID",
  to: "5215512345678",
  type: "document",
  url: "https://ejemplo.com/reporte.pdf",
  filename: "Reporte_2026.pdf"
};
axios.post('https://zapwhat.com/api/send-media', docData, {
  headers: {
    'Authorization': 'Bearer TU_API_TOKEN',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

// Enviar contacto
const contactData = {
  instance_id: "TU_INSTANCE_ID",
  to: "5215512345678",
  type: "contact",
  contact_name: "Juan Pérez",
  contact_phone: "5215598765432"
};
axios.post('https://zapwhat.com/api/send-media', contactData, {
  headers: {
    'Authorization': 'Bearer TU_API_TOKEN',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

import requests, json

url = "https://zapwhat.com/api/send-media"
headers = {
  'Authorization': 'Bearer TU_API_TOKEN',
  'Content-Type': 'application/json'
}

# Enviar imagen con caption
payload = json.dumps({
  "instance_id": "TU_INSTANCE_ID",
  "to": "5215512345678",
  "type": "image",
  "url": "https://ejemplo.com/imagen.jpg",
  "caption": "Mira esta imagen!"
})
response = requests.post(url, headers=headers, data=payload)
print(response.text)

# Enviar sticker
payload = json.dumps({
  "instance_id": "TU_INSTANCE_ID",
  "to": "5215512345678",
  "type": "sticker",
  "url": "https://ejemplo.com/sticker.webp"
})
response = requests.post(url, headers=headers, data=payload)
print(response.text)

# Enviar contacto
payload = json.dumps({
  "instance_id": "TU_INSTANCE_ID",
  "to": "5215512345678",
  "type": "contact",
  "contact_name": "Juan Pérez",
  "contact_phone": "5215598765432"
})
response = requests.post(url, headers=headers, data=payload)
print(response.text)

# Enviar imagen
curl --location 'https://zapwhat.com/api/send-media' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "to": "5215512345678",
    "type": "image",
    "url": "https://ejemplo.com/imagen.jpg",
    "caption": "Mira esta imagen!"
}'

# Enviar documento
curl --location 'https://zapwhat.com/api/send-media' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "to": "5215512345678",
    "type": "document",
    "url": "https://ejemplo.com/reporte.pdf",
    "filename": "Reporte_2026.pdf"
}'

Enviar Ubicación

Envía coordenadas GPS con nombre y dirección opcional.

POST https://zapwhat.com/api/send-location

Parámetro	Tipo	Requerido	Descripción
`instance_id`	String	Sí	ID de tu sesión de WhatsApp.
`to`	String	Sí	Número del receptor con código de país.
`lat`	Float	Sí	Latitud de la ubicación. Ej: `19.4326`
`lng`	Float	Sí	Longitud de la ubicación. Ej: `-99.1332`
`address`	String	No	Dirección física en formato texto.
`name`	String	No	Nombre del lugar o establecimiento.

Ejemplos de Integración

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://zapwhat.com/api/send-location',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode(array(
    "instance_id" => "TU_INSTANCE_ID",
    "to" => "5215512345678",
    "lat" => 19.4326,
    "lng" => -99.1332,
    "address" => "Zócalo de la CDMX",
    "name" => "Centro Histórico"
  )),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer TU_API_TOKEN',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
echo $response;

const axios = require('axios');

const data = {
  instance_id: "TU_INSTANCE_ID",
  to: "5215512345678",
  lat: 19.4326,
  lng: -99.1332,
  address: "Zócalo de la CDMX",
  name: "Centro Histórico"
};

axios.post('https://zapwhat.com/api/send-location', data, {
  headers: {
    'Authorization': 'Bearer TU_API_TOKEN',
    'Content-Type': 'application/json'
  }
}).then(res => console.log(res.data));

import requests, json

url = "https://zapwhat.com/api/send-location"
payload = json.dumps({
  "instance_id": "TU_INSTANCE_ID",
  "to": "5215512345678",
  "lat": 19.4326,
  "lng": -99.1332,
  "address": "Zócalo de la CDMX",
  "name": "Centro Histórico"
})
headers = {
  'Authorization': 'Bearer TU_API_TOKEN',
  'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)

curl --location 'https://zapwhat.com/api/send-location' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "to": "5215512345678",
    "lat": 19.4326,
    "lng": -99.1332,
    "address": "Zócalo de la CDMX",
    "name": "Centro Histórico"
}'

Verificar si un Número está en WhatsApp

Verifica si un número de teléfono está registrado en WhatsApp. Requiere una instancia conectada.

POST https://zapwhat.com/api/check-number

Parámetro	Tipo	Requerido	Descripción
`instance_id`	String	Sí	ID de tu sesión de WhatsApp conectada.
`phone`	String	Sí	Número a verificar (ej: 5215512345678).

curl --location 'https://zapwhat.com/api/check-number' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "phone": "5215512345678"
}'

Listar Contactos

Obtén todos los contactos sincronizados con tu sesión de WhatsApp.

POST https://zapwhat.com/api/contacts

curl --location 'https://zapwhat.com/api/contacts' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "list"
}'

Información de un Contacto

POST https://zapwhat.com/api/contacts

curl --location 'https://zapwhat.com/api/contacts' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "info",
    "phone": "5215512345678"
}'

Bloquear / Desbloquear Contacto

POST https://zapwhat.com/api/contacts

# Bloquear
curl --location 'https://zapwhat.com/api/contacts' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "block",
    "phone": "5215512345678"
}'

# Desbloquear
curl --location 'https://zapwhat.com/api/contacts' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "unblock",
    "phone": "5215512345678"
}'

Crear o Actualizar Contacto

Guarda o actualiza un contacto en la agenda de tu sesión de WhatsApp.

POST https://zapwhat.com/api/contacts

curl --location 'https://zapwhat.com/api/contacts' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "sync",
    "phone": "5215512345678",
    "name": "Juan Pérez"
}'

Listar Grupos

Obtén todos los grupos donde está presente tu sesión de WhatsApp.

POST https://zapwhat.com/api/groups

curl --location 'https://zapwhat.com/api/groups' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "list"
}'

Crear Grupo

Crea un nuevo grupo de WhatsApp con los participantes indicados.

POST https://zapwhat.com/api/groups

Parámetro	Tipo	Requerido	Descripción
`instance_id`	String	Sí	ID de tu sesión.
`action`	String	Sí	`create`
`name`	String	Sí	Nombre del grupo.
`participants`	Array	Sí	Array de números a agregar (ej: ["5215512345678"]).

curl --location 'https://zapwhat.com/api/groups' \
--header 'Authorization: Bearer TU_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "instance_id": "TU_INSTANCE_ID",
    "action": "create",
    "name": "Mi Grupo",
    "participants": ["5215512345678", "5215598765432"]
}'

Gestionar Grupo

Adminstra participantes, configuración, y más desde un solo endpoint.

POST https://zapwhat.com/api/groups

Acción	Descripción	Parámetros adicionales
`metadata`	Obtener info del grupo	`group_id`
`participants`	Listar participantes	`group_id`
`add-participants`	Agregar miembros	`group_id`, `participants` [array]
`remove-participants`	Eliminar miembros	`group_id`, `participants` [array]
`settings`	Cambiar nombre/descripción	`group_id`, `subject`, `description`
`invite-link`	Obtener link de invitación	`group_id`
`leave`	Salir del grupo	`group_id`

# Obtener metadata curl --location 'https://zapwhat.com/api/groups' \ --header 'Authorization: Bearer TU_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "instance_id": "TU_INSTANCE_ID", "action": "metadata", "group_id": "[email protected]" }' # Agregar participantes curl --location 'https://zapwhat.com/api/groups' \ --header 'Authorization: Bearer TU_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "instance_id": "TU_INSTANCE_ID", "action": "add-participants", "group_id": "[email protected]", "participants": ["5215512345678"] }'

El group_id es el JID del grupo (ej: [email protected]). Puedes obtenerlo con la acción list.

Recibir Mensajes (Webhooks)

Para recibir mensajes entrantes, configura una URL de Webhook desde la sección Instancias de tu Panel de Control. Cada vez que tu número reciba un mensaje, ZapWhat enviará una petición POST a tu servidor con los detalles.

Puedes configurar una URL de webhook diferente para cada instancia desde el panel.

Estructura del JSON Recibido

{ "event": "message.incoming", "sessionId": "TU_SESSION_ID", "text": "Hola, necesito información", "from": "5215512345678", "data": { "messages": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "MSG_ID_12345" }, "message": { "conversation": "Hola, necesito información" }, "messageTimestamp": 1781289344 } } }

Ejemplo de Implementación en PHP

// webhook.php - Recibir notificaciones de ZapWhat

// 1. Leer los datos del POST
$input = file_get_contents('php://input');
$data = json_decode($input, true);

if (!$data) {
    http_response_code(400);
    exit('JSON inválido');
}

// 2. Extraer los datos principales
$messageText = $data['text'] ?? '';
$senderNumber = $data['from'] ?? '';

// 3. Procesar o registrar
if (!empty($senderNumber) && !empty($messageText)) {
    $log = date('Y-m-d H:i:s') . " | Remitente: $senderNumber | Mensaje: $messageText" . PHP_EOL;
    file_put_contents('webhooks.log', $log, FILE_APPEND);
}

// 4. Responder con éxito
http_response_code(200);
echo json_encode(['status' => 'processed']);

Buenas Prácticas

1. Anti-Spam y Límites de WhatsApp

La API no impone un límite estricto de mensajes por segundo, pero tu número de WhatsApp sigue sujeto a las políticas anti-spam de Meta. Para evitar bloqueos:

Introduce pausas aleatorias (3-8 segundos) entre envíos masivos
Varia el contenido de los mensajes (no uses plantillas idénticas)
Evita enviar mensajes a usuarios que no te tengan en sus contactos
Monitorea la tasa de bloqueos y ajusta la velocidad

2. Manejo de Errores

Implementa reintentos con backoff exponencial (espera 1s, 2s, 4s...)
Registra todos los errores y respuestas de la API para depuración

3. Seguridad

Nunca expongas tu API Token en código del lado del cliente
Usa variables de entorno para almacenar tokens

4. Proxies Integrados

ZapWhat incluye una red global de proxies rotativos integrados en todas tus instancias de forma automática para máxima estabilidad. No necesitas configurar ni comprar proxies adicionales.

Protección automática contra bloqueos mediante IPs dinámicas
Asignación inteligente de ubicaciones para coincidir con tu región
Alta disponibilidad garantizada sin configuraciones extra