Ir al contenido
OmniMessage

API de pasarela de mensajería

Una sola API para todos los canales de mensajería

Envía mensajes de WhatsApp Business, SMS, Telegram, Messenger, Instagram y TikTok a través de un único endpoint REST. Prepago, facturado por mensaje saliente, con webhooks de entrega y modo de prueba.

Obtén una clave de APILee la documentación
Desde
0,0003 $
por mensaje saliente
Al registrarte
100
mensajes gratis
Permanencia
Ninguna
prepago, sin contrato
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
    "to": "+971501234567",
    "type": "text",
    "text": { "body": "Your order #1042 has shipped." },
    "reference": "order-1042"
  }'
202 Accepted
{
  "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
  "object": "message",
  "mode": "live",
  "channel_id": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "channel_type": "whatsapp",
  "direction": "outbound",
  "to": "+971501234567",
  "from": "+971800123456",
  "type": "text",
  "content": {
    "text": { "body": "Your order #1042 has shipped." }
  },
  "status": "queued",
  "error": null,
  "reference": "order-1042",
  "metadata": {},
  "billing": {
    "source": "wallet",
    "amount_micros": 1000,
    "package_grant_id": null,
    "refunded": false
  },
  "created_at": "2026-10-05T09:30:00.000Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": null
}
  • Tipos de canal7 detrás de un solo endpoint
  • Tipos de mensaje9, del texto a las listas interactivas
  • Precio desde0,0003 $ por mensaje saliente
  • Límite de frecuencia100 solicitudes por segundo por clave
  • Tamaño de loteHasta 100 mensajes por solicitud
  • Reintentos de webhook8, con espera progresiva de 30 segundos a 24 horas
  • Ventana de idempotencia24 horas
  • Modo de pruebaGratis, sin necesidad de canal
  • Mensajes fallidosSe reembolsan automáticamente
  • Mensajes entrantesGratis

Canales

Siete tipos de canal, un mismo formato de solicitud

Conecta los remitentes que ya tienes. Cada uno se convierte en un ID de canal que pasas al mismo endpoint, y todos te devuelven los mismos estados.

Comparar canales

Cómo funciona

Del registro a un mensaje entregado en cuatro pasos

No hay llamada comercial ni compromiso mínimo. Puedes hacer tu primera llamada a la API en modo de prueba un minuto después de crear la cuenta.

  1. Paso 01

    Crea una cuenta

    Regístrate, verifica tu correo y crea una clave de API en la consola. Las claves de prueba funcionan de inmediato, antes de conectar ningún canal.

  2. Paso 02

    Conecta un canal

    Inicia sesión con Facebook o TikTok en la consola para conectar un número de WhatsApp, una página o una cuenta de empresa. Añade un bot de Telegram o un número de Twilio con sus credenciales, en la consola o con POST /v1/channels.

  3. Paso 03

    Envía a través de un solo endpoint

    POST /v1/messages recibe un ID de canal, un destinatario y un objeto de contenido tipado. El formato de la solicitud es el mismo en todos los canales.

  4. Paso 04

    Sigue cada entrega

    Los webhooks firmados informan de los estados enviado, entregado, leído y fallido. El mismo historial está en la consola y en GET /v1/messages.

Tipos de mensaje

Lo que envías es lo que ven

Cada mensaje tiene un tipo y un objeto de contenido bajo la clave de ese tipo. Elige uno para ver el cuerpo de la solicitud junto al mensaje que genera.

Todos los tipos de mensaje
POST /v1/messages
{
  "channel": "ch_7Hq2mN5vB8cX1zL0pK3j",
  "to": "+971501234567",
  "type": "text",
  "text": {
    "body": "Tu pedido n.º 1042 ya está en camino. Síguelo en https://example.com/t/1042",
    "preview_url": true
  },
  "reference": "order-1042"
}

Texto sin formato, aceptado por todos los tipos de canal. Activa preview_url para que el canal muestre una vista previa del enlace.

