Push notifications API

Push notifications are a communication channel built into every mobile device sold today. Push notifications allow apps to reach out to users with short messages that users may respond to. Users don’t have to be in the app or using their devices to receive them.

ConnectyCube provides an API to subscribe users for push notifications and to initiate push events.

To send a notification on user’s device, the following actions should be initially completed:

On receiver’s side:

On sender’s side:

Create subscription

Endpoint

POST https://api.connectycube.com/subscriptions

Parameters

Parameter	Required	Description
notification_channel	yes	Declare which notification channels could be used to notify user about events: apns apns_voip gcm
push_token[environment]	yes	Determines application environments. It allows conveniently separate development and production environments. Allowed values: development production
push_token[bundle_identifier]	no	A unique identifier for client’s application. In iOS, this is the Bundle Identifier. In Android - package id
push_token [client_identification_sequence]	yes	Identifies client device in 3-rd party service like APNS, GCM/FCM. Initially retrieved from 3-rd service and should be send to ConnectyCube to let it send push notifications to the client
device[platform]	yes	Platform of device, which is the source of application running. Allowed values: ios android
device[udid]	yes	UDID (Unique Device identifier) of device, which is the source of application running. This must be any sequence which uniquely identifies a particular device. This is needed to support schema: 1 User - Multiple devices

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token: <TOKEN>" \
-d '{"notification_channel": "apns", "push_token": {"environment": "development", "client_identification_sequence": "98559c1f3028b3fa0ec811d058cef16be27fe2fc507ca243b3d4fab006bfc9b8"}, "device": {"platform": "ios", "udid": "BFE36393-24E4-7689-AF85-428F4A5F2ED9"}}' \
https://api.connectycube.com/subscriptions

Response

[
  {
    "subscription": {
      "id": 50,
      "notification_channel": {
        "name": "apns"
      },
      "device": {
        "udid": "BFE36393-24E4-7689-AF85-428F4A5F2ED9",
        "platform": {
          "name": "ios"
        }
      }
    }
  }
]

Retrieve subscriptions

Retrieve subscriptions for current user.

GET https://api.connectycube.com/subscriptions

Request example

curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/subscriptions

Response

[
  {
    "subscription": {
      "id": 55,
      "notification_channel": {
        "name": "apns"
      },
      "device": {
        "udid": "7618C089-4C28-5214-6H3C-763AC0CA79FW",
        "platform": {
          "name": "ios"
        }
      }
    }
  },
  {
    "subscription": {
      "id": 56,
      "notification_channel": {
        "name": "apns"
      },
      "device": {
        "udid": "7618C089-4C28-5214-6H3C-763AC0CA79FW",
        "platform": {
          "name": "ios"
        }
      }
    }
  }
]

Remove subscription

Remove a subscription by its identifier.

Endpoint

DELETE https://api.connectycube.com/subscriptions/{subscription_id}

Request example

curl -X DELETE \
-H "CB-Token:  <TOKEN> "\
https://api.connectycube.com/subscriptions/56

Response

200 OK

Create event

Create event to initiate a push notification delivery.

Endpoint

POST https://api.connectycube.com/events

Parameter

Parameter	Required	Type	Description
event[notification_type]	yes	enum	Type of notification. Allowed values: push
event[push_type]	yes	enum	Used only if notification_type == push, ignored in other cases. If not present - Notification will be delivered to all possible devices for specified users. Each platform has their own standard format. If specified - Notification will be delivered to the specified platform only. Allowed values: apns apns_voip gcm
event[environment]	yes	enum	An environment of the notification. Allowed values: development production
event[event_type]	no	enum	Allowed values: one_shot - to send immediately
event[message]	yes	event[push_type] not present - should be Base64 encoded text. event[push_type] specified - should be formatted as described in Payload formation rules	Push notification payload
event[user][ids]	optional*	string	Users who will receive push notifications. Several IDs comma separated can be specified
event[external_user][ids]	optional*	string	Send push notifications to users specifying their external IDs. Several external IDs comma separated can be specified
event[user][tags][any]	optional*	string	Send push notifications to users specifying their tag(s). Recipients must have at least one tag specified in the list of tags
event[user][tags][all]	optional*	string	Send push notifications to users specifying their tag(s). Recipients must have all tags specified in list of tags
event[user][tags][exclude]	optional*	string	Send push notifications to users who do not have the specified tags

