Saltar al contenido
Operativov1.0

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.

0msp95 latency
0.9%uptime
0/mrate limit
$npm install @withmia/sdk
1234567891011
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...
200
23msapplication/json
{ "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.

01
01

Obtén tu API Key

Crea una cuenta y genera tu token de acceso desde el dashboard. Sandbox gratuito incluido.

Authorization: Bearer sk_live_...
02
02

Instala el SDK

Instala la librería oficial para tu lenguaje con un solo comando.

npm install @withmia/sdk
03
03

Enví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.

Ejemplo de autenticació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-generated
Tokens nunca se loguean ni se exponen en respuestas

Referencia API

Endpoints

api.withmia.com/v1Live
POST/v1/messages

Enviar mensaje a cualquier canal conectado

Request
POST https://api.withmia.com/v1/messages
Authorization: Bearer sk_live_...
Content-Type: application/json
Response
200
{ "id": "msg_7f3kQ9x", "status": "queued", "channel": "whatsapp", "to": "+569...", "created_at": "2026-02-24T14:32:01Z" }

Códigos de Error

Respuestas predecibles

HTTP Status Codes
200OK
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
422Unprocessable
429Rate Limited
500Server Error
Formato de error estándar
{
  "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"
  }
}
Rate limit excedido (429)
// Headers de respuesta
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708872000
Retry-After: 30

Paginació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.

Ejemplo de paginación + filtros
// 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

Burst: 20/s
Gratis

Starter

1,000

req/minuto

Burst: 50/s
$49/mes
Popular

Growth

5,000

req/minuto

Burst: 200/s
$149/mes

Enterprise

Custom

req/minuto

Burst: Custom
Contactar

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

$npm install @withmia/sdk
1234567891011
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 types8 events
message.received
message.delivered
message.failed
conversation.created
conversation.assigned
contact.updated
channel.status
bot.handoff
POSTyour-endpoint.com/webhook
{
  "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..."
}
HMAC-SHA256 signature included in every payload

API Playground

Prueba en vivo

Ejecuta requests directamente desde tu navegador. Sandbox mode — sin efectos reales.

WITHMIA API PlaygroundSANDBOX
https://api.withmia.com
Bodyapplication/json
Response

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

RESTSDKWS

WITHMIA API

Orquestador inteligente

OAuth 2.0IA/NLP<23ms
WA
IG
MSG
Mail
Chat
API

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.

e-commerce.js
12345678910
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.

agendamiento.js
12345678910
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.

salud.js
12345678910
// 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.

educación.js
123456789
// 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.

inmobiliaria.js
12345678910111213
// 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.

v1.4.0Feb 2026feature
  • Endpoint /v1/messages/bulk para envío masivo
  • Soporte para archivos multimedia hasta 50MB
  • Nuevo SDK para Go (beta)
v1.3.2Ene 2026fix
  • Fix: Rate limit headers inconsistentes en /v1/analytics
  • Mejora de latencia en webhooks (p95: 18ms → 12ms)
v1.3.0Dic 2025feature
  • Endpoint /v1/bots para configurar chatbots
  • Scopes granulares por recurso (OAuth 2.0)
  • Paginación cursor-based en todas las listas
v1.2.0Nov 2025feature
  • Endpoint /v1/analytics con métricas por canal
  • Idempotency keys para POST requests
  • Soporte para Instagram DM como canal
v1.1.0Oct 2025feature
  • Endpoint /v1/teams para gestión de agentes
  • Webhook event: bot.handoff
  • Sandbox environment disponible
v1.0.0Sep 2025release
  • 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.

TLS 1.3
HMAC-SHA256
OAuth 2.0
99.9% SLA
Multi-region
Versioning
Comienza gratis

Empieza a construir hoy

API keys gratuitas. Sandbox incluido. Sin tarjeta de crédito.