image


Notification manager API


Contents

  1. Devices
  2. Notifications
  3. Counters
  4. Send
  5. Templates
  6. Tags
  7. Aditional information

1. Devices

1.1. List devices

Endpoint: HTTP POST /devices

Content-type: application/json

Parameters:

Name Type Description Optional
users array Users ID on which you want to consult their devices NO

Example:

{
    "users": ["U00001", "U00002"]
}

Response:

HEADER CODE
StatusCode 201

Response example:

{
  "U00001": [
    {
      "deviceId": 'ANDROID-XXXXX',
      "userId": '00001',
      "lang": 'es-es',
      "country": 'spain',
      "operator": 'movistar',
      "sdkVersion": '3.0.0',
      "osName": 'Android',
      "osVersion": '7.0',
      "deviceBrand": 'motorola',
      "deviceModel": 'Moto G (4)',
      "created": '2017-08-27T13:16:10.000Z'
    },
    ...
  ],
  ...
}

1.2. Associate a device to a user

Endpoint: HTTP POST /user/:userId/device/:deviceId

Content-type: application/json

Parameters:

Name Type Description Optional
deviceId string Device ID NO
userId string User ID NO
lang string Language YES
osName  string Operating system YES
osVersion string Operating system version YES

Example:

{
  "lang": "es-ES",
  "osName": "Android",
  "osVersion": "7.0"
}

Response:

HEADER CODE
StatusCode 201

1.3. Delete a device

Endpoint: HTTP DELETE /user/:userId/device/:deviceId

Parameters:

Name Type Description Optional
deviceId string Device ID NO
userId string User ID NO

Response:

HEADER CODE
StatusCode 204

2. Notifications

2.1. List notifications

Endpoint: HTTP GET /user/:userId/notification

Parameters:

Name Type Description Optional
userId string User ID NO
page number Page number NO
pageSize number Elements per page NO
status  array States list that should have the response notifications YES

Example:

/user/U00001/notification?page=0&pageSize=10&status=sent,read

Response example:

[
  {
    "notificationId": "123123",
    "userId": "U00001",
    "status": "sent",
    "new": false,
    "templateId":"0000001",
    "created": "2017-06-17T08:45:43.000Z",
    "message":{
        "title": "title",
        "uri": "http://.../index.html",
        "description": "description",
      ...
    }
  },
  ...
]

Look the message object definition


2.2. Get one notification

Endpoint: HTTP GET /user/:userId/notification/:notificationId

Parameters:

Name Type Description Optional
userId string User ID NO
notificationId string Notification ID NO

Example:

/user/U00001/notification/123123

Response

HEADER CODE
StatusCode 200

Response example:

{
  "notificationId": "123123",
  "userId": "U00001",
  "status": "sent",
  "new": false,
  "templateId":"0000001",
  "created": "2017-06-17T08:45:43.000Z",
  "message":{
    "title": "title",
    "uri": "http://.../index.html",
    "description": "description",
    ...
  }
}

2.3. Update one notification

Endpoint: HTTP PUT /user/:userId/notification/:notificationId

Content-type: application/json

Parameters:

Name Type Description Optional
userId string User ID NO
notificationId string Notification ID NO
status string Notification status NO

Example:

{
    "status": "read"
}

Response:

HEADER CODE
StatusCode 201

2.4. Update all notifications of a user

Endpoint: HTTP PUT /user/:userId/notification/all

Content-type: application/json

Parameters:

Name Type Description Optional
userId string User ID NO
status string Notification status NO

Example:

{
    "status": "deleted"
}

Response:

HEADER CODE
StatusCode 201

3. Counters

3.1. Get counters

Endpoint: HTTP GET /user/:userId/counters

Parameters:

Name Type Description Optional
userId string User ID NO

Response example:

{
  "new": 27,
  "read": 4,
  "sent": 33,
  "deleted": 0
}

4. Send notifications

4.1. Send simple notification

Endpoint: HTTP POST /message/send

