Send Push Notification V2

Definition

Method: POST

Endpoint: https://api.gravitec.net/api/v2/push.json

Headers: Content-Type: application/json

Request body:

{
 "send_date": "now",
 "message": "Push message text",
 "ttl": 3600,
 "chrome": {
   "header": "CHROME TITLE",
   "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
   "redirect_url": "http://yoursite.com"
 },
 "audience": {
   "all": 1
 }
}
Arguments

send_date

Optional

default: "now"

type: String or Int

Date and time, when you want your push to be sent. For delayed push, you must set the desired date and time, which have to be in the future and for immediate sending set it to “now”.

NOTE: Time must be in UNIX_TIME format, which is essentially the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, minus the number of leap seconds that have taken place since then

Example:

"send_date": "now"   - immediate sending
"send_date": 1509058800 – send push at 2017.Oct.26 23:00:00

message

Required

type: String

Text, which will be displayed as push message text (pic. 2).

NOTE: Maximum length of the message is 240 symbols.

Example:

"send_date": "now"   - immediate sending
"send_date": 1509058800 – send push at 2017.Oct.26 23:00:00
doc-18.png

pic. 2

ttl

Optional

default: 3600

type: Int

The number of seconds that a message may be stored if the user is not immediately available.

NOTE: The number must be in between 0 and 2 419 200

NOTE: Keep in mind that a TTL value of 0 means messages that can't be delivered immediately to users are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages

Example:

"ttl ": 14400   - time-to-live is set to 4 hours

chrome

Required

The “Chrome” section is required some arguments within the section are not required.

 

header

Optional

default: Title

type: String

Title or header of the message.

NOTE: Max length of header is 65 symbols

Example:

"header": "Just another header"

Chrome:

doc-19.png

Firefox:

doc-20.png

icon

Required

type: String

URL of the notification's icon. Sets the notification icon to specified image URL. Image must be at least 80x80 pixels and with 1:1 ratio. The pictures without that ratio will be resized and probably distorted.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL and with ending .jpg, .jpeg or .png, otherwise the error will be fired.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Providing “icon": “” will set the icon to default site icon, which can be set in the Site Settings page.

Example:

"icon": "https://push.gravitec.net/img/gravitecBig.jpg
doc-21.png

redirect_url

Required

type: String

URL, which will be opened in user’s browser if user clicks on the notification.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL, otherwise the error will be fired.

Example:

"redirect_url": "http://yoursite.com/news"

audience

Required

The “Audience” section is required. The section must contain only one of these variables: alltokensaliases or tags.

 

all

Optional

type: Int

Setting this parameter in any value means that message will be send to all subscribers.

NOTE: Any JSON correct value is accepted, but we would recommend you to set it in 1, as mentioned in example.

Example (of the whole Audience section):

"audience": {
  "all": 1
}

tokens

Optional

type: Array

Specifying a list of subscribers’ IDs in this parameter means that message will be send exactly to the list of subscribers specified. You can get subscriber’s ID by using getSubscription function from our Web SDK API

NOTE: Array size is limited to 100 IDs.

Example:

"tokens": ["dec301908b9ba...8df85e57a58e40f96f", "523f4c2068674f1fe...2ba25cdc250a2a41"]

aliases

Optional

type: Array

Specifying a list of aliases means that message will be sent exactly to the list of subscribers who are associated with aliases provided in the list. You can set an alias by using setAlias function from our Web SDK API.

Example:

"aliases": ["own_id_device_1", "own_id_device_2", "own_id_device_3"]

tags

Optional

type: Array

Specifying a list of tags means that message will be send exactly to the list of subscribers who were tagged with tags provided in the list. You can tag your subscribers by using addTag or setTags function from our Web SDK API

Example:

"tags": ["tag1", "tag2", "tag3"]
Examples

Send push to all followers of site

curl -X POST \
-H "Content-Type: application/json" \
-u "APP_KEY:APP_SECRET" \
--data '{
  "message": "Push message",
  "chrome": {
    header": "title message",
    icon": "http://example.com/icon.png",
    redirect_url": "http://yoursite.com/new"
  },
  "audience": {
    "all": 1
  }
}' \
https://api.gravitec.net/api/v2/push.json

Send push to followers of site who were tagged with tag1 and tag2

curl -X POST \
-H "Content-Type: application/json" \
-u "APP_KEY:APP_SECRET" \
--data '{
  "message": "Push message",
  "chrome": {
    "header": "title message",
    "icon": "http://example.com/icon.png",
    "redirect_url": "http://yoursite.com/new"
  },
  "audience": {
    "tags": ["tag1", "tag2"]
  }
}' \
https://api.gravitec.net/api/v2/push.json
Responses (Results and Errors)

200 OK - Standard response for successful HTTP requests

Request

{
  "send_date":"now",
  "message":"Push message text",
  "ttl":3600,
  "chrome": {
    "header":"CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "all": 1
  }
}

Response

{
  "id": "1578964386674900992",
  "status": "completed",
  "message": "Push message text",
  "title": "CHROME TITLE",
  "platforms": "chrome",
  "ttl": "3600",
  "date": "Tue Sep 19 13:43:02 EEST 2017"
}

403 FORBIDDEN - authorization failed

Request

POST /api/v2/push.json HTTP/1.1

Host: api.gravitec.net

Content-Type: application/json

Authorization: Basic NTQ1OTA1OTA1OTQwNTk0MGdwZ2tqOmVyZmdkZmdkZmdkZmc=

Cache-Control: no-cache

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "tags": ["tag1", "tag2", "tag3"]
  }
}

Response

{
  "status": "incomplete by bad auth",
  "error_message": "There is no web site with appKey: 5459059059405940gpgkj"
}

404 NOT FOUND - missed required parameter

Request

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  }
}

Response

{
 "status": "incomplete by missed req param(s)",
 "error_message": "Audience required"
}

412 PRECONDITION_FAILED - bad message

Request

{
  "message": "Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test Test message$Test message$Test message$Test message$Test message$Test test",
  "chrome": {
   "header": "Test it out!",
   "icon": "https://cdn.gravitec.net/img/logo_footer.png",
   "redirect_url": "https://gravitec.net/"
   "all": 1
  },
  "send_date": "now"
}

Response

{
 "status": "incomplete by wrong param(s)",
 "error_message": "message max length is 1000 symbol"
}

417 EXPECTATION_FAILED - wrong parameter

Request

{
  "send_date": "2017-09-20",
  "message": "Push message text",
  "ttl":3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "all": 1
  }
}

Response

{
  "status": "incomplete by wrong param(s)",
  "error_message": "date must be timestamp or now"
}

424 FAILED_DEPENDENCY - bad audience

Request

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header":"CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "tags": ["tag1", "tag2", "tag3"]
  }
}

Response

{
  "status": "incomplete by bad audience",
  "error_message": "tags list is invalid"
}