CanalesWhatsApp Business, SMS, SMS OTP, Telegram, Messenger, Instagram y TikTok

Consola

Una consola para todo lo que no es código

Crea claves, conecta canales, busca en el registro de mensajes, reenvía entregas de webhooks y gestiona la facturación. Todo lo que muestra la consola también está disponible a través de la API.

Resumen. Saldo del monedero, créditos de paquetes restantes y volumen saliente de los últimos 30 días, por cuenta y por modo. Las pantallas de esta página están dibujadas con datos de ejemplo.
Registro de mensajes. Filtra por canal, estado, destinatario o tu propia referencia, y abre cualquier mensaje para ver su historial de estados y lo que se cobró por él.
Facturación. Recarga el monedero, compra paquetes, configura la recarga automática y descarga recibos. Los créditos de paquetes muestran cuánto queda y cuándo caduca.

Precios

Paga por mensaje o compra mensajes por volumen

Recarga un monedero prepago desde 10 $ y paga el precio por mensaje de cada canal, o compra un paquete de créditos de mensajes para el volumen de tus canales más caros.

Todos los precios

10 mil mensajes

8 $

0,0008 $ por mensaje

  • 10.000 mensajes salientes
  • Válido durante 3 meses desde la compra
  • Válido en todos los tipos de canal
Empezar con el paquete 10 mil

100 mil mensajes

Destacado

60 $

0,0006 $ por mensaje

  • 100.000 mensajes salientes
  • Válido durante 6 meses desde la compra
  • Válido en todos los tipos de canal
Empezar con el paquete 100 mil

1 M mensajes

400 $

0,0004 $ por mensaje

  • 1.000.000 mensajes salientes
  • Válido durante 12 meses desde la compra
  • Válido en todos los tipos de canal
Empezar con el paquete 1 M

Pago por uso

Precio de pago por uso por mensaje saliente según el tipo de canal, en dólares estadounidenses
CanalPor mensaje
WhatsApp Business0,001 $
Telegram0,0003 $
SMS0,0005 $
SMS OTP0,0005 $
Messenger0,0005 $
Instagram0,0005 $
TikTok0,0005 $

Qué cubre el precio

  • Se facturaLos mensajes salientes aceptados por la API, en el momento en que se aceptan.
  • GratisLos mensajes entrantes, los mensajes en modo de prueba, los webhooks y la consola.
  • Se reembolsaCualquier mensaje que termine como fallido, al paquete o al monedero del que salió.
  • AparteLas tarifas que Meta, los operadores u otros proveedores cobran por el canal en sí.

Experiencia de desarrollo

Hecho para integrarse una vez y olvidarse

Webhooks firmados, reintentos seguros, un sandbox que se comporta como producción y errores sobre los que puedes ramificar tu código.

Referencia de la API

Webhooks que puedes verificar

Cada entrega se firma con HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar, en la cabecera OmniMessage-Signature. Responde con cualquier 2xx en un máximo de 10 segundos. Las entregas fallidas se reintentan ocho veces con espera progresiva, desde 30 segundos hasta 24 horas.

verify-signature.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// header is "t=<unix seconds>,v1=<hex hmac-sha256>"
export function verifySignature(rawBody, header, secret) {
  const parts = header.split(',').map((part) => part.split('='));
  const { t, v1 = '' } = Object.fromEntries(parts);

  const expected = createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const matches =
    v1.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected));

  return fresh && matches;
}
Evento message.delivered
{
  "id": "evt_8Kd2pQ7wN4xB1zR6mT3c",
  "object": "event",
  "type": "message.delivered",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "id": "msg_2b1Xw9aQ3rT8yU0pL4kZ",
      "object": "message",
      "status": "delivered",
      "reference": "order-1042",
      "delivered_at": "2026-10-05T09:30:02.871Z"
    }
  }
}

