Apple Push Notifications & Google Cloud Messaging

API Call Reference

GET /api/push

Get the current user’s configuration for Apple Push Notification service (APNs) and Google Cloud Messaging for Android (GCM).

Response body example

{
    "gcm": {
        "sender_id": "4815162342",
        "registration_ids": [
            "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
            "Iausdj89apcoaSDdojfAsidfAs8d84-5621i..."
        ]
    },
    "apns": {
        "device_tokens": {
            "a6461732069737d42065496e...f39ad": {
                "application_id": "39JSDKGJ38.de.cospace.app",
                "sandbox": true
            },
            "a6281e62e55932df9ec72829...5e2d3": {
                "application_id": "39JSDKGJ38.de.cospace.app",
                "sandbox": false
                "apns_topic": "de.cospace.app.voip"
            }
        }
    }
}

The gcm section lists the items necessary to use Google Cloud Messaging for Android (GCM). The sender_id is needed by the App to apply for a registration ID that identifies the combination of App and Device as a receiver for cloud messages (push notifications). The registration_ids array lists all registration IDs that are stored for the current user.

The apns section lists the items necessary to use Apple Push Notification service (APNs). In the device_tokens section, all active device tokens are listed as keys, with their respective application ID in the value (the application ID consists of the application’s bundle ID prefixed with a ten-character code generated by Apple) and optional APNS topic. Device tokens are 32-byte octet strings and represented here as 64-character hexadecimal strings.

POST /api/push

Add or delete tokens for Apple Push Notification service (APNs) or registration IDs for Google Cloud Messaging for Android (GCM).

Request body example

{
    "system": "gcm",
    "action": "add",
    "registration_id": "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx..."
}

- or -

{
    "system": "gcm",
    "action": "delete",
    "registration_id": "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx..."
}

- or -

{
    "system": "apns",
    "action": "add",
    "device_token": "a6461732069737d42065496e...f39ad",
    "sandbox": true,
    "application_id": "39JSDKGJ38.de.cospace.app"
    "apns_topic": "de.cospace.app.voip"
}

- or -

{
    "system": "apns",
    "action": "delete",
    "device_token": "a6461732069737d42065496e...f39ad"
}
JSON Parameters:
 
  • system

    gcm|apns

    selects operation for Apple (APNs) or Google (GCM)

  • actionadd|delete
  • registration_id

    ^.{10,250}$

    only for GCM: the registration ID

  • device_token

    ^[0-9a-fA-F]{64}$

    only for APNs: the device token

  • sandbox

    true|false

    optional; only for APNs and action add: selects the sandbox APNS

  • application_id

    ^[a-zA-Z0-9]{10}.[a-zA-Z0-9.-]{5,100}$

    only for APNs and action add: the application ID (team-id.bundle-id)

  • apns_topic

    ^[a-zA-Z0-9.-]{5,100}$

    optional; only for APNs and action add: the APNS topic if not set, the bundle-id part of the application-id will be used instead.

Response body example

{}
JSON Parameters:
 
  • status
    • unknown-appid: The application ID is not known to the system (see note below)
    • invalid-appid: The application ID is syntactically invalid
    • invalid-apns-topic: The APNS topic is syntactically invalid

The system field selects Apple Push Notification service (apns) or Google Cloud Messaging for Android (gcm) as the basis of the operation. The following fields depend on this choice.

The action field defines whether this API call will result in a new registration ID / device token being registered with the system (add) or an existing entry to be removed from the system (delete).

For GCM, the registration_id must be specified with both the add or delete operation.

For APNs, both the device_token and the application_id need to be specified with the add operation. For the delete operation, it is sufficient to specify only the device_token. The sandbox field specifies whether notifications for this device token should be send to the sandbox APNS.

Please note that for APNs, since Apple requires custom certificates for each application ID, it is necessary to contact the cospace team if you want to integrate a new app. No such restriction exists for GCM.

Push Event Reference

Push Event fax_new

This push event is sent to all registered devices when a new fax has been received by the system.

GCM content:

{
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "fax_new",
    "fax": "af729cc0-3251-11e2-81c1-0800200c9a66",
    "phone": "+492215587412",
    "page_count": "2"
}

APNs content:

{
    "aps": {
        "content-available": 1
    },
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "fax_new",
    "fax": "af729cc0-3251-11e2-81c1-0800200c9a66",
    "phone": "+492215587412",
    "page_count": 2
}

The owner field contains the UUID of the user who received the fax.

The fax field contains the UUID of the new fax, the phone field contains the phone number of the sender and the page_count field contains the number of pages in the fax.

Note that for GCM, page_count is of type string because GCM suggests to only use strings as values in the notification payload.

Push Event recording_new

This push event is sent to all registered devices when a new recording has been received by the system.

GCM content:

{
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "recording_new",
    "recording": "af729cc0-3251-11e2-81c1-0800200c9a66",
    "phone": "+492215587412"
}

APNs content:

{
    "aps": {
        "content-available": 1
    },
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "recording_new",
    "recording": "af729cc0-3251-11e2-81c1-0800200c9a66",
    "phone": "+492215587412"
}

The owner field contains the UUID of the user who received the recording.

The recording field contains the UUID of the new recording and the phone field contains the phone number of the caller.

Push Event dialplan_callreverse_start

This push event is sent to all registered devices when a call-reverse function has been started.

GCM content:

{
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "dialplan_callreverse_start",
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

APNs content:

{
    "aps": {
        "content-available": 1
    },
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "dialplan_callreverse_start",
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

The owner field contains the UUID of the user who started the call-reverse function.

The phone_from field contains the caller’s phone number (origination number).

The phone_to field contains the called phone number (destination number).

Push Event dialplan_callreverse_stop

This push event is sent to all registered devices when a call-reverse function has been stopped.

GCM content:

{
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "dialplan_callreverse_stop",
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

APNs content:

{
    "aps": {
        "content-available": 1
    },
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "dialplan_callreverse_stop",
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

The owner field contains the UUID of the user who started the call-reverse function.

The phone_from field contains the caller’s phone number (origination number).

The phone_to field contains the called phone number (destination number).

Push Event chat_message

This push event is sent to all registered devices when a chat message is delivered to a user.

GCM content:

{
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "chat_message",
    "chat": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "uuid": "c1aa1566-84d7-11e2-a7a8-0024e8f90cc0",
    "time": "1362407297",
    "user": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user_name": "John Doe",
    "type": "text",
    "text": "what's for lunch today?"
}

APNs content:

{
    "aps": {
        "content-available": 1
    },
    "owner": "9aed5e94-3803-11e3-8475-0024e8f90cc0",
    "message": "chat_message",
    "chat": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "uuid": "c1aa1566-84d7-11e2-a7a8-0024e8f90cc0",
    "time": 1362407297,
    "user": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user_name": "John Doe",
    "type": "text",
    "text": "what's for lunch today?"
}

The owner field contains the UUID of the user who got this chat message.

The chat field contains the UUID of the chat, the uuid field contains the UUID of the message.

The push event contains the fields of the chat message as described in the API call GET /api/chat/(uuid)/message (in this case user, type and text). The additional user_name field contains the full name of the user.

Note that for GCM, time is of type string because GCM suggests to only use strings as values in the notification payload.