Contrato de api para envío de mensajes push

Descripción de api de Masiv para envió de mensajes push

Contrato base

POST https://push.masivapp.com/v1/notification/sendToList

{
 "tokens": [string, ...],
 "tokensByAssociation": 
  TokensByAssociation
,
 "notification": 
  Notification
,
 "data": {
  key: value,
  ...
 }
}

Campo	Descripción
tokens (Obligatorio si no hay tokensByAssociation) Se debe especificar, ya sea el atributo “tokens” o el atributo “tokensByAssociation”	Tipo: [string, string, …] Arreglo de “strings”, con la lista de tokens a la cual se enviará la notificación. Ejemplo: [ “e5b7244fe8e07a38eea633aaaec5c”, “969423461e6a6adf967920efbd764”, “12bh8c2ioq308kkd19csbokctqlcq21” ]
tokensByAssociation (Obligatorio si no hay lista de tokens) Se debe especificar, ya sea el atributo “tokens” o el atributo “tokensByAssociation”	Tipo: (ver sección TokensByAssociation) Información que será utilizada para obtener el “token” del dispositivo a partir del número celular o email, el cual es registrado a través del endpoint de asociación.
notification (Obligatorio)	Tipo: (ver sección Notification) Plantilla con los datos básicos de la notificación
data (Opcional)	Tipo: {key:value, key:value, ...} (Tanto key como value son de tipo string) Lista arbitraria de llaves y sus respectivos valores. Puede ser usada para incluir información adicional (metadata) de utilidad para fines estadísticos, de reportería, etc. La llave no puede ser ninguna de las siguientes palabras reservadas: “from”, “message_type”, ni palabras que empiecen por “google” o “gcm”. Ejemplo: { "Campaña": "Créditos nuevos", "Destinatarios": "Todos los clientes", "Notificar máximo": "3 dispositivos" }

Notification

Estructura de un objeto “notification” para enviar los mensajes a través de diferentes plataformas

{
 "title": string,
 "message": string,
 "imageUrl": string
}

Campo	Descripción
title (Obligatorio)	Tipo: string Título de la notificación
message (Obligatorio)	Tipo: string Mensaje de la notificación
imageUrl (Opcional)	Tipo: string Debe contener la URL de una imagen que va a ser descargada en el dispositivo y mostrada en una notificación. Formatos válidos: JPEG, PNG, BMP (soportados para todas las plataformas). GIF animados y videos sólo para iOS. Android tiene un tamaño límite de 1MB.

TokensByAssociation

{
 "appId": string,
 "deviceTypesToSend": [string, ...],
 "cellphones": [string, ...],
 "emails": [string, ...]
}

Campo	Descripción
appId (Opcional)	Si se tienen múltiples aplicaciones asociadas a una cuenta con el mismo número de celular o correo se debe especificar.
deviceTypesToSend (Opcional)	Tipo: [string, string, …] Arreglo de “strings”, con la lista de tipos de dispositivos válidos para hacer envíos. Si no se especifica al menos un tipo de dispositivo, la notificación se envía a todos los celulares y/o emails encontrados. Valores válidos: "Android", "iOS", "Web"
cellphones (Obligatorio si no hay lista de emails)	Tipo: [string, string, …] Arreglo de “strings”, con la lista números celulares, que será utilizada para obtener los “tokens” de los dispositivos que fueron asociados a través del endpoint de asociación. El número celular debe tener el siguiente formato: Código País + Número Celular Ejemplo: 573141234567
emails (Obligatorio si no hay lista de cellphones)	Tipo: [string, string, …] Arreglo de “strings”, con la lista correos electrónicos, que será utilizada para obtener los “tokens” de los dispositivos que fueron asociados a través del endpoint de asociación.

Observaciones adicionales:

Los filtros “appId” y “deviceTypesToSend” se aplican únicamente a la lista de celulares y correos electrónicos que en envien en los atributos “cellphones” e “emails”.

Ejemplo JSON válido:

{
  "tokens": [
    "e5b7244fe8e07a38eea633aaaec5c",
    "969423461e6a6adf967920efbd764",
    "12bh8c2ioq308kkd19csbokctqlcq21"
  ],
  "tokensByAssociation": {
    "appId": "com.empresa.miapp",
    "deviceTypesToSend": [
      "ANDROID",
      "IOS"
    ],
    "cellphones ": [
      "5713140000000",
      "5713140000001"
    ],
    "emails": [
      "[e-mail]",
      "[e-mail]"
    ]
  },
 "notification": {
   "title": "Mensaje para lista",
   "message": "Este es un mensaje para una lista de dispositivos",
   "imageUrl": "https://dominio.com/ruta/imagen.png"
  },
  "data": {
    "Campaña": "Créditos nuevos",
    "Destinatarios": "Todos los clientes",
    "Notificar máximo": "3 dispositivos"
  }
}

Respuestas del servidor:

Code OK 200

{
  "status": "OK",
  "data": "Notification has been sent",
  "error": null
}

Code 400 Error

{
  "timestamp": "2020-07-16T00:00:56.522+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "",
  "path": "/notification/v1/sendToList"
}

Contrato de api para la asociación de tokens con celulares o correos

Contrato base

¿Por qué usarlo?

Este endpoint permite asociar un token de dispositivo (android, ios o web) a un celular y/o email.

El objetivo es poder enviar mensajes push a uno o varios dispositivos de un cliente usando un sólo email o celular, sin necesidad de especificar el token del dispositivo.

Es una funcionalidad permite integración sencilla con otros productos de Masiv cómo automation o hub express en donde fácilmente se podrían configurar flujos, los cuales que automaticamente si no logran contactar a un cliente mediante sms o llamada de voz, lo intenten hacer por push, o viceversa.

POST https://push.masivapp.com/v1/association/create

{
 "appId": string
 "token": string
 "association": 
    Association
}

Campo	Descripción
appId (Opcional)	Tipo: string Nombre de la aplicación a la cual está asociado el token específico
token (Obligatorio)	Tipo: string Contiene el token, del dispositivo específico, para el cual se asocia un número celular (cellphone) y/o un correo electrónico (email).
association (Obligatorio al menos un valor)	Tipo: (ver sección Association) Contiene los números de celular y emails asociadas al dispositivo Se quiere cell phone or email, o ambos, pero obligatoriamente uno de los dos.

Association

Objeto utilizado para recibir los emails y/o celulares asociados a un token específico.

{
 "cellphone": string
 "email": string
}

Campo	Descripción
cellphone (Obligatorio si no se indica email)	Tipo: string Número de celular válido El número celular debe tener el siguiente formato: Código País + Número Celular Ejemplo: 573141234567
email (Obligatorio si no se indica cellphone)	Tipo: string Dirección de correo electrónico válida

Ejemplo JSON válido:

{
 "appId": "com.empresa.miapp",
 "token": "asdfdgwregjirgjirjh435ggyfggghhtg9i45rj9tu4j943ujto94jhtiorgtty",
 "association": {
 "cellphone": "573141234567",
 "email": "[e-mail]"
 }
}

Respuesta del servidor:

Code OK 200

{
  "status": "OK",
  "data": "Successful association",
  "error": null
}

Code 400 Error

{
  "timestamp": "2020-07-16T00:00:56.522+00:00",
  "status": 400,
  "error": "Bad Request",
  "message": "",
  "path": "/association/v1/create"
}