Crear API de envío de notificaciones

Enviar una notificación o un mensaje a un único dispositivo o a una lista de dispositivos.

El contenido del push solo puede ser un único objeto push en formato JSON.

Para funciones relacionadas con etiquetas/alias, consulte AppPushAPI.

Esta es la versión más reciente de la Push API. Las mejoras de la versión v4 son las siguientes:

Se utiliza autenticación básica HTTP (HTTP Basic Authentication) para autorizar el acceso. De este modo, se puede completar toda la solicitud de la API utilizando herramientas HTTP comunes, como curl y complementos del navegador.
El contenido del push está en formato JSON.

Límites de tasa de solicitudes

Nuestra API impone límites a la frecuencia de llamadas para garantizar la estabilidad y la equidad del servicio. Los límites de QPS (consultas por segundo) para cada AppKey son los siguientes:

Límite estándar: un máximo de 500 solicitudes por segundo.
Límite avanzado: si usted es suscriptor de nuestro plan de pago y su AppKey de pago requiere un límite de QPS más alto, póngase en contacto con nuestro equipo comercial: Sales@engagelab.com.

Validación de llamadas

Para obtener más información, consulte Método de autenticación

Dirección de llamada

POST /v4/push

              
              POST /v4/push

Este bloque de código se muestra en una ventana flotante

Ejemplos de solicitud

Encabezado de solicitud

> POST /v4/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Este bloque de código se muestra en una ventana flotante

Cuerpo de la solicitud

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

Este bloque de código se muestra en una ventana flotante

Parámetros de la solicitud

La estructura de parámetros del push se detalla en la tabla siguiente:

Palabra clave	Tipo	Opción	Descripción
from	String	Opcional	Remitente del negocio actual
to	String o JSON Object	Obligatorio	Destino de envío
body	JSON Object	Obligatorio	Cuerpo de la solicitud de envío
platform	String o JSON Array	Obligatorio	Plataforma de push
notification	JSON Object	Opcional	El cuerpo de la notificación, que es el contenido enviado al cliente. Junto con message, debe incluirse uno, y no pueden coexistir.
message	JSON Object	Opcional	El cuerpo del mensaje, que es el contenido enviado al cliente. Junto con notification, debe incluirse uno, y no pueden coexistir.
options	JSON Object	Opcional	Parámetros de push
request_id	String	Opcional	Campo opcional personalizado que utiliza el cliente para identificar la solicitud y que se devuelve en la respuesta.
custom_args	JSON Object	Opcional	Campos opcionales personalizados por el cliente, que se devuelven al cliente durante el callback.

from

El remitente del negocio actual. El valor es de tipo String y es opcional.

Ejemplos de solicitud

{ "from":"push" }

              
              {
    "from":"push"
}

Este bloque de código se muestra en una ventana flotante

to

Objeto de dispositivo de push, que indica la lista de dispositivos a los que se puede enviar un push. MTPush proporciona dos métodos: Registration ID y difusión.

Destino de push

Palabra clave	Tipo	Significado	Descripción	Nota
all	String	Difusión	Enviar a todos los dispositivos	Enviar a los dispositivos objetivo que hayan estado activos en los últimos 365 días.
registration_id	JSON Array	Registration ID	Array. La relación entre múltiples registration_id es OR, es decir, la unión.	El ID del dispositivo. Se pueden enviar como máximo 1000 por vez.
tag	JSON Array	Etiqueta	Array. La relación entre múltiples etiquetas es OR, es decir, se toma la unión.	Utilizar etiquetas para segmentar atributos de dispositivos y atributos de usuarios a gran escala. Enviar hasta 20 por vez. Composición válida de etiquetas: letras (distingue mayúsculas/minúsculas), números, guiones bajos y caracteres chinos. Límite: la longitud de cada etiqueta está limitada a 40 bytes. (Se requiere codificación UTF-8 para determinar la longitud)
tag_and	JSON Array	Etiqueta AND	Array. Múltiples etiquetas están en relación AND, es decir, se toma la intersección.	Tener en cuenta la distinción con tag; hasta 20 por vez.
tag_not	JSON Array	Etiqueta NOT	Array. Entre múltiples etiquetas, primero se toma el conjunto combinado de múltiples etiquetas y, después, se toma el conjunto complementario de ese resultado.	Enviar hasta 20 por vez.
alias	JSON Array	Alias	Array. Múltiples alias están en relación OR, es decir, se toma la unión.	Identificar a un usuario mediante un alias. Un dispositivo solo puede vincularse a un alias, y viceversa. Enviar hasta 1000 por vez. Composición válida de alias: letras (distingue mayúsculas/minúsculas), números, guiones bajos y caracteres chinos. Límite: la longitud de cada alias está limitada a 40 bytes. (Se requiere codificación UTF-8 para determinar la longitud)