Un modo de prueba que no cuesta nada

Las claves de prueba usan canales de sandbox integrados, así que no hay nada que conectar. Los últimos dígitos del destinatario determinan el resultado simulado, y tus webhooks se disparan igual que en producción.

Solicitud de sandbox, termina como leído
curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_test_whatsapp",
    "to": "+971501230002",
    "type": "text",
    "text": { "body": "Hello from the sandbox" }
  }'

Errores con un tipo y un código

Todas las respuestas que no son 2xx tienen el mismo cuerpo: un type para la clase de fallo, un code estable sobre el que ramificar, el param causante cuando lo hay y un request_id para soporte.

402 Payment Required
{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Not enough wallet balance or package credits.",
    "request_id": "req_5Vn1cH8jL3qW6yD9sF2k",
    "doc_url": "https://omnimessage.co/docs/errors#insufficient_balance"
  }
}

  • POST idempotentes

    Envía una cabecera Idempotency-Key y un reintento dentro de las 24 horas siguientes devuelve la respuesta almacenada con Idempotent-Replayed: true, sin enviar ni cobrar dos veces.

  • Límites predecibles

    100 solicitudes por segundo por clave en POST /v1/messages y 20 en el resto. Cada respuesta incluye RateLimit-Remaining, y un 429 incluye Retry-After.

  • Envío por lotes

    POST /v1/messages/batch acepta hasta 100 mensajes. Cada elemento se acepta, se rechaza y se factura por separado, y la respuesta 207 informa de ellos por índice.

  • Claves con ámbitos

    Da a cada clave solo los ámbitos que necesita, como messages:write o billing:read, y restríngela a una lista de IP permitidas.

Preguntas

Antes de integrar

Las respuestas cortas. Las largas están en la documentación.

¿Necesito mi propio número de WhatsApp, bot o número de SMS?

Sí. OmniMessage es una pasarela a la que traes tus propios canales: conectas tu propio número de WhatsApp Cloud API, bot de Telegram, número de Twilio o cuenta social, y conservas su titularidad. La página de canales indica qué necesita cada tipo.

¿Qué se me factura exactamente?

Un cargo por cada mensaje saliente que la API acepta: un crédito de paquete si tienes alguno; si no, el precio por mensaje del tipo de canal, con cargo a tu monedero. Los mensajes entrantes y los mensajes en modo de prueba son gratuitos, y un mensaje que termina como fallido se reembolsa automáticamente.

¿Están incluidas las tarifas de Meta, de los operadores o de los proveedores?

No. La tarifa de pasarela cubre la API, el seguimiento de entregas, los webhooks y la consola. Las tarifas que Meta, Twilio u otro proveedor cobran por el canal en sí quedan entre tú y ese proveedor.

¿Cómo hago pruebas sin enviar mensajes reales?

Usa una clave que empiece por om_test_. Cada cuenta tiene un canal de sandbox por tipo, como ch_test_whatsapp. No se entrega ni se cobra nada y los estados son simulados: un destinatario terminado en 0000 falla, 0001 se queda en enviado, 0002 además se lee, y cualquier otro se entrega en unos dos segundos.

¿Qué pasa cuando se me acaba el saldo?

La API responde 402 insufficient_balance y no se pone nada en cola, así que nunca quedas debiendo dinero a posteriori. Puedes suscribirte al evento balance.low o activar la recarga automática para recargar el monedero cuando baje de un umbral que tú elijas.

¿Necesito un SDK?

No. La API es JSON sobre HTTPS con autenticación bearer, así que sirve cualquier cliente HTTP. La documentación incluye ejemplos en cURL, Node, Python y PHP.

Envía hoy tu primer mensaje en modo de prueba

Crea una cuenta, copia una clave de prueba y llama a la API antes de conectar un solo canal. Cada cuenta nueva empieza con 100 mensajes gratis.

Obtén una clave de APILee la documentación