Construye con la
WITHMIA API
Envía mensajes, gestiona conversaciones y conecta canales con una API REST predecible, bien documentada y con SDKs oficiales para tu lenguaje favorito.
Inicio rápido
Envía tu primer mensaje en 5 minutos
Referencia API
Documentación completa de endpoints
SDKs y librerías
Node.js, Python y cURL
import { Withmia } from '@withmia/sdk';
const client = new Withmia('sk_live_...');
const msg = await client.messages.send({
channel: 'whatsapp',
to: '+56912345678',
text: 'Tu cita fue confirmada ✅'
});
console.log(msg.id); // msg_7f3kQ9x...{ "id": "msg_7f3kQ9x", "status": "delivered", "channel": "whatsapp" }Inicio Rápido
Integra en 3 pasos
Desde API key hasta tu primer mensaje enviado en menos de 5 minutos.
Obtén tu API Key
Crea una cuenta y genera tu token de acceso desde el dashboard. Sandbox gratuito incluido.
Authorization: Bearer sk_live_...Instala el SDK
Instala la librería oficial para tu lenguaje con un solo comando.
npm install @withmia/sdkEnvía tu primer mensaje
Un POST request y tu mensaje se entrega por WhatsApp, Email o cualquier canal.
client.messages.send({ ... })Autenticación
Seguridad de nivel enterprise
Genera tu API Key
Desde el dashboard de WITHMIA, genera un token de acceso. Puedes crear múltiples keys con scopes específicos.
Incluye el token en cada request
Envía el header Authorization: Bearer sk_live_... en todas tus peticiones. Para testing, usa sk_test_... en el sandbox.
Scopes granulares
Asigna permisos por recurso: messages:write, conversations:read, contacts:*, webhooks:manage. Principio de mínimo privilegio.
Rotación segura
Rota tokens sin downtime. La API soporta dos tokens activos simultáneamente durante la migración.
// Tokens con scopes específicos
const client = new Withmia({
apiKey: "sk_live_...",
scopes: [
"messages:write",
"conversations:read",
"contacts:read"
]
});
// Headers enviados automáticamente:
// Authorization: Bearer sk_live_...
// X-Api-Version: 2026-02-01
// X-Idempotency-Key: auto-generatedReferencia API
Endpoints
Enviar mensaje a cualquier canal conectado
POST https://api.withmia.com/v1/messages
Authorization: Bearer sk_live_...
Content-Type: application/json{ "id": "msg_7f3kQ9x", "status": "queued", "channel": "whatsapp", "to": "+569...", "created_at": "2026-02-24T14:32:01Z" }Códigos de Error
Respuestas predecibles
{
"error": {
"type": "validation_error",
"code": "invalid_phone_number",
"message": "El número de teléfono no es válido",
"param": "to",
"doc_url": "https://docs.withmia.com/errors/invalid_phone"
}
}// Headers de respuesta
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708872000
Retry-After: 30Paginación y Filtros
Navega datos eficientemente
Cursor-based pagination
Todas las listas usan paginación por cursor, más eficiente y consistente que offset. El cursor es un token opaco que apunta al siguiente grupo de resultados.
Filtros avanzados
Filtra por cualquier campo: status, channel, tags, fecha, agente asignado. Combina múltiples filtros con operadores AND.
Búsqueda full-text
El parámetro q= busca en nombre, email, teléfono y campos personalizados. Soporta búsqueda parcial y normalización de caracteres.
Ordenamiento
Ordena resultados por cualquier campo con sort=campo:asc|desc. Por defecto: created_at:desc.
// Request con filtros y paginación
GET /v1/conversations
?status=open
&channel=whatsapp
&assigned_to=agent_5xK
&limit=20
&cursor=eyJpZCI6MTIzfQ==
&sort=updated_at:desc
// Response
{
"data": [...],
"meta": {
"has_more": true,
"next_cursor": "eyJpZCI6MTQzfQ==",
"total": 142
}
}Rate Limiting
Límites por plan
Cada request incluye headers informativos. Escala sin sorpresas.
Sandbox
100
req/minuto
Starter
1,000
req/minuto
Growth
5,000
req/minuto
Enterprise
Custom
req/minuto
Backoff inteligente: Los SDKs oficiales implementan retry automático con backoff exponencial. Si excedes el límite, esperan el tiempo indicado en Retry-After y reintentan.
Librerías Cliente
SDKs oficiales
import { Withmia } from '@withmia/sdk';
const client = new Withmia('sk_live_...');
const msg = await client.messages.send({
channel: 'whatsapp',
to: '+56912345678',
text: 'Tu cita fue confirmada ✅'
});
console.log(msg.id); // msg_7f3kQ9x...Webhooks
Eventos en tiempo real
{
"event": "message.received",
"timestamp": "2026-02-24T14:32:01Z",
"data": {
"id": "msg_8xK2p4q...",
"channel": "whatsapp",
"from": "+56912345678",
"text": "Hola, necesito agendar",
"conversation_id": "conv_3fR9..."
},
"signature": "sha256=a1b2c3d4..."
}API Playground
Prueba en vivo
Ejecuta requests directamente desde tu navegador. Sandbox mode — sin efectos reales.
Presiona "Send" para ejecutar el request
Capacidades
Diseñada para escalar
REST API
CRUD para mensajes, contactos, conversaciones, canales y webhooks. JSON responses.
Webhooks
Eventos push en tiempo real via HTTPS. Firma HMAC-SHA256 en cada payload.
OAuth 2.0
Tokens de acceso, refresh tokens y scopes granulares por recurso.
SDKs oficiales
Node.js, Python y cURL. Tipados, con retries automáticos y error handling.
Rate limiting
1,000 req/min por defecto. Headers informativos. Enterprise: límites custom.
TLS 1.3
Cifrado end-to-end. Webhook signatures verificables con tu secret key.
Paginación
Cursor-based pagination en todas las listas. Filtros avanzados por campo.
Idempotency
Idempotency keys para requests POST seguros. Zero duplicados garantizado.
Sandbox
Entorno de pruebas aislado con datos fake. Sin costo, sin tarjeta de crédito.
Arquitectura
Un solo endpoint, múltiples canales
WITHMIA abstrae la complejidad de cada proveedor. Tú hablas con una sola API.
Tu aplicación
REST / SDK / Webhook
WITHMIA API
Orquestador inteligente
Canales
6+ conectados
Casos de Uso
Integraciones reales
Ejemplos de código listos para copiar. Adapta, conecta y lanza.
E-commerce
Confirmaciones de pedido, tracking de envío y soporte post-venta automatizado por WhatsApp.
client.messages.send({
channel: "whatsapp",
to: order.phone,
template: "order_confirmed",
variables: {
name: order.customer,
order_id: order.id,
total: order.total
}
});Agendamiento
Envía recordatorios automáticos, permite confirmar o reagendar directamente por chat.
client.messages.send({
channel: "whatsapp",
to: appointment.phone,
template: "appointment_reminder",
variables: {
date: appointment.date,
doctor: appointment.professional,
link: appointment.reschedule_url
}
});Salud
Resultados de exámenes, recordatorio de medicamentos y seguimiento post-consulta.
// Webhook: conversation.created
app.post("/webhook", (req, res) => {
const { data } = req.body;
if (data.metadata.department === "lab") {
client.messages.send({
to: data.contact.phone,
text: "Sus resultados están listos 📋"
});
}
});Educación
Proceso de admisión automatizado, envío de documentos y seguimiento de matrículas.
// Automatizar respuesta a consultas
client.bots.configure({
trigger: "admission_inquiry",
actions: [
{ type: "send_template", template: "admission_info" },
{ type: "collect_data", fields: ["name", "grade", "email"] },
{ type: "create_contact", assign_to: "admissions" }
]
});Inmobiliaria
Califica leads automáticamente, agenda visitas y envía fichas de propiedades por WhatsApp.
// Calificar lead y agendar visita
app.post("/webhook", (req, res) => {
const lead = req.body.data;
const score = qualifyLead(lead);
if (score >= 7) {
client.conversations.assign({
id: lead.conversation_id,
agent: "senior_broker",
note: `Lead calificado: ${score}/10`
});
}
});Changelog
Historial de cambios
La API usa versionado por fecha. Cada request incluye X-Api-Version.
- Endpoint /v1/messages/bulk para envío masivo
- Soporte para archivos multimedia hasta 50MB
- Nuevo SDK para Go (beta)
- Fix: Rate limit headers inconsistentes en /v1/analytics
- Mejora de latencia en webhooks (p95: 18ms → 12ms)
- Endpoint /v1/bots para configurar chatbots
- Scopes granulares por recurso (OAuth 2.0)
- Paginación cursor-based en todas las listas
- Endpoint /v1/analytics con métricas por canal
- Idempotency keys para POST requests
- Soporte para Instagram DM como canal
- Endpoint /v1/teams para gestión de agentes
- Webhook event: bot.handoff
- Sandbox environment disponible
- Lanzamiento público de la API
- Endpoints core: messages, conversations, contacts, webhooks, channels
- SDKs oficiales: Node.js, Python, cURL
FAQ
Preguntas frecuentes
Todo lo que necesitas saber antes de empezar a integrar.
Empieza a construir hoy
API keys gratuitas. Sandbox incluido. Sin tarjeta de crédito.