La relación implícita entre múltiples valores en un array es OR, es decir, se toma la unión; sin embargo, tag_and es diferente, ya que la relación entre múltiples valores en un array es AND, es decir, se toma la intersección.

Si se utiliza tag_not de forma independiente, se realizará el procesamiento tag_not entre los usuarios de difusión.

Estos tipos pueden coexistir. La relación implícita entre múltiples tipos cuando coexisten es AND, es decir, se toma la intersección. Por ejemplo:

"to" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }

              
              "to" : {"tag" : [ "tag1", "tag2"],
"tag_and" : ["tag3", "tag4"],
"tag_not" : ["tag5", "tag6"]
}

Este bloque de código se muestra en una ventana flotante

Primero, calcular el resultado del campo "tag": tag1 or tag2 = A;

A continuación, calcular el resultado del campo "tag_and": tag3 and tag4 = B;

A continuación, calcular el resultado del campo "tag_not": not (tag5 or tag6) = C;

El resultado final de "to" es A and B and C.

Ejemplos de solicitud

Enviar a todos (difusión):

{ "to": "all", }

              
              {
  "to": "all",
}

Este bloque de código se muestra en una ventana flotante

Enviar a múltiples Registration ID:

{ "to": { "registration_id": [ "1a3018970ab49abcd8e", "1537bfd3f7d57d13cef", "163a3797c816b1160dc" ] } }

              
              {
  "to": {
    "registration_id": [
      "1a3018970ab49abcd8e",
      "1537bfd3f7d57d13cef",
      "163a3797c816b1160dc"
    ]
  }
}

Este bloque de código se muestra en una ventana flotante

body

Cuerpo de la solicitud de envío. Los campos admitidos son los siguientes:

Palabra clave	Tipo	Opción	Descripción
platform	String o JSON Array	Obligatorio	Plataforma de push
notification	JSON Object	Opcional	El cuerpo de la notificación, que es el contenido enviado al cliente. Junto con message, debe incluirse uno, y no pueden coexistir.
message	JSON Object	Opcional	El cuerpo del mensaje, que es el contenido enviado al cliente. Junto con notification, debe incluirse uno, y no pueden coexistir.
options	JSON Object	Opcional	Parámetros de push

platform

MTPush actualmente solo admite push en la plataforma Web, por lo que la palabra clave de platform es: "web".

{ "platform" : "web" }

              
              { "platform" : "web" }

Este bloque de código se muestra en una ventana flotante

notification

El objeto "notification" es uno de los objetos de contenido de un push (el otro es "message"), y se envía a la Web como una notificación.

Palabra clave	Tipo	Opción	Significado	Descripción
web	JSON Object	Obligatorio	Atributo de plataforma	Parámetros de push de la plataforma

web

Notificación en la plataforma Web.

Palabra clave	Tipo	Opción	Significado	Descripción
alert	String o JSON Object	Obligatorio	Contenido	El contenido del mensaje en sí; si se especifica aquí, sobrescribe el alert de nivel superior.
url	String	Obligatorio	URL de Web Push	Dirección de redirección al hacer clic en la notificación
title	String	Opcional	Título	Título del mensaje
extras	JSON Object	Opcional	Campos ampliados	Información Key/Value personalizada en formato JSON para uso empresarial.
icon	String	Opcional	Icono de notificación	Se recomienda 192×192 px, sin restricción estricta; tamaño máximo 1 M, formatos: JPG, PNG, GIF. Compatible con Chrome, Firefox (Safari y Edge no admiten personalización).
image	String	Opcional	Imagen grande	Se recomienda 360×180 px, sin restricción estricta; tamaño máximo 1 M, formatos: JPG, PNG, GIF. Compatible con Chrome, Edge (Firefox y Safari no son compatibles).

{ "notification": { "web": { "alert": "hello, Push!", "title": "Push Test", "url":"http://www.google.com", "icon":"", "image":"", "extras": { "news_id": 134, "my_key": "a value" } } } }

              
              {
    "notification": {
        "web": {
            "alert": "hello, Push!",
            "title": "Push Test",
            "url":"http://www.google.com",
            "icon":"",
            "image":"",
            "extras": {
                "news_id": 134,
                "my_key": "a value"
            }
        }
    }
}

