undefined

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:

  1. Create session with a user
  2. Subscribe user on push notifications

On sender's side:

  1. Create session with a user
  2. Create event

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_channels": "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
  • email
  • 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 immidiately
  • fixed_date - to send on the specified date
  • period_date - periodic push that is sent in the specified time period from the start date. Period can be specified only if the start_date parameter is provided as well
  • Default values:
  • fixed_date - if 'date' is specified
  • period_date - if 'period' is specified
  • one_shot - if 'date' is not specified
  • 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
    event[date] yes if the 'event_type' = 'fixed_date' or 'period_date' Timestamp, in seconds The date when the scheduled notifications should be sent on. If the 'event type'=='fixed_date', the date can not be in the past
    event[end_date] no Timestamp, in seconds Date when the scheduled push should stop a periodic delivery
    event[period] yes if the 'event_type' = 'period_date' Timestamp, in seconds Event period specified in seconds. Possible values:
  • 86400 (1 day)
  • 604800 (1 week)
  • 2592000 (1 month)
  • 31557600 (1 year)
  • event[name] no string The name of the event for debug purpose

    *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"
            }
        }
    }

    Retrieve events

    Get all events which were created by a user specified in the authorization token.

    Endpoint
    GET https://api.connectycube.com/events
    Request example
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/events
    Response
    {
        "current_page": 1,
        "per_page": 10,
        "total_entries": 1,
        "items": [
            {
                "event": {
                    "id": 8429,
                    "event_type": "one_shot",
                    "message": "payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogew0KICAgICAgICAgICAgInRpdGxlIiA6ICJHYW1lIFJlcXVlc3QiLA0KICAgICAgICAgICAgImJvZHkiIDogIkJvYiB3YW50cyB0byBwbGF5IHBva2VyIg0KICAgICAgICB9LA0KICAgICAgICAiYmFkZ2UiIDogNQ0KICAgIH0sDQogICAgImFjbWUxIiA6ICJiYXIiDQp9",
                    "date": null,
                    "period": null,
                    "name": null,
                    "occured_count": 1,
                    "created_at": "2018-12-06T11:31:23Z",
                    "updated_at": "2018-12-06T11:31:23Z",
                    "end_date": null,
                    "active": false,
                    "application_id": 1,
                    "user_id": 271,
                    "kind": "API",
                    "environment": "development",
                    "tag_query": null,
                    "notification_channel": {
                        "name": "apns"
                    }
                }
            }
        ]
    }

    Retrieve event by ID

    Retrieve event by its identifier. The event specified in the request should belong to the application for which the authorization token has been received.

    Endpoint
    GET https://api.connectycube.com/events/{event_id}
    Request example
    curl -X GET \
    -H "CB-Token: <TOKEN>" \
    https://api.connectycube.com/events/8429
    Response
    {
        "event": {
            "id": 8429,
            "event_type": "one_shot",
            "message": "payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogew0KICAgICAgICAgICAgInRpdGxlIiA6ICJHYW1lIFJlcXVlc3QiLA0KICAgICAgICAgICAgImJvZHkiIDogIkJvYiB3YW50cyB0byBwbGF5IHBva2VyIg0KICAgICAgICB9LA0KICAgICAgICAiYmFkZ2UiIDogNQ0KICAgIH0sDQogICAgImFjbWUxIiA6ICJiYXIiDQp9",
            "date": null,
            "period": null,
            "name": null,
            "occured_count": 1,
            "created_at": "2018-12-06T11:31:23Z",
            "updated_at": "2018-12-06T11:31:23Z",
            "end_date": null,
            "active": false,
            "application_id": 1,
            "user_id": 271,
            "kind": "API",
            "environment": "development",
            "tag_query": null,
            "notification_channel": {
                "name": "apns"
            }
        }
    }

    Edit event

    Update details of the event.

    Endpoint
    PUT https://api.connectycube.com/events/{event_id}
    Parameter
    Parameter Required Type Description
    event[active] no bool Mark event as active/inactive. Possible values: true, false
    event[message] no base64
  • event[push_type] not present - should be Base64 encoded text.
  • event[push_type] specified - should be formatted as described in ConnectyCube Push Notifications Formats
  • event[date] yes if the 'event_type' = 'fixed_date' or 'period_date' Timestamp, in seconds The date when the scheduled notifications should be sent on. If the 'event type'=='fixed_date', the date can not be in the past.
    event[period] yes if the 'event_type' = 'period_date' Timestamp, in seconds Event period specified in seconds. Possible values:
  • 86400 (1 day)
  • 604800 (1 week)
  • 2592000 (1 month)
  • 31557600 (1 year)
  • event[name] no string The name of the event for debug purpose
    Request example
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "CB-Token:  <TOKEN>" \
    -d '{"event": {"name": "Updated name"}}' \
    https://api.connectycube.com/events/8429
    Response
    {
        "event": {
            "id": 8429,
            "event_type": "one_shot",
            "message": "payload=ew0KICAgICJhcHMiIDogew0KICAgICAgICAiYWxlcnQiIDogew0KICAgICAgICAgICAgInRpdGxlIiA6ICJHYW1lIFJlcXVlc3QiLA0KICAgICAgICAgICAgImJvZHkiIDogIkJvYiB3YW50cyB0byBwbGF5IHBva2VyIg0KICAgICAgICB9LA0KICAgICAgICAiYmFkZ2UiIDogNQ0KICAgIH0sDQogICAgImFjbWUxIiA6ICJiYXIiDQp9",
            "date": null,
            "period": null,
            "name": "Updated name",
            "occured_count": 1,
            "created_at": "2018-12-06T11:31:23Z",
            "updated_at": "2018-12-06T12:23:00Z",
            "end_date": null,
            "active": false,
            "application_id": 1,
            "user_id": 271,
            "kind": "API",
            "environment": "development",
            "tag_query": null,
            "notification_channel": {
                "name": "apns"
            }
        }
    }

    Delete event

    Delete event by its identifier.

    Endpoint
    DELETE https://api.connectycube.com/events/{event_id}
    Request example
    curl -X DELETE \
    -H "CB-Token:  <TOKEN> "\
    DELETE https://api.connectycube.com/events/8429
    Response
    Status: 200

    Payload formation rules

    ConnectyCube provides 2 types of push notifications that can be sent:

    • Platform based push notification - will be delivered to specified platform only
    • Universal push notifications - will be delivered to all possible platforms

    Platform based push notification

    Platform based push notification will be delivered to specified platform only. To specify platform use event[push_type] parameter in 'create event' request.

    With platform based push notifications allowed to use all possible push payload parameters provided by particular platform (iOS or Android).

    General requirements

    Push notification payload format is a 'key=value' string where 'key' is a raw string, and 'value' - base64 encoded and CGI escaped. Each pair should be separated by '&'

    Example: key1=c29tZXZhbHVlMQ==&key2=YW5vdGhlcnZhbHVlMg==&key3=dGhpcmRleGFtcGxl

    Important: '&' should be escaped with '%26'

    IOS

    Push notification payload has to meet Apple payload requirements.

    Example:

    1. Initial JSON payload:

       {
           "aps" : {
               "alert" : "Hello world",
               "badge" : 2
           },
           "dialog_id" : "89y970c0912c123fed45652n",
           "user_id" : 51
       }
    2. Base64 Encoded data: ewoJICAgICJhcHMiIDo...iIDogNTEKCX0K

    3. Final message (for iOS pushes you should add payload= before message): event[message]=payload=ewoJICAgICJhcHMiIDo...iIDogNTEKCX0K

    Android

    Push notification payload has to meet Firebase Cloud Messaging (FCM) requirements.

    Push notifications format is a data.key1=value1&...&data.keyN=valueN. Values should be CGI-escaped and then Base64 encodeded. Required field collapse_key is added automatically before sending and contains value event<ID>

    data.message key is required and should be 1st.

    Example:

    1. Plain message: data.message=New message arrived

    2. CGI-escaped: data.message=New+message+arrived

    3. Base64-encoded: data.message=TmV3K21lc3NhZ2UrYXJyaXZlZA==

    4. Final message: event[message]=data.message=TmV3K21lc3NhZ2UrYXJyaXZlZA==

    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.

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

    Example:

    1. Initial JSON message: {"message": "Walking in a flowers garden", "ios_badge": 2, "ios_sound": "lounge.wav", "user_id": "51"}

    2. Base64-encoded: V2Fsa2luZyBpbiBhIGZsb3dlcnMgZ2FyZGVu

    3. Final message: event[message]=V2Fsa2luZyBpbiBhIGZsb3dlcnMgZ2FyZGVu