Send Push Notification V3
Resources
Definition
Method: POST
Endpoint: https://uapi.gravitec.net/api/v3/alias
Request parameters:
- regId - subscriber’s token [Required, 1-255 symbols string]
- name - desired alias name [Required, 1-255 symbols string]
NOTE: All request parameters names and values are case-sensitive.
Request URL example:
https://uapi.gravitec.net/api/v3/alias?regId=someregid&name=newalias
200 OK
The alias was successfully added
400 Required String parameter "name" is not present
"name" parameter was not provided in request
400 Required String parameter "regId" is not present
"regId" parameter was not provided in request
422 Unprocessable Entity
No follower with regID provided was found
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "There is no follower with this regId!"
}
422 Unprocessable Entity
Provided alias name length was more than 255 symbols
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "Max alias length is 255!"
}
Definition
Method: POST
Endpoint: https://uapi.gravitec.net/api/v3/tag
Request parameters:
- regId - subscriber’s token [Required, 1-255 symbols string]
- name - desired tag name [Required, 1-255 symbols string]
NOTE: All request parameters names and values are case-sensitive.
NOTE: Tags saving method behaves with case sensitive values like:
First tag will be saved in exact case it provided, if another tag, which in case-insensitive comparison is the same one, provided, it will not be added as a new tag – the system considers it as the same as previous.
Request URL example:
https://uapi.gravitec.net/api/v3/tag?regId=someregid&name=tagname
200 OK
Tag was successfully added
400 Required String parameter "name" is not present
"name" parameter was not provided in request
400 Required String parameter "regId" is not present
"regId" parameter was not provided in request
422 Unprocessable Entity
No follower with regID provided was found
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "There is no follower with this regId!"
}
422 Unprocessable Entity
Provided tag name length was more than 255 symbols
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "Max alias length is 255!"
}
Definition
Method: DELETE
Endpoint: https://uapi.gravitec.net/api/v3/tag
Request parameters:
- regId - subscriber’s token [Required, 1-255 symbols string]
- name - desired tag name [Required, 1-255 symbols string]
NOTE: All request parameters names and values are case-sensitive.
Request URL example:
https://uapi.gravitec.net/api/v3/tag?regId=someregid&name=tagname
200 OK
Tag was successfully deleted
400 Required String parameter "name" is not present
"name" parameter was not provided in request
400 Required String parameter "regId" is not present
"regId" parameter was not provided in request
422 Unprocessable Entity
No follower with regID provided was found
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "There is no follower with this regId!"
}
422 Unprocessable Entity
Provided tag was not found for the subscriber with provided regId.
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "The follower doesn't have this tag!"
}
422 Unprocessable Entity
Provided tag name length was more than 255 symbols
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "Max alias length is 255!"
}
Definition
Method: GET
Endpoint: https://uapi.gravitec.net/api/v3/alias
Request parameters:
- regId - subscriber’s token [Required, 1-255 symbols string]
NOTE: All request parameters names and values are case-sensitive.
Request URL example:
https://uapi.gravitec.net/api/v3/alias?regId=someregid
regIdExists [boolean]
- Is "true" if provided in request regId is an actual subscriber’s token
- Set in "false" if provided in request regId does not exists as actual subscriber’s token
aliasExists [boolean]
- Is "true" if provided in request regId is an actual subscriber’s token and there is an active alias for that token
- Is "false" if provided in request regId is an actual subscriber’s token and there is no active alias for that regID
- Does not present in response if regIdExists is "false"
isActiveFollower [boolean]
- Is "true" if provided in request regId is a token of an active subscriber
- Is "false" if provided in request regId is a token of an inactive subscriber
- Does not present in response if regIdExists is "false"
alias [string]
- Is an actual and active alias for provided in request regId
- Does not present in response if regIdExists is "false"
200 - OK
400 - Required String parameter regId is not present
RegId property was not in request
Request:
https://uapi.gravitec.net/api/v3/alias?regId=
Response code:
400 - Required String parameter regId is not present
RegId exists as actual subscriber’s token
Request:
https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g
Response code:
200 - OK
Response body:
{
"regIdExists": "false"
}
There is no active alias for regID
Request:
https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g
Response code:
200 - OK
Response body:
{
"regIdExists": "true",
"aliasExists": "false",
"isActiveFollower": "true"
}
There is an active alias for regID and subscriber is not in an active state
Request:
https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g
Response code:
200 - OK
Response body:
{
"regIdExists": "true",
"aliasExists": "true",
"isActiveFollower": "false",
"alias": "alias1"
}
There is an active alias for regID and subscriber is in an active state
Request:
https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g
Response code:
200 - OK
Response body:
{
"regIdExists": "true",
"aliasExists": "true",
"isActiveFollower": "true",
"alias": "alias1"
}
Definition
Method: POST
Endpoint: https://uapi.gravitec.net/api/v3/push
Headers: Content-Type: application/json
Request body properties:
{
"send_date": "",
"ttl": "",
"push_tag":"",
"display_time": "",
"is_transactional": "",
"segments": [""],
"payload": {
"message": "",
"title": "",
"icon": "",
"image": "",
"redirect_url": "",
"buttons": [{
"title": "",
"url": ""
}]
},
"audience": {
"tokens": [""],
"aliases": [""],
"tags": [""],
"tags_segment": [{""}]
}
}
Properties list
send_date
Optional
default: ""
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 milliseconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, minus the number of leap milliseconds that have taken place since then
Example:
"send_date": "" - immediate sending
"send_date": 1509058800000 – send push at 2017.Oct.26 23:00:00
ttl
Optional
default: 28800
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 ": 28800 - time-to-live is set to 8 hours
push_tag
Optional
type: String
Tags push campaign so that a comparative analysis among such tags may be available.
NOTE: A tag's length must be between 1 and 100 characters
Example:
"push_tag": "news" - tags a campaign with "news" tag
display_time
Optional
default: 60
type: Int
The number of seconds that a message will be displayed on participant’s screen
NOTE: If set in 0 – the message will be displayed until user clicks on it
NOTE: Maximum time is 2419200
is_transactional
Optional
default: false
type: boolean
Marks a push message as Transactional, thus the message will not be displayed in the main campaign history section of the web application (https://push.gravitec.net). Use this if you send a great deal of small messages, which are by itself contains transactional data like personal notifications for your users, reminders, etc.
NOTE: If omitted, false" value will be set for a push message
segments
Optional
type: array
Send push campaign to a segment.
NOTE 1: You can not include both the segments and the audience section in request.
NOTE 2: You can only send to one segment. In case more than one segment included the system will not send the campaign
NOTE 3: If segment has been deleted or does not exists the system will not send the campaign
payload
Required
The "Payload" section is required, whereas some arguments within the section are not required.
message
Required
type: String
Text, which will be displayed as push message text
NOTE: Maximum length of the message is 1000 symbols.
Example:
"message": "Push message text"
title
Optional
default: Title
type: String
Title or header of the message.
NOTE: Max length of title is 1000 symbols.
Example:
"header ": "Just another header"Chrome:
Firefox:
icon
Required
type: String
URL of notification's icon. Sets the notification icon to specified image URL. Image must be at least 80x80 pixels and with 1:1 ratio. Pictures without that ratio will be resized with its aspect ratio and put on a white square.
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: Not specifying an "icon": will set the default icon of the site, which can be set on the page "Site Settings".
Example:
"icon": "https://push.gravitec.net/img/gravitecBig.jpg"1:1 aspect ratio and more than 80x80 on X and Y sides:
1:1.2 aspect ratio and more than 80 on Y side:
1.2:1 aspect ratio and more than 80 on X side:
Less than 80x80 on X and Y sides:
image
Optional
type: String
URL of big picture to display below the notification main body. For the best results provided image must be with 1.5:1 sides ratio and size at least 360x240 pixels.
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: Pictures, which are not in 1.5:1 ratio or less then 360x240 and will be resized according to their aspect ratio and put on top of a white image of 360x240 px
Different image processing examples:
1.5:1 aspect ratio and more or equal than 360x240 on X and Y sides accordingly:
1:1.2 aspect ratio and more than 240 on Y side:
1.2:1 aspect ratio and more than 360 on X side:
Less than 360x240 on X and Y sides:
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"
Optional
Specify in this array one or two action buttons, which will be displayed below the notification main body:
Example:
title
Required
type: String
Provide appropriate title for the button.
NOTE: Max length of title is 48 symbols
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 (rfc3986)
audience
Optional
The "Audience" section is optional.
NOTE: If omitted, the system shall send push message to all subscribers.
NOTE: If set - the section must contain only one of these variables (in other case, error will be fired):
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"]
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"]
Optional
type: Array
In order to send campaign to a part of your audience, which is an intersection two or more segments of tagged subscribers, you can provide such a condition by using logic operators AND, AND_NOT, OR, OR_NOT followed by a tag. Such conditions should be put in array of json elements.
AND – include all followers tagged by the tag followed with AND logical operator
AND_NOT - include all followers who hasn’t been tagged by the tag followed with AND logical operator
OR - include all followers tagged by the tag followed with OR logical operator
OR_NOT - include all followers who hasn’t been tagged by the tag followed with OR logical operator
NOTE: Tags array must contain not less that 1 and not more than 256 elements
NOTE: Tag name must contain not less that 1 and not more than 255 symbols
NOTE: You must provide logical operator only from the list: AND, AND_NOT, OR, OR_NOT
NOTE: Tag name provided must be case-insensitive unique among the elements in the array (Example: CARS and cars are not unique)
NOTE: It is not allowed to use both tags_segment and tags directive simultaneously
NOTE: You must provide tags that exists in the system
Example:
The system shall send the campaign to all followers with tag tag1 and without tag2:
"tags_segment": [{
"association": "AND",
"name": "tag1"
}, {
"association": "AND_NOT",
"name": "tag2"
}]The system shall send the campaign to all followers without tag tag1 or with tag2:
"tags_segment": [{
"association": "AND_NOT",
"name": "tag1"
},{
"association": "OR",
"name": "tag2"
}]
200 OK - Standard response for successful HTTP requests
Request
{
"payload": {
"message": " Test massage",
"title": "Test message",
"redirect_url": "https://gravitec.net"
}
}Response
{
"id": "1590394828308348928",
"send_date": "1516718700678",
"ttl": 86400,
"display_time": 60,
"payload": {
"title": "Test message"
}
}
403 FORBIDDEN - authorization failed
Request
POST /api/v3/push HTTP/1.1
Host: api.gravitec.net
Content-Type: application/json
Authorization: Basic Z2hqZ2hqZ2g6aGdtamdoag==
Cache-Control: no-cache
{
"payload": {
"message": "Test massage",
"title": "Test message",
"redirect_url": "https://gravitec.net"
}
}Response
{
"status": "incomplete by bad auth",
"error_message": "There is no web site with appKey: 5459059059405940gpgkj"
}Definition
Method: GET
Endpoint: https://uapi.gravitec.net/api/v3/messages/
Request parameters:
- campaignID - Campaign ID [Required, Id from “Send Push Notification V3]
NOTE: All request parameters names and values are case-sensitive.
Request URL example:
https://uapi.gravitec.net/api/v3/messages/1603861504654835713
200 OK
Request successfully received
Body:
{
"status": "SENT",
"send": 2,
"received": 2,
"clicked": 1,
"closed": 1
}
400 Required parameter "campaignID" is not present
"campaignID" parameter was not provided in request
422 Unprocessable Entity
No Push Campaign with campaignID provided was found
Body:
{
"httpStatus": "UNPROCESSABLE_ENTITY",
"error": "Incomplete by wrong param(s)!",
"errorDescription": "There is no message with this id!"
}