Este bloque de código se muestra en una ventana flotante

message

Mensaje dentro de la aplicación. También conocido como: mensaje personalizado o mensaje transparente. Este contenido no se mostrará en el navegador. Tras recibir el contenido del mensaje, el SDK lo transmite a la Web, que se encarga de la lógica empresarial.

El mensaje contiene los siguientes campos:

Palabra clave	Tipo	Opción	Descripción
msg_content	String o JSON Object	Obligatorio	Contenido del mensaje
title	String	Opcional	Título del mensaje
content_type	String	Opcional	Tipo de contenido del mensaje
extras	JSON Object	Opcional	Parámetros opcionales en formato JSON

Ejemplo:

{ "message": { "msg_content": "Hi,Push", "content_type": "text", "title": "msg", "extras": { "key": "value" } } }

              
              {
  "message": {
    "msg_content": "Hi,Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "value"
    }
  }
}

Este bloque de código se muestra en una ventana flotante

options

Opciones de push. Actualmente incluye las siguientes opciones:

Palabra clave	Tipo	Opción	Significado	Descripción
time_to_live	Int o String	Opcional	Duración de retención de mensajes offline (segundos)	Si el usuario no está en línea en el momento del push, el mensaje offline se puede retener durante el tiempo especificado para reenviarlo cuando esté en línea. El valor predeterminado es 86400 (1 día), máximo 15 días. Si el valor máximo admitido por el navegador es menor que el valor configurado, prevalece el máximo del sistema. Establecer en 0 significa no retener mensajes offline; solo los usuarios en línea pueden recibirlos.
override_msg_id	Long	Opcional	ID del mensaje a sobrescribir	Si el push actual debe sobrescribir un push anterior, introduzca aquí el msg_id del push anterior: Los mensajes offline recibidos con ese msg_id tendrán el contenido actualizado. Si la notificación ya fue recibida pero no se ha eliminado de la barra de notificaciones, el nuevo contenido la sobrescribirá. El tiempo límite de la función de sobrescritura es 1 día. Si el msg_id no existe en ese plazo, se devuelve el error 1003, indicando que no es una operación válida de sobrescritura, y el mensaje actual no se enviará.
big_push_duration	Int	Opcional	Duración del push a velocidad controlada (minutos)	También conocido como push lento. Reduce la velocidad de envío para distribuir uniformemente el push a los usuarios objetivo en los n minutos indicados; el valor máximo es 1440. Puede haber hasta 20 pushes con velocidad controlada simultáneamente. Si no se configura, no se aplica velocidad controlada.
web_buttons	JSON Object	Opcional	Añadir botones a la notificación	Se pueden añadir hasta 2 botones. Se puede configurar el nombre del botón y el enlace de redirección. Para más detalles, consulte web_buttons.
multi_language	JSON Object	Opcional	Configuración de push multilingüe	Configuración de adaptación multilingüe del contenido del push. Para más detalles, consulte multi_language.
third_party_channel	JSON Object	Opcional	Información de configuración del canal del sistema Web	Parámetro válido solo para usuarios configurados con canales del sistema. Para más detalles, consulte third_party_channel.
plan_id	String	Opcional	Identificador del plan de push	Es necesario crear previamente un valor de identificador de plan, que se puede crear desde la consola o a través de la API.
cid	String	Opcional	Identificador de solicitud de push para evitar pushes duplicados	Solo se permiten letras, números, guiones bajos y guiones, con una longitud máxima de 64 caracteres. Este campo debe ser único bajo el mismo AppKey.

multi_language

Este campo es la funcionalidad de push multilingüe del servicio EngageLab Push. Permite enviar notificaciones personalizadas para usuarios de diferentes idiomas. Al especificar múltiples idiomas y su contenido de mensaje, título correspondiente en la solicitud de push, puede enviar notificaciones adecuadas según la configuración de idioma del usuario.

Parámetros de solicitud

Palabra clave	Tipo	Opción	Significado	Descripción
en	String	Opcional	Clave de idioma múltiple	Corresponde al idioma del usuario del push. Consulte los códigos de idioma en el apéndice.
content	String	Opcional	Contenido del mensaje	Reemplaza los datos de notification.web.alert y message.msg_content según el idioma del usuario.
title	String	Opcional	Título del mensaje	Reemplaza los datos de notification.web.title y message.title según el idioma del usuario.

