Contents
|
Summary
Employs QuickBlox servers’ power to send thousands of technical and marketing messages to your users. Four channels are supported:
- Push Notifications – sends iOS, Android, WP, BlackBerry pushes. This is being used for technical notifications, reminders and marketing messages. Also used as IM, enabling you or your users to send direct messages to other users (even if they are offline and not using the app). Can be integrated with other functions within the particular application.
- Emails – sending e-mails to your users. This is being used for users registration, password reminders, marketing newsletter etc
Features
- Messages Queue – messages can be either sent instantly or assigned a specific time/date and pushed into a Message Queue which allows to send delayed and recurring messages such as reminders, planned marketing announcements or any planned notifications for the better engagement of the users.
- Recurring notifications – set up a time interval and the message will be repeated automatically by the server
- User tags - a feature powered by integration with our Users module, allowing to specify a group of users the message shall be sent to
- Media attachments (send rich media attachments such as video, audio and location data, including video streaming, powered by our Content module). Not available for emails.
Need to know information
Before start with Messages module please read the following:
Push Notifications API
Push Notifications module provides powerful and simple to use API to subscribe your user base to push & email notifications and send them.
Typical use сases
Send Push Notification from Admin panel
To send message from Admin panel you need to do next steps:
Client side (subscribe to Push Notifications channel):
Admin panel:
- iOS - upload сertificates; Android - register your Android application, then you need to get the tokens for your google account.
- Send message using Messages module
Send Push Notification from Application
To send message from client side you need to do next steps:
Client side (subscribe to Push Notifications channel):
Client side (send Push Notifications):
- Create an event - then push notification will be send automatically
Admin panel:
- iOS - upload сertificates; Android - register your Android application, then you need to get the tokens for your google account.
Requests and Responses
URL | HTTP Verb | Supported formats | Action Description | Success HTTP Status Code |
---|---|---|---|---|
/subscriptions | POST |
|
Create subscriptions (subscribes) | 201 |
/subscriptions | GET |
|
Retrieve subscriptions | 200 |
/subscriptions/:id | DELETE |
|
Remove subscription (unsubscribes) | 200 |
/events | POST |
|
Create event | 201 |
/events | GET |
|
Get events | 200 |
/events/{event_id} | PUT |
|
Edit event | 200 |
/events/{event_id} | DELETE |
|
Delete event | 200 |
/events/{event_id} | GET |
|
Retrieve event by ID | 200 |
Create subscription (subscribes)
Create device based subscriptions.
Parameters
Param | Required | Type | Value Example | Description |
---|---|---|---|---|
notification_channel | Yes | String | apns | Declare which notification channels could be used to notify user about events. Allowed values: apns, apns_voip, gcm, mpns, bbps, email. |
push_token[environment] | Yes | Enum | development | Determine application mode. It allows conveniently separate development and production modes. Allowed values: development, production |
push_token[bundle_identifier] | No | String | com.quickblox.supresample | A unique identifier for client's application. In iOS, this is the Bundle Identifier. In Android - package id. |
push_token [client_identification_sequence] | Yes | String | aa557232bc237245ba67686.. | Identifies client device in 3-rd party service like APNS, GCM/FCM, BBPS or MPNS. Initially retrieved from 3-rd service and should be send to QuickBlox to let it send push notifications to the client. |
device[platform] | Yes | String | ios | Platform of device, which is the source of application running. Allowed values: ios, android, windows_phone, blackberry. |
device[udid] | Yes | String | 2343af3433aa3a4fsv | UDID (Unique Device identifier) of device, which is the source of application running. This must be anything sequence which uniquely identify particular device. This is needed to support schema: 1 User - Multiple devices. |
Request
curl -X POST \ -H "Content-Type: application/json" \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: 17f6a337b0656c9c7e983f9705d79562fc694c0e" \ -d '{"notification_channels": "apns", "push_token": {"environment": "development", "client_identification_sequence": "aa557232bc237245ba67686aa557232bc237245ba67686", "bundle_identifier": "com.quickblox.myawesomeapp"}, "device": {"platform": "ios", "udid": "2343af3433aa3a4fsv"}}' \ https://api.quickblox.com/subscriptions.json
Response
[ { "subscription": { "id": 41, "notification_channel": { "name": "apns" }, "device": { "udid": "3429C429-4C34-5214-8E3C-803AC0CA79ED", "platform": { "name": "ios" } } } } ]
Retrieve subscriptions
Retrieve subscriptions for the device which is specified in the authorization token.
Request
curl -X GET \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: d85042b92eb651c6c4a68ad49a87b985a9ba50e2" \ https://api.quickblox.com/subscriptions.json
Response
[ { "subscription": { "id": 40, "notification_channel": { "name": "email" }, "device": { "udid": "3429C429-4C34-5214-8E3C-803AC0CA79ED", "platform": { "name": "ios" } } } }, { "subscription": { "id": 41, "notification_channel": { "name": "apns" }, "device": { "udid": "3429C429-4C34-5214-8E3C-803AC0CA79ED", "platform": { "name": "ios" } } } } ]
Remove subscription (unsubscribes)
Remove a subscription by the identifier
Request
curl -X DELETE \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: 0b06980edeca062ebed4f8d402449f84e88fcac4" \ https://api.quickblox.com/subscriptions/13.json
Response
Create event
Create notification event
Parameters
Param | Required | Type | Value Example | Description |
---|---|---|---|---|
event[notification_type] | Yes | Enum |
push |
Type of notification. |
event[push_type] | No | Enum |
apns |
Used only if notification_type == push, ignored in other cases
Allowed values: apns, apns_voip, gcm, mpns, bbps |
event[environment] | Yes | Enum |
development |
An environment of the notification.
|
event[event_type] | No | Enum |
one_shot |
Allowed values: one_shot, fixed_date, period_date fixed_date - a one-time event, which occurs at a specified 'date' (the value is valid only if the 'date' is given) period_date - reusable event that occurs within a given 'period' from the initial 'date' (the value is only valid if the 'period' specified) fixed_date, if 'date' is specified period_date, if 'period' is specified one_shot, if 'date' is not specified |
event[message] | Yes | string |
event[push_type] not present - should be Base64 encoded text. event[push_type] specified - should be formatted as described in QuickBlox Push Notifications Formats
Base64 encoded text | |
event[user][ids] | Optional* | string | 11,25,356,489 |
Notification's recipients - should contain a string of users' ids divided by commas. |
event[external_user][ids] | Optional* | string | 15,24,367,49 |
Notification's recipients - should contain a string of external users' ids divided by commas. |
event[user][tags][any] | Optional* | string | good,bad,ugly |
Notification's recipients - should contain a string of tags divided by commas. Recipients (users) must have at least one tag that specified in the list. |
event[user][tags][all] | Optional* | string | tag1,tag2,tag3 |
Notification's recipients - should contain a string of tags divided by commas. Recipients (users) must exactly have only all tags that specified in list |
event[user][tags][exclude] | Optional* | string | tag1,tag2,tag3 |
Notification's recipients - should contain a string of tags divided by commas. Recipients (users) mustn't have tags that specified in list |
event[date] |
|
Timestamp, in seconds | 11241342343 | The date of the event to send on. If the 'event type'=='fixed_date', the date can not be in the past. |
event[end_date] |
|
Timestamp, in seconds | 31241342343 | Date of completion of the event. Can't be less than the 'date'. |
event[period] |
|
Timestamp, in seconds | 86400 | The period of the event in seconds. Possible values:
|
event[name] |
No |
String | my event | The name of the event. Service information. Only for your own usage. |
* Only one of these parameters is required
Request
curl -X POST \ -H "Content-Type: application/json" \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: ee7db1a695eeb42830498720a7e9d56682472fbd" \ -d '{"event": {"notification_type": "push", "environment": "production", "user": { "ids": "1326"}, "message": "payload=eyJhcHMiOnsic291bmQiOiJkZWZhdWx0IiwiYWxlcnQiOiJZb3UgaGF2ZSBqdXN0IHJlY2VpdmVkIGEgbmV3IG1lc3NhZ2UgZnJvbSBZdWxpYSBTeWRvcmVua28uIn0sIngiOnsiZGF0YSI6IntcInR5cGVcIjpcIm1lc3NhZ2VcIixcImZyb21fbmFtZVwiOlwiWXVsaWEgU3lkb3JlbmtvXCIsXCJmcm9tX2lkXCI6XCI4NTc1MTFcIixcImZyb21fZmFjZWJvb2tcIjpcIjEwMDAwMDM0OTA4MjYwM1wifSJ9fQ==", "push_type": "apns"}}' \ https://api.quickblox.com/events.json
Response
[ "event": { "active": true, "created_at": "2012-05-07T12:55:15Z", "date": null, "end_date": null, "event_type": "one_shot", "id": 592, "message": "payload=eyJhcHMiOnsiYWxlcnQiOiJIZWxsbywgV29ybGQhIiwiYmFkZ2UiOjc3Nywic291bmQiOiJkZWZhdWx0In19", "name": null, "occured_count": 0, "period": null, "updated_at": "2012-05-07T12:55:15Z", "user_id": 1326, "notification_channel": { "name": "apns" }, "subscribers_selector": { "environment": "production", "user_ids":[ 1,2,3,4,5 ] } } ]
Get events
Get all events which were created by a user specified in the authorization token
Request
curl -X GET \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: b9c808a7a9d44ca5804f38c43f62d9d0ef8c8020" \ https://api.quickblox.com/events.json
Response
{ "current_page": 1, "per_page": 10, "total_entries": 1, "items": [ { "event": { "active": false, "created_at": "2012-03-21T09:49:03Z", "date": null, "end_date": null, "event_type": "one_shot", "id": 290, "message": "mpns=PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0ndXRmLTgnPz48d3A6Tm90aWZpY2F0aW9uIHhtbG5zOndwPSdXUE5vdGlmaWNhdGlvbic%2BPHdwOlRvYXN0Pjx3cDpUZXh0MT5JbmNvbWluZyBNZXNzYWdlPC93cDpUZXh0MT48d3A6VGV4dDI%2BdGVzdCBtZXNzYWdlPC93cDpUZXh0Mj48d3A6UGFyYW0%2BL3F1aWNrYmxveC54YW1sPC93cDpQYXJhbT48L3dwOlRvYXN0Pjwvd3A6Tm90aWZpY2F0aW9uPg==%26headers=Q29udGVudC1UeXBlLHRleHQveG1sLENvbnRlbnQtTGVuZ3RoLDIyNiwnWC1Ob3RpZmljYXRpb25DbGFzcywyLFgtV2luZG93c1Bob25lLVRhcmdldCx0b2FzdA==", "name": null, "occured_count": 1, "period": null, "updated_at": "2012-03-21T09:49:11Z", "user_id": 3, "notification_channel": { "name": "mpns" }, "subscribers_selector": { "environment": "production", "tags_query": { "all":"man" }, "user_ids":[ ... ] } } } ] }
Edit event
Edit event
Parameters
Param | Required | Type | Value Example | Description |
---|---|---|---|---|
event[active] | Optional | Bool | true | Marks event as active/inactive |
event[message] | Optional | Base64 |
payload=eyJhcHMiOnsiYWxlcnQi OiJkZnNkZnNzZGYiLCJiYWRnZSI 6MSwic291bmQiOiJkZWZhdWx0In19 |
|
event[date] |
Yes, and the possibility of a parameter depends on the 'event_type' value |
Timestamp | 86400 | The date of the event. If the 'event type'=='fixed_date', the date can not be in the past. |
event[period] |
Yes, and the possibility of a parameter depends on the 'event_type' value |
Timestamp | 86400 | The period of the event in seconds. Possible values:
|
event[name] |
Optional |
String | my event | The name of the event |
Request
curl -X PUT \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: d85042b92eb651c6c4a68ad49a87b985a9ba50e2" \ -d '{"event": {"date": "1332327600", "period": "1332414000", "name": "My%20New%20Event"}}' \ https://api.quickblox.com/events/394.json
Response
{ "event": { "active": false, "created_at": "2012-03-22T13:25:06Z", "date": 1332327600, "end_date": null, "event_type": "one_shot", "id": 394, "message": "payload=eyJhcHMiOnsiYWxlcnQiOiJIZWxsbywgV29ybGQhIiwiYmFkZ2UiOjc3Nywic291bmQiOiJkZWZhdWx0In19", "name": "My New Event", "occured_count": 1, "period": 1332414000, "updated_at": "2012-03-22T16:16:52Z", "user_id": 89, "notification_channel": { "name": "apns" }, "subscribers_selector": { "environment": "development" } } }
Delete event
Delete event.
Request
curl -X DELETE \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: 61be07f7fd9071e0eab36ec51cdd68d5e97570c7" \ https://api.quickblox.com/events/320.json
Response
Retrieve event by ID
Retrieve event by the ID. The event specified in the request should belong to the application for which the authorization token has been received.
Request
curl -X GET \ -H "QuickBlox-REST-API-Version: 0.1.0" \ -H "QB-Token: d85042b92eb651c6c4a68ad49a87b985a9ba50e2" \ https://api.quickblox.com/events/394.json
Response
{ "event": { "active": false, "created_at": "2012-03-22T13:25:06Z", "date": 1332327600, "end_date": null, "event_type": "one_shot", "id": 394, "message": "payload=eyJhcHMiOnsiYWxlcnQiOiJIZWxsbywgV29ybGQhIiwiYmFkZ2UiOjc3Nywic291bmQiOiJkZWZhdWx0In19", "name": "My New Event", "occured_count": 1, "period": 1332414000, "updated_at": "2012-03-22T16:16:52Z", "user_id": 89, "notification_channel": { "name": "apns" }, "subscribers_selector": { "environment": "development" } } }
Push Notification Formats
QuickBlox provides 2 type of push notifications you can send:
- Platform based push notification - will be delivered to specified platform only, for example, iOS or Android only.
- Universal push notifications - will be delivered to all possible devices/platforms for specified users.
Platform based push notification
Platform based push notification will be delivered to specified platform only. To specify platform use event[push_type] parameter when create event.
With platform based push notification you can use all specified features of particular platform, no restrictions.
General requirements
Message format is a key=value string. Where key is raw text and value - BASE64 encoded and CGI escaped. Each pair should be separated by &
Example: key1=c29tZXZhbHVlMQ==&key2=YW5vdGhlcnZhbHVlMg==&key3=dGhpcmRleGFtcGxl
Important! & should be escaped by %26
iOS
To meet Apple payload requirements.
Example:
JSON payload:
{ "aps" : { "alert" : "You got your emails.", "badge" : 9, "sound" : "bingbong.aiff" }, "acme1" : "bar", "acme2" : 42 }
Base64 Encoded data:
ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogIllvdSBnb3QgeW91ciBlbWFpbHMuIiwNCiAgICAgICAgImJhZ
GdlIiA6IDksDQogICAgICAgICJzb3VuZCIgOiAiYmluZ2JvbmcuYWlmZiINCiAgICB9LA0KICAgICJhY21lMSIgOiAiYmFyIiwNCiAg
ICAiYWNtZTIiIDogNDINCn0=
Final message (for iOS pushes you should add payload= before message):
event[message]=payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogIllvdSBnb3QgeW91ciBlbWFpbHMuIiwNCiAgICAgICAg
ImJhZGdlIiA6IDksDQogICAgICAgICJzb3VuZCIgOiAiYmluZ2JvbmcuYWlmZiINCiAgICB9LA0KICAgICJhY21lMSIgOiAiYmFyIiwNCi
AgICAiYWNtZTIiIDogNDINCn0=
Android
To meet Google GCM/FCM requirements.
Message format is a data.key1=value1&...&data.keyN=valueN
Values should be CGI-escaped before Base64 encoding.
Required field collapse_key is added automatically before sending and contains value "event<ID>"
data.message key is required and should be 1st.
Example:
Plain message:
data.message=I love M&M's! Especially red one!
CGI-escaped:
data.message=I+love+M%26M%27s%21+Especially+red+one%21
Base64-encoded:
data.message=SStsb3ZlK00lMjZNJTI3cyUyMStFc3BlY2lhbGx5K3JlZCtvbmUlMjE=
Final message:
event[message]=data.message=SStsb3ZlK00lMjZNJTI3cyUyMStFc3BlY2lhbGx5K3JlZCtvbmUlMjE=
Windows Phone
Meets Microsoft requirements. See MSDN portal for more detailed information.
Example:
Body:
<?xml version='1.0' encoding='utf-8'?> <wp:Notification xmlns:wp='WPNotification'> <wp:Toast> <wp:Text1>Incoming Message</wp:Text1> <wp:Text2>ping</wp:Text2> <wp:Param>/quickblox.xaml</wp:Param> </wp:Toast> </wp:Notification>
Headers should be written in a string as key,value separated by comas.
Headers:
Content-Type,text/xml,Content-Length,226,X-NotificationClass,2,X-WindowsPhone-Target,toast
Base64 Encoded data:
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0ndXRmLTgnPz48d3A6Tm90aWZpY2F0aW9uIHhtbG5zOndwPSdXUE5vdGlm
aWNhdGlvbic=PHdwOlRvYXN0Pjx3cDpUZXh0MT5JbmNvbWluZyBNZXNzYWdlPC93cDpUZXh0MT48d3A6VGV4dDI=cGluZzwvd3A6VGV
4dDI=PHdwOlBhcmFtPi9xdWlja2Jsb3gueGFtbDwvd3A6UGFyYW0=PC93cDpUb2FzdD48L3dwOk5vdGlmaWNhdGlvbj4=&headers=Q
29udGVudC1UeXBlLHRleHQveG1sLENvbnRlbnQtTGVuZ3RoLDIxOCxYLU5vdGlmaWNhdGlvbkNsYXNzLDIsWC1XaW5kb3dzUGhvbmUtVGFyZ
2V0LHRvYXN0
Final message (for WP pushes you should add mpns= before message):
event[message]=mpns=PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0ndXRmLTgnPz48d3A6Tm90aWZpY2F0aW9uIHhtbG5zOndwPSdXUE5vdGlm
aWNhdGlvbic=PHdwOlRvYXN0Pjx3cDpUZXh0MT5JbmNvbWluZyBNZXNzYWdlPC93cDpUZXh0MT48d3A6VGV4dDI=cGluZzwvd3A6VGV
4dDI=PHdwOlBhcmFtPi9xdWlja2Jsb3gueGFtbDwvd3A6UGFyYW0=PC93cDpUb2FzdD48L3dwOk5vdGlmaWNhdGlvbj4=&headers=Q
29udGVudC1UeXBlLHRleHQveG1sLENvbnRlbnQtTGVuZ3RoLDIxOCxYLU5vdGlmaWNhdGlvbkNsYXNzLDIsWC1XaW5kb3dzUGhvbmUtVGFyZ
2V0LHRvYXN0
Blackberry
Meets Blackberry requirements. See Blackberry developer portal for more detailed information.
Example
Base64 Encoded data:
PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0ndXRmLTgnPz48d3A6Tm90aWZpY2F0aW9uIHhtbG5zOndwPSdXUE5vdGlm
aWNhdGlvbic=PHdwOlRvYXN0Pjx3cDpUZXh0M5JbmNvbWluZyBNZXNzYWdlPC93cDpZXh0MT48d3A6VGV4dDI=cGluZzwvd3A6VGV
4dDI=PHdwOlBhcmFtPi9xdWlja2Jsb3gueGFtbDwvdA6UGFyYW0=PC93cDpUb2FzdD48L3dwOk5vdGlmaWNhdGlvbj4=&headers=Q
29udGVudC1UeXBlLHRleHQveG1sLENvbnRlbnQtTGVuZ3RoLDIxOCxYLU5vdGlaWNhdGlvbkNsYXNzLDIsWC1XaW5kb3dzUGhvbmUtVGFyZ
2V0LHRvYXN0
Final message (for Blackberry pushes you should add bbps= before message):
event[message]=bbps=PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0ndXRmLTgnPz48d3A6Tm90aWZpY2F0aW9uIHhtbG5zOndwPSdXUE5vdGlm
aWNhdGlvbic=PHdwOlRvYXN0Pjx3cDpUZX0MT5JbmNvbWluZyBNZXNzYWdlPC93cDpUZXh0MT48d3A6VGVdDI=cGluZzwvd3A6VGV
4dDI=PHdwOlBhcmFtPi9xdWlja2Jsb3gueGFtbDwvd3A6UGFyYW0=PC93cDpUb2FzdD48L3dwO5vdGlmaWNhdGlvbj4=&headers=Q
29udGVudC1UeXBlLHRleHQveGsLENvbnRlbnQtTGVuZ3RoLDIxOCxYLU5vdGlmaWNhdGlvbkNsYXNzLDIsWC1XaW5kb3dzUGhvbmUtVGFyZ
2V0LHRvYXN0
Universal Push Notifications
Universal push notifications will be delivered to all possible devices/platforms for specified users. To send Universal push notifications just omit event[push_type] parameter when create event.
Send simple text
If you would like to send just text push message (without any parameters):
Example:
Plain message:
I love M&M's! Especially red one!
Base64-encoded:
SSBsb3ZlIE0mTSdzISBFc3BlY2lhbGx5IHJlZCBvbmUh
Final message:
event[message]=SSBsb3ZlIE0mTSdzISBFc3BlY2lhbGx5IHJlZCBvbmUh
Use custom parameters
With custom parameters you can achieve behaviour similar to platform based push notifications.
Note: custom parameters only available for iOS and Android platforms.
There are some standard parameters, which will be translated to particular platform parameters:
- message - push text. Will be translated to aps.alert.body for iOS and to data.message for Android
- ios_badge - will be translated to aps.badge for iOS. Ignored for Android
- ios_sound - will be translated to aps.sound for iOS. Ignored for Android
- ios_content_available=1 - will be translated to aps.content-available for iOS. Ignored for Android
- ios_mutable_content=1 - will be translated to aps.mutable-content for iOS. Ignored for Android
- ios_category - will be translated to aps.category for iOS. Ignored for Android
- ios_voip=1 - will initiate VoIP push notification for iOS if user has VoIP push subscription. Otherwise - iOS user will receive standart iOS push. For Android - it will be a standard push.
You can use any other custom parameters - they will be added as well according to specific platform push format. For iOS - it will be root keys, for Android - data.X.
Example:
JSON message:
{"message": "Message received from Bob", "ios_badge": 5, "ios_sound": "mysound.wav", "user_id": "234"}
Base64-encoded:
c29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQ
Final message:
event[message]=c29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQc29tZXZhbHVlMQ
Client's application will receive next payload:
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { NSLog(@"New push: %@", userInfo); } ... { aps = { alert = "Message received from Bob"; badge = 5; sound = "mysound.wav"; }; "user_id" = 234; }
@Override protected void onMessage(Context context, Intent intent) { String message = ""; for(String key : intent.getExtras().keySet()){ Log.d(LOG_TAG, key + ": " + intent.getExtras().getString(key)); } } ... 07-21 11:07:26.489 14443-14842/? D/GCMIntentService﹕ message: Message+received+from+Bob 07-21 11:07:26.489 14443-14842/? D/GCMIntentService﹕ user_id: 234 07-21 11:07:26.489 14443-14842/? D/GCMIntentService﹕ collapse_key: event1206083 07-21 11:07:26.489 14443-14842/? D/GCMIntentService﹕ from: 761750217637