Enviar notificaciones

Un envío es un POST /v1/notifications con tu llave secreta, o lo mismo desde Notificaciones → Nueva en el panel. Responde 202 de inmediato y se entrega en segundo plano.

{
  "target": { "type": "external_users", "ids": ["cliente-123"] },
  "content": {
    "es": { "title": "Tu pedido va en camino", "body": "Llega hoy" },
    "en": { "title": "Your order is on its way", "body": "Arriving today" }
  },
  "data": { "orderId": "A-1029" },
  "deepLink": "miapp://pedidos/A-1029"
}

Destinos (target.type)

Tipo	Campos	Alcanza a
devices	ids o tokens	Dispositivos concretos
external_users	ids	Todos los dispositivos de esos usuarios (externalUserId)
topic	name	Los suscritos al topic
segment	segmentId	Los que cumplen un segmento guardado
filters	rules	Un filtro al vuelo (mismo formato que los segmentos)
all	—	Todos los dispositivos activos de la app
test_devices	—	Solo los dispositivos de prueba

Con una llave test, cualquier destino se limita a los dispositivos de prueba. platforms: ["ios"] restringe a una plataforma.

Contenido

• Por idioma: content.es, content.en… con title, subtitle (iOS) y body. Cada dispositivo recibe su idioma; si no está, el idioma por defecto de la app.
• Variables: {{nombre}} en el texto, con sus valores en variables.
• Plantillas: templateId usa una plantilla guardada; lo que envíes en la petición tiene prioridad.
• contentType:
  • alert, la visible (por defecto);
  • data_only, solo datos: la app arma la notificación. El título y el texto viajan en data, en las claves que lee el plugin de tu framework (title y body; title y message en Cordova y Expo). Ver Compatibilidad;
  • silent, para actualizar la app en segundo plano.

Datos, enlaces y botones

• data: hasta 50 claves que tu app recibe. No uses claves que empiecen por _ph: son de PushHub.
• deepLink: la app lo recibe al tocar la notificación.
• actions: hasta 3 botones { id, title, deepLink }. Requieren código en la app (o el SDK).
• sound: default o un sonido incluido en la app y registrado en el panel.
• badge (iOS), ttlSeconds (hasta 28 días), priority (high / normal).
• Opciones por plataforma:
  • android: channelId, color, tag, collapseKey;
  • ios: interruptionLevel, threadId, relevanceScore.

Categoría

• transactional (por defecto): pedidos, seguridad, recordatorios del usuario.
• marketing: promociones. Va por una cola de menor prioridad, para que nunca retrase a las transaccionales, y respeta los límites de la app.

Límites de marketing

En la configuración de cada app (Apps → editar → Envíos de marketing) puedes fijar dos límites. Se aplican en la hora local de cada dispositivo y solo a los envíos marketing:

• Máximo por dispositivo y día: las notificaciones que pasan el límite se omiten. Aparecen como skipped (código FREQUENCY_CAP) y no cuentan como fallidas.
• Horas de silencio (por ejemplo, de 22:00 a 08:00): la entrega se aplaza hasta la hora de fin. El envío sigue en sending hasta entregarlas, y stats.deferred cuenta cuántas se aplazaron.

Si el dispositivo no informó su zona horaria, se usa la de la empresa. El SDK la envía siempre.

Validar sin enviar

"validateOnly": true valida todo, estima cuántos dispositivos alcanzaría y calcula el tamaño del payload, sin crear el envío.

El payload no puede pasar de 4 KB (2003): la multimedia nunca viaja en el payload, solo su URL.

Seguimiento

• GET /v1/notifications/{id}: estado y estadísticas (enviadas, aceptadas, fallidas, tokens inválidos, aperturas, clics).
• GET /v1/notifications/{id}/deliveries: el resultado por dispositivo.
• POST /v1/notifications/{id}/cancel: cancela un envío programado o en curso.
• Webhooks notification.completed y notification.failed al terminar. Ver Webhooks.