Ejemplo de solicitud

{ "options": { "multi_language": { "en": { "content": "", "title": "", } } } }

              
                 {
    "options": {
      "multi_language": {
        "en": {
          "content": "",
          "title": "",
        }
      }
    }
   }

Este bloque de código se muestra en una ventana flotante

web_buttons

Utilice el parámetro web_buttons para describir el id, texto, icono y url del botón. La descripción de los parámetros es la siguiente:

Palabra clave	Tipo	Opción	Significado	Descripción
id	Obligatorio	String	ID del botón	Compatible con Chrome 48+
text	Obligatorio	String	Contenido del botón	Compatible con Chrome 48+
icon	Opcional	String	Icono del botón	Compatible con Chrome 50+
url	Obligatorio	String	Enlace de redirección del botón	Compatible con Chrome 48+. Si se utiliza web_buttons, la url del campo web no tendrá efecto.

Ejemplo:

[ { "id": "like-button", "text": "Like", "icon": "http://i.imgur.com/N8SN8ZS.png", "url": "https://yoursite.com" }, { "id": "read-more-button", "text": "Read more", "icon": "http://i.imgur.com/MIxJp1L.png", "url": "https://yoursite.com" } ]

              
              [
  {
    "id": "like-button",
    "text": "Like",
    "icon": "http://i.imgur.com/N8SN8ZS.png",
    "url": "https://yoursite.com"
  },
  {
    "id": "read-more-button",
    "text": "Read more",
    "icon": "http://i.imgur.com/MIxJp1L.png",
    "url": "https://yoursite.com"
  }
]

Este bloque de código se muestra en una ventana flotante

third_party_channel

Este campo se utiliza para rellenar la información personalizada del canal del sistema Web. El nombre de la clave es w3push y el valor es un objeto JSON que solo contiene un campo opcional distribution de tipo String.

Palabra clave	Tipo	Opción	Significado	Descripción
distribution	Obligatorio	String	Establecer la prioridad de entrega cuando Engagelab y el canal del sistema coexisten	El valor no puede ser una cadena vacía. El valor predeterminado es first_ospush. first_ospush: el push se envía primero a través del canal del sistema; si no es válido, se envía a través del canal Engagelab. mtpush: el push se envía obligatoriamente a través del canal Engagelab. secondary_push: el push se envía primero a través de Engagelab; si Engagelab no está en línea, se utiliza el canal del sistema como auxiliar (se recomienda este método). ospush: el push se envía obligatoriamente solo a través del canal del sistema.

Ejemplo:

{ "third_party_channel":{ "w3push":{ "distribution":"mtpush" } } }

              
              {
  "third_party_channel":{
    "w3push":{
      "distribution":"mtpush"
    }
  }
}

Este bloque de código se muestra en una ventana flotante

request_id

ID de solicitud, campo opcional personalizado por el cliente. El cliente lo utiliza para identificar la solicitud y se devuelve en la respuesta.

Ejemplo de solicitud

{ "request_id":"12345678" }

              
              {
      "request_id":"12345678"
}

Este bloque de código se muestra en una ventana flotante

Ejemplo de respuesta

custom_args

Campo opcional personalizado por el cliente. No se devuelve en la respuesta, pero se devuelve durante el callback.

{ "custom_args":"business info" }

              
              {
  "custom_args":"business info"
}

Este bloque de código se muestra en una ventana flotante

Parámetros de respuesta

Respuesta exitosa

Campo	Tipo	Opción	Descripción
request_id	String	Opcional	El ID personalizado enviado en la solicitud, se devuelve tal cual en la respuesta.
message_id	String	Obligatorio	ID del mensaje, identifica de forma única un mensaje.

< HTTP/1.1 200 OK < Content-Type: application/json {"request_id":"18","msg_id":"1828256757"}

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id":"18","msg_id":"1828256757"}

Este bloque de código se muestra en una ventana flotante

Respuesta fallida

El código de estado HTTP es 4xx o 5xx. El cuerpo de la respuesta contiene los siguientes campos:

Campo	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error. Consulte la descripción de Códigos de error.
message	String	Obligatorio	Detalles del error

{ "code": 3002, "message": "Push.template field must be set correctly when type is template" }

              
              {
    "code": 3002,
    "message": "Push.template field must be set correctly when type is template"
}

Este bloque de código se muestra en una ventana flotante

Respuesta de llamada

