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 Firebase Cloud Messaging for Android (FCM).

Response body example

{
    "fcm": {
        "device_tokens": [
            "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 fcm section lists the items necessary to use Firebase Cloud Messaging for Android (FCM). The tokens array lists all tokens 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 Firebase Cloud Messaging for Android (FCM).

Request body example

{
    "system": "fcm",
    "action": "add",
    "device_token": "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx..."
}

- or -

{
    "system": "fcm",
    "action": "delete",
    "device_token": "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 –
fcm|apns

selects operation for Apple (APNs) or Google (FCM)
action – add|delete
device_token –
^[0-9a-fA-F]{64}$

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 Firebase Cloud Messaging for Android (fcm) 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 FCM, the device_token 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 FCM.

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.

FCM 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 FCM, page_count is of type string because FCM 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.

FCM 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.

FCM 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.

FCM 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.

FCM 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 FCM, time is of type string because FCM suggests to only use strings as values in the notification payload.

Apple Push Notifications & Google Cloud Messaging¶

API Call Reference¶

Push Event Reference¶

Push Event fax_new¶

Push Event recording_new¶

Push Event dialplan_callreverse_start¶

Push Event dialplan_callreverse_stop¶

Push Event chat_message¶

Table of Contents

Related Topics

API email update