** Only one of these parameters is required.*

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token:  <TOKEN>" \
-d '{"event": {"notification_type": "push", "environment": "development", "user": { "ids": "271"}, "message": "payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogew0KICAgICAgICAgICAgInRpdGxlIiA6ICJHYW1lIFJlcXVlc3QiLA0KICAgICAgICAgICAgImJvZHkiIDogIkJvYiB3YW50cyB0byBwbGF5IHBva2VyIg0KICAgICAgICB9LA0KICAgICAgICAiYmFkZ2UiIDogNQ0KICAgIH0sDQogICAgImFjbWUxIiA6ICJiYXIiDQp9", "push_type": "apns"}}' \
https://api.connectycube.com/events

Response

[{
    "event": {
        "id": 8429,
        "event_type": "one_shot",
        "message": "payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogew0KICAgICAgICAgICAgInRpdGxlIiA6ICJHYW1lIFJlcXVlc3QiLA0KICAgICAgICAgICAgImJvZHkiIDogIkJvYiB3YW50cyB0byBwbGF5IHBva2VyIg0KICAgICAgICB9LA0KICAgICAgICAiYmFkZ2UiIDogNQ0KICAgIH0sDQogICAgImFjbWUxIiA6ICJiYXIiDQp9",
        "date": null,
        "period": null,
        "name": null,
        "occured_count": 0,
        "created_at": "2018-12-06T11:31:23Z",
        "updated_at": "2018-12-06T11:31:23Z",
        "end_date": null,
        "active": true,
        "application_id": 1,
        "user_id": 271,
        "kind": "API",
        "environment": "development",
        "tag_query": null,
        "notification_channel": {
            "name": "apns"
        }
    }
}]

Payload formation rules

Universal Push Notifications

Universal push notifications will be delivered to all platforms. To send Universal push notification do not set event[push_type] parameter in the ‘Create event’ request.

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 standard iOS push. For Android - it will be a standard push.
ios_push_type - will be translated to apns-push-type header for iOS. Allowed values (alert, background), default alert. Ignored for Android
ios_thread_id - will be translated to aps.thread-id for iOS. Ignored for Android
expiration - A UNIX epoch date expressed in seconds (UTC). This value identifies the date when the notification is no longer valid and can be discarded. In short, the value should equal ‘current timestamp’ + ‘ttl offset, in seconds’. Will be translated to apns-expiration for iOS and time-to-live or ttl for Android FCM
android_fcm_notification - will be translated to ‘notification.*’ param on Android. Ignored for iOS. Available fields
ios_loc_data - object with notification localization settings for iOS. Ignored for Android
Object example:

{
    "title_loc_key": "GREETING_NOTIFICATION",
    "title_loc_args": ["smith"],
    "body_loc_key": "CUBE_NOTIFICATION",
    "body_loc_args": ["hi there", "guest"]
}

title_loc_key - will be translated to aps.alert.title-loc-key
title_loc_args - will be translated to aps.alert.title-loc-args
body_loc_key - will be translated to aps.alert.loc-key
body_loc_args - will be translated to aps.alert.loc-args
None of these parameters are required

Other custom parameters can be used as well according to specific platform push format.

Example:

Initial JSON message:

{
    "message": "Walking in a flowers garden",
    "ios_badge": 2,
    "ios_sound": "lounge.wav",
    "friend_id": 51,
    "ios_loc_data": {
        "title_loc_key": "GREETING_NOTIFICATION",
        "title_loc_args": ["Tom Silencer"],
    }
}

Base64-encoded:

eyJtZXNzYWdlIjoiV2Fsa2luZyBpbiBhIGZsb3dlcnMgZ2FyZGVuIiwiaW9zX2JhZGdlIjoyLCJpb3Nfc291bmQiOiJsb3VuZ2Uud2F2IiwiZnJpZW5kX2lkIjo1MSwiaW9zX2xvY19kYXRhIjp7InRpdGxlX2xvY19rZXkiOiJHUkVFVElOR19OT1RJRklDQVRJT04iLCJ0aXRsZV9sb2NfYXJncyI6WyJUb20gU2lsZW5jZXIiXX19

Final message:

event[message]=eyJtZXNzYWdlIjoiV2Fsa2luZyBpbiBhIGZsb3dlcnMgZ2FyZGVuIiwiaW9zX2JhZGdlIjoyLCJpb3Nfc291bmQiOiJsb3VuZ2Uud2F2IiwiZnJpZW5kX2lkIjo1MSwiaW9zX2xvY19kYXRhIjp7InRpdGxlX2xvY19rZXkiOiJHUkVFVElOR19OT1RJRklDQVRJT04iLCJ0aXRsZV9sb2NfYXJncyI6WyJUb20gU2lsZW5jZXIiXX19