Código de estado HTTP

Documento de referencia: HTTP-Status-Code

Códigos de error

Code	Descripción	Explicación detallada	HTTP Status Code
20101	Parámetro de push no válido	registration_id no válido o no pertenece al appkey actual	400
21001	Solo se admite el método HTTP Post	No se admite el método Get	405
21002	Falta un parámetro obligatorio	Debe corregirse	400
21003	Valor del parámetro no válido	Debe corregirse	400
21004	Error de autenticación	Debe corregirse. Para más detalles, consulte: validación de llamadas	401
21005	Cuerpo del mensaje demasiado grande	Debe corregirse. Límite de longitud de Notification+Message: 2048 bytes	400
21008	Parámetro app_key no válido	Debe corregirse. Verifique si el appkey transmitido es una cadena de 24 caracteres y si contiene espacios adicionales.	400
21009	Error interno del sistema	Debe corregirse	400
21011	No hay destinos de push que cumplan las condiciones	Verifique el campo to	400
21015	Error de validación de parámetros de solicitud	Existen parámetros no esperados	400
21016	Error de validación de parámetros de solicitud	Tipo de parámetro incorrecto o longitud del parámetro excede el límite	400
21039	Error en parámetros de web button	id, url o text del botón están vacíos	400
21040	Error en parámetros de web button	La cantidad de botones excede 2	400
21041	Error en parámetros de web button	Formato de url no válido	400
21042	Error en parámetros de web button	id del botón duplicado	400
21030	Tiempo de espera del servicio interno	Reintentar más tarde	503
23006	Error de parámetro	big_push_duration del push a velocidad controlada excede el valor máximo 1440	400
23008	Límite de tasa de la interfaz	El QPS de la interfaz de push de la aplicación ha alcanzado el límite (500 qps)	400
27000	Error de memoria del sistema	Reintentar	500
27001	Información de autenticación no válida	El AppKey en Basic Auth tiene 24 caracteres pero la aplicación no existe, o la información de autenticación de la aplicación no es válida	401
27008	Error de parámetro	distribution en third_party_channel no está vacío, pero el contenido alert de notification está vacío	401
27009	Error de parámetro	El formato de distribution en third_party_channel no es válido o está vacío	401

Restricciones de push

Canal	Longitud del título	Longitud del contenido	Otras instrucciones
Canal Engagelab	Sin límite, pero se limita el tamaño total del cuerpo del mensaje	Sin límite, pero se limita el tamaño total del cuerpo del mensaje	La longitud de Notification en MTPush está limitada a 4000 bytes.
Canal del sistema	< 20 caracteres (40 caracteres en inglés)	El centro de notificaciones y la pantalla de bloqueo muestran hasta 110 caracteres, 55 caracteres chinos. La ventana emergente superior muestra hasta 62 caracteres, 31 caracteres chinos; el exceso se muestra con puntos suspensivos.	Ninguna

Códigos de idioma

Nombre del idioma	Código de idioma
Inglés	en
Árabe	ar
Chino (simplificado)	zh-Hans
Chino (tradicional)	zh-Hant
Checo	cs
Danés	da
Neerlandés	nl
Francés	fr
Alemán	de
Hindi	hi
Italiano	it
Japonés	ja
Coreano	ko
Malayo	ms
Ruso	ru
Español	es
Tailandés	th
Vietnamita	vi
Indonesio	id
Noruego	no
Sueco	sv
Polaco	pl
Turco	tr
Hebreo	he
Portugués	pt
Rumano	ro
Húngaro	hu
Finés	fi
Griego	el
Ucraniano	uk
Laosiano	lo
Portugués (Portugal)	pt_PT
Portugués (Brasil)	pt_BR
Español (Argentina)	es_AR
Español (España)	es_ES
Español (Latinoamérica)	es_419

Push API v4

Límites de tasa de solicitudes

Validación de llamadas

Dirección de llamada

Ejemplos de solicitud

Parámetros de la solicitud

from

Ejemplos de solicitud

to

Destino de push

Ejemplos de solicitud

body

platform

notification

web

message

options

multi_language

Parámetros de solicitud

Ejemplo de solicitud

web_buttons

third_party_channel

request_id

Ejemplo de solicitud

Ejemplo de respuesta

custom_args

Parámetros de respuesta

Respuesta exitosa

Respuesta fallida

Respuesta de llamada

Código de estado HTTP

Códigos de error

Restricciones de push

Códigos de idioma