Content-type: application/json

Parameters:

Name Type Description Optional
message object Message data NO
users array List of users to notify NO
inbox string Shows if it will be saved in the mailbox YES
allDevices boolean Send to all user devices or only to the last device registered YES

Example:

{
    "message":{
        "title": "title",
        "description": "description",
    ...
    },
    "inbox": "inbox_and_push",
    "allDevices": true,
    "users": ["U00001", "U00002"]
}

Response:

HEADER CODE
StatusCode 201

Response example:

{
  "indigitallMessageId": 9
}

Attention! If "inbox" is set as "inbox_only", won´t be returned message ID


4.2. Send notification using a template

Endpoint: HTTP POST /template/:templateId/send

Content-type: application/json

Parameters:

Name Type Description Optional
templateId string Template ID NO
data object Data which will be mixed with the template YES
users array List of users to notify NO
inbox string Shows if it will be saved in the mailbox YES
allDevices boolean Send to all user devices or only to the last device registered YES

Example:

{
    "data": {
        "name": "John Doe",
        "country": "Spain",
    ...
    },
  "inbox": "inbox_and_push",
    "allDevices": true,
    "users": ["U00001", "U00002"]
}

Response:

HEADER CODE
StatusCode 201

Response example:

{
  "indigitallMessageId": 9
}

Attention! If "inbox" is set as "inbox_only", won´t be returned message ID

5. Templates

5.1. List templates

Endpoint: HTTP GET /template

Parameters: None

Response example:

[
  {
    "templateId": "NT001AT02",
    "message": {
      "title": "Hello <%=name%>",
      "description": "Welcome to <%=country%>",
      ...
    },
    "defaultData": {
      "name":"John Doe",
      "country":"Spain",
      ...
    },
    "inbox": "inbox_and_push",
    "allDevices": true,
    "created": "2017-07-13T18:26:40.000Z"
  },
    ...
]

5.2. Read a template

Endpoint: HTTP GET /template/:templateId

Parameters:

Name Type Description Optional
templateId string Template ID NO

Response:

HEADER CODE
StatusCode 200

Response example:

{
    "templateId": "NT001AT02",
    "message": {
        "title": "Hello <%=name%>",
        "description": "Welcome to <%=country%>",
        ...
    },
    "defaultData": {
        "name":"John Doe",
        "country":"Spain",
    ...
    },
    "inbox": "inbox_and_push",
    "allDevices": true,
    "created": "2017-07-13T18:26:40.000Z"
}

5.3. Create a template

Endpoint: HTTP POST /template

Content-type: application/json

Parameters:

Name Type Description Optional
templateId string Template ID NO
message object Message data NO
defaultData object Message default data NO
inbox string Shows if it will be saved in the mailbox YES
allDevices boolean Send to all user devices or only to the last device registered YES

Example:

{
    "templateId": "NT001AT02",
    "message": {
        "title": "Hello <%=name%>",
        "description": "Welcome to <%=country%>",
        ...
    },
    "defaultData": {
        "name":"John Doe",
        "country":"Spain",
    ...
    },
    "inbox": "inbox_and_push",
    "allDevices": true
}

Response:

HEADER CODE
StatusCode 204

5.4. Update a template

Endpoint: HTTP PUT /template/:templateId

Content-type: application/json

Parameters:

Name Type Description Optional
templateId string Template ID NO
message object Message data YES
defaultData object Message default data YES
inbox string Shows if it will be saved in the mailbox YES
allDevices boolean Send to all user devices or only to the last device registered YES

Example:

{
    "message": {
        "title": "Hello <%=name%>",
        "description": "Welcome to <%=country%>",
        ...
    },
    "defaultData": {
        "name":"John Doe",
        "country":"Spain",
    ...
    },
    "inbox": "inbox_and_push",
    "allDevices": true
}

Response:

HEADER CODE
StatusCode 201

5.5. Delete a template

Endpoint: HTTP DELETE /template/:templateId

Parameters:

Name Type Description Optional
templateId string Template ID NO

Response:

HEADER CODE
StatusCode 204

6 Tags

6.1. List avaliable tags

Endpoint: HTTP GET /tag

Parameters:

Example response:

[
    {
        "id": "customer_premium",
        "name": "Premium customers"
    },
    {
        "id": "customer_default",
        "name": "Normal customers"
    },
    ...
]

6.2. List tags from user

Endpoint: HTTP GET /user/:userId/tag

Parameters:

Nombre Tipo Descripción Opcional
userId string user identifier NO

Example response:

[
    {
        "id": "customer_premium",
        "name": "Premium customers"
    },
    {
        "id": "customer_default",
        "name": "Normal customers"
    },
    ...
]

6.3. Add tag to user

Endpoint: HTTP POST /user/:userId/tag/:tagId

Content-type: application/json

Parameters:

Nombre Tipo Descripción Opcional
userId string user identifier NO
tagId string tag identifier NO

Example:

{}

Response:

HEADER CODE
StatusCode 201

6.4. Delete tag from user

Endpoint: HTTP DELETE /user/:userId/tag/:tagId

Content-type: application/json

Parameters:

Nombre Tipo Descripción Opcional
userId string user identifier usuario NO
tagId string tag identifier NO

Response:

HEADER CODE
StatusCode 204

7. Additional information

7.1. HTTP calls authorization

To authenticate a call there are two methods:

  • Using the header "Authorize" and putting the token with "Bearer 1111" Example:
key value
Authorization Bearer 1111
  • Adding the parameter token in the call.
http://[host]/webhook/notification?token=1111

7.2. Possible errors in HTTP calls

  • Error in the parameters

    StatusCode: 400

    {
      "data": "page",
      "message": "Must be number and required",
      "status": 400
    }
  • Error in the authorization

    StatusCode: 401

    {
      "data": "Token not valid",
      "message": "Unauthenticated, token not valid",
      "status": 401
    }
  • Error don´t exist the ID

    StatusCode: 404

    {
      "data": "",
      "message": "User id not found",
      "status": 404
    }
  • Error in the database

    StatusCode: 500

    {
      "data": "ECONNREFUSED",
      "message": "Error to connect BDD",
      "status": 500
    }

7.3. Data dictionary

status

Notification status. Shows the life cicle of a notification.

Tipo: string

Value Description
"sent" The message was sent to a user, but the user didn´t read it
"read" The user has read the message
"deleted" The user has deleted the notification

inbox

Specify the channel which the notification will be sent.

Type: string

Value Description
"inbox_only" The message can be consulted in the mailbox, but won´t be sent a notification.
"inbox_and_push" A notification will be sent and can be consulted in the mailbox.
"push_only" Only will be sent the notification. Is useful to avoid duplicate messages in the mailbox.

osName

Operating sistem name.

Type: string

Value Description
"Android" To appPush. Indentify a Android device (smartphone or tablet)
"iOS" To appPush. Indentify iOS user (iPod, iPad or iPhone)
"Firefox" To webPush. Indentify a Firefox browser
"Safari" To webPush. Indentify a Safari browser
"Chrome" To webPush. Indentify a Chrome browser

osVersion

Operating sistem version.

Type: string

lang

Language of the browser to webPush. OS language to appPush.

Type: string Format: ISO 639 Example: "es-ES"

allDevices

Specify if will be sent a notification to all user devices or only to one.

Type: boolean

Value Description
true Notification will be sent to all user devices
false Notification will be sent only to the last user device registered

message

This object represents a message.

Nombre Tipo Descripción
id number message ID
title string message title
description string Message body
uri string target URL or custom parameters
icon string Small icon URL. If null, the app logo should be used as default
wallpaper_thumb string Big picture URL. If null, no picture is attached
text string Left button label
url1 string Left button URL
button string Right button label
url2 string Right button URL
scheduled_at string This is the send date for scheduled campaigns
ctid string Message category ID