Event Reference

Generic Event JSON Considerations

Each API event (as returned with the GET /api/event call) has a specific JSON representation that is defined in the following sections. Besides the specific elements, there is also a common structure, i.e. some fields that are present in all events. The generic JSON representation of any event („event skeleton”) looks like this:

{
    "id": 42,
    "event": "object_new",
    "time": 2182782732
}

The id field is a unique identifier of the event in the context of the current session. The first event of a newly created session has id 0, and the id is increased by 1 with every new event. This enables a client to detect whether the stream of events is contiguous, and it enables multiple clients to share the event stream of one server-side session (because every client knows what events it has already seen). The time field lists the time of event generation in seconds-since-epoch.

User events

Event user_modify

When the user settings of a user are modified, this event is sent to the user

{}

Invitation events

Event invitation_new

When an internal invitation is created, this event is sent both to the originator and the recipient of the invitation

{
    "owner": "2a578836-e7b3-11e1-8f2c-0024e8f90cc0",
    "user": "a1edadee-9ccd-11e0-ba16-0024e8f90cc0"
}

The owner field contains the UUID of the invitation originator.

The user field contains the UUID of the other party, the invited person.

Event invitation_delete

When an internal invitation is deleted by either party of the invitation, this event is sent both to the originator and the recipient of the invitation

{
    "owner": "2a578836-e7b3-11e1-8f2c-0024e8f90cc0",
    "user": "a1edadee-9ccd-11e0-ba16-0024e8f90cc0"
}

The owner field contains the UUID of the invitation originator.

The user field contains the UUID of the other party, the invited person.

Phone events

Event phone_modify

This event is sent to a user if her phone configuration is modified (usually via the POST /api/phone call). The event carries no additional payload, it just indicates the modification. Modified data can be retrieved using the GET /api/phone call.

{}

Tag events

Event tag_new

When a new tag is created, this event is sent to all users that have any access level within the tag (including the tag owner):

{
    "tag": "7b3785b8-974f-11e0-a900-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "label": "myTag",
    "foreign_use": true,
    "policy": {
        "1de7257a-4f34-11e0-ab6e-0024e8f90cc1": 4,
        "c5dbbdd4-0ad9-11e1-bd0d-0024e8f90cc0": 2,
        "c63ff81c-0ad9-11e1-bb94-0024e8f90cc0": 3
    }
}

The tag field contains the UUID of the new tag.

The owner field contains the UUID of user that owns the tag.

The policy section lists the access users of the tag with their respective access privileges (values are 1 = read, 2 = write, 3 = propagate, 4 = owner).

Event tag_modify

When an existing tag is modified (e.g., the label or the access policy is changed), this event is sent to all users that have at least read access before or after the modification.

{
    "tag": "7b3785b8-974f-11e0-a900-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "label": "myTag",
    "foreign_use": true,
    "policy": {
        "1de7257a-4f34-11e0-ab6e-0024e8f90cc1": 4,
        "c5dbbdd4-0ad9-11e1-bd0d-0024e8f90cc0": 3,
        "c63ff81c-0ad9-11e1-bb94-0024e8f90cc0": 0
    }
}

The tag field contains the UUID of the tag.

The owner field contains the UUID of user that owns the tag.

The policy section lists the access users of the tag with their respective access privileges (values are 0 = no access, 1 = read, 2 = write, 3 = propagate, 4 = owner). Note that in this case, a value of 0 is sent if the respective user has lost access the tag because of the modification.

Event tag_delete

When an existing tag is deleted, this event is sent to all users that had at least read access before the operation.

{
    "tag": "7b3785b8-974f-11e0-a900-0024e8f90cc0"
}

The tag field contains the UUID of the deleted tag.

Trash events

Event trash_purge

This event is sent to the user if her trash is purged, i.e. all objects in the trash are permanently deleted.

{}

Generic object events

Event object_new

When a new object is created, this event is sent to all users that access to the object (i.e. in most cases solely the owner).

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "description": "Hans Mustermann",
    "tag": [
        "be00e8aa-5c3d-11e0-b0cf-0024e8f90cc0",
        "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
        "97d3a606-a961-11e0-9a43-0024e8f90cc0"
    ]
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owns the object.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

The tag section contains a list of all tags attached to the object.

Event object_modify

When an existing object is modified (i.e. its fields are modified), this event is sent to all users that have at least read access before and after the modification. This event is not sent if only comments or attached tags are modified: specific events exist for these cases.

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
    "description": "Hans Mustermann"
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owns the object.

The user field contains the UUID of user who submitted the modification that triggered this event, if this action was initiated by a user. If not, this field will not be present.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

Event object_delete

When an existing object is deleted, this event is sent to all users that had at least read access before the delete operation.

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
    "description": "Hans Mustermann",
    "purge": true
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owned the object.

The user field contains the UUID of user who deleted the object, if this action was initiated by a user. If not, this field will not be present.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

The purge field, if present, indicates that this is a permanent delete (“delete-from-trash”).

Event object_share

When an object is shared with a new user for the first time by attaching a tag that grants access to this user, an event of this type is sent towards the user.

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
    "description": "Hans Mustermann",
    "tag": [
        "be00e8aa-5c3d-11e0-b0cf-0024e8f90cc0",
        "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
        "97d3a606-a961-11e0-9a43-0024e8f90cc0"
    ]
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owned the object.

The user field contains the UUID of user who shared the object, if this action was initiated by a user. If not, this field will not be present.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

The tag section contains a list of all tags currently attached to the object.

Event object_tag

When tags are attached to or detached from an existing object, this event is sent to all users that have at least read access before and after the modification, and that have at least access to one of the tags added or deleted to the object.

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
    "description": "Hans Mustermann",
    "tag": [
        "be00e8aa-5c3d-11e0-b0cf-0024e8f90cc0",
        "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
        "97d3a606-a961-11e0-9a43-0024e8f90cc0"
    ],
    "tag_add": [
        "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
        "97d3a606-a961-11e0-9a43-0024e8f90cc0"
    ],
    "tag_delete": [
        "0f3441b4-1141-11e1-8829-0024e8f90cc0"
    ]
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owned the object.

The user field contains the UUID of user who modified the tag attachments on the object, if this action was initiated by a user. If not, this field will not be present.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

The tag section contains a list of all tags currently attached to the object.

The tag_add section contains a list of all tags added to the object during this operation.

The tag_delete section contains a list of all tags deleted from the object during this operation.

Event object_unshare

When an object gets invisible to some user because the tag that grants access is removed, this user gets an event of this type.

{
    "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "type": "contact",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "ae30e5b0-5c3d-11e0-817e-0024e8f90cc0",
    "description": "Hans Mustermann"
}

The object field contains the UUID of the object.

The type field contains the object type, e.g. fax, contact, recording, …

The owner field contains the UUID of user who owned the object.

The user field contains the UUID of user who removed the tag attachments on the object, if this action was initiated by a user. If not, this field will not be present.

The description field, if present, contains a short, human-readable description of the object. This may be the actual description field of the object (if the object type has one), or the name of a contact or something similar.

Comment events

Event comment_new

When a new comment is added to an object, this event is sent to all users that access to the object.

{
    "comment": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "text": "This is a new comment",
    "object": {
        "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
        "type": "contact",
        "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
        "description": "Hans Mustermann"
    }
}

The comment field contains the UUID of the comment.

The owner field contains the UUID of the user who owns the comment.

The text field contains the full text content of the comment.

The object section contains the object’s UUID (object), type, owner and a textual description of the object (description).

Event comment_modify

When an existing comment is modified, this event is sent to all users that access to the object.

{
    "comment": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "text": "I changed the text of this comment",
    "object": {
        "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
        "type": "contact",
        "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
        "description": "Hans Mustermann"
    }
}

The comment field contains the UUID of the comment.

The owner field contains the UUID of the user who owns the comment.

The text field contains the new full text content of the comment.

The object section contains the object’s UUID (object), type, owner and a textual description of the object (description).

Event comment_delete

When an existing comment is deleted, this event is sent to all users that access to the object.

{
    "comment": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "object": {
        "object": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
        "type": "contact",
        "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
        "description": "Hans Mustermann"
    }
}

The comment field contains the UUID of the comment.

The owner field contains the UUID of the user who owned the comment.

The object section contains the object’s UUID (object), type, owner and a textual description of the object (description).

Metadata events

Event user_metadata

When the user’s metadata is changed, this event is sent to all sessions of that user

{
    "update": {
        "com.otherdomain.client.nice": true,
        "com.otherdomain.client.timestamp": 1324899645
    },
    "delete": [
        "com.otherdomain.client.something"
    ]
}

The update sections contain the metadata elements (key and value) that have been added or modified.

The delete array contains the metadata keys that have been deleted.

Event object_metadata

When an object’s metadata is changed, this event is sent to all users that have at least read access to the object.

{
    "object": "94f1bb1a-5931-11e0-8db5-0024e8f90cc0",
    "user": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "update": {
        "com.otherdomain.client.nice": true,
        "com.otherdomain.client.timestamp": 1324899645
    },
    "delete": [
        "com.otherdomain.client.something"
    ]
}

The object field contains the UUID of the object for which metadata elements were changed.

The user field contains the UUID of the user that did the change.

The update sections contain the metadata elements (key and value) that have been added or modified.

The delete array contains the metadata keys that have been deleted.

Fax events

Event fax_convert

When the fax contents of an existing fax are updated (after an upload and the following format conversion are finished), this event is sent to all users that have at least read access.

{
    "fax": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "page_count": 12
}

The fax field contains the UUID of the fax object.

In case of successful format conversion, the page_count field is present and contains the number of pages.

Event fax_report

This event is sent to all users that have at least read access to a fax in case a send/receive status change (“fax report”) is updated for this fax.

{
    "fax": "94f1bb1a-5931-11e0-8db5-0024e8f90cc0",
    "report": {
        "7b149600-5921-11e0-b85f-0024e8f90cc0": {
            "incoming": true,
            "from": "+492216689711",
            "to": "+492216689712",
            "time_start": 2128383234,
            "time_end": 2128384351,
            "status": "ok",
            "sip_status_code": 200,
            "fax_error_code": 0
        }
    }
}

The fax field contains the UUID of the fax object.

The fax report itself is encapsulated in the report section of the event. See the API documentation of the GET /api/fax/(uuid) API call for details about the fax report.

Announcement events

Event announcement_convert

When the announcement contents of an existing announcement are updated (after an upload and the following format conversion are finished), this event is sent to all users that have at least read access.

{
    "announcement": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "success": true
}

The announcement field contains the UUID of the announcement object.

In case of successful conversion, the success field will be present with a value of true.

Conference events

Event conference_start

When the first participant enters an active conference, this event is sent to all users that have at least read access to the conference. It serves as a signal that this conference is now „live”.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "description": "My Conference Room"
}

The conference field contains the UUID of the conference object.

The owner field contains the UUID of user who owned the object.

The description field, if present, contains a short, human-readable description of the conference.

Event conference_stop

When the last participant exits an active conference, this event is sent to all users that have at least read access to the conference.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "description": "My Conference Room"
}

The conference field contains the UUID of the conference object.

The owner field contains the UUID of user who owned the object.

The description field, if present, contains a short, human-readable description of the conference.

Event conference_status

To receive this event, the user needs to subscribe to the detailed event stream of the conference using the GET /api/conference/(uuid)/event call.

The server will send this event once after receiving the event stream subscription, and may send this event again in regular intervals as long as the subscription exists.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "member": {
        "9fe1cc2a-8ab6-11e0-b368-0024e8f90cc0": {
            "phone": "+492216698000",
            "user": "2d07f7be-8abc-11e0-8166-0024e8f90cc0",
            "mute": false,
            "deaf": false,
            "talk": true,
            "floor": true,
            "volume_in": 0,
            "volume_out": 0
        },
        "b1439c46-8ab6-11e0-acdc-0024e8f90cc0": {
            "phone": "+49241441010",
            "mute": false,
            "deaf": false,
            "talk": true,
            "floor": false,
            "volume_in": 0,
            "volume_out": 0
        }
    }
}

The conference field contains the UUID of the conference object.

The member section lists all participants of the conference, indexed by a UUID that is used to uniquely identify them.

The phone field is only present if the participant transmitted her originating phone number with the call.

The user field, connects the conference participant to a user account of a system. This field is only present if the participant was successfully connected to a user UUID via the specific API call.

Volume levels range from -4 to 4, where 0 is the default volume level.

Event conference_update

To receive this event, the user needs to subscribe to the detailed event stream of the conference using the GET /api/conference/(uuid)/event call.

The server will send this event if the current status of one or more conference members has changed.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "member": {
        "9fe1cc2a-8ab6-11e0-b368-0024e8f90cc0": {
            "talk": false,
            "floor": false
        },
        "b1439c46-8ab6-11e0-acdc-0024e8f90cc0": {
            "mute": true,
            "talk": false
        }
    }
}

The member sections only lists those members that actually have changes, and within the member only those fields that actually represent changes to the previous conference_status / conference_update event are present.

The fields in the event are identical to the definition in the conference_status event.

Event conference_join

To receive this event, the user needs to subscribe to the detailed event stream of the conference using the GET /api/conference/(uuid)/event call.

The server will send this event if one or more new conference participants join the conference.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "member": {
        "b20116b8-8acf-11e0-b38e-0024e8f90cc0": {
            "phone": "+492216698123",
            "mute": false,
            "deaf": false,
            "talk": true,
            "floor": true,
            "volume_in": 0,
            "volume_out": 0
        }
    }
}

The fields in the event are identical to the definition in the conference_status event.

Event conference_leave

To receive this event, the user needs to subscribe to the detailed event stream of the conference using the GET /api/conference/(uuid)/event call.

The server will send this event if one or more new conference participants leave the conference.

{
    "conference": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "member": [
        "b20116b8-8acf-11e0-b38e-0024e8f90cc0",
        "359e049a-8ad0-11e0-8a33-0024e8f90cc0"
    ]
}

The member sections lists the participant UUIDs that left the conference.

File events

Event file_new

When a file or folder is created within a volume object, this event is sent to all users that have at least read access to the volume.

{
    "commit": "383a5354-362f-11e3-837a-0024e8f90cc0",
    "file": "8aaf6000-474f-11e1-b0ba-0024e8f90cc0",
    "volume": "6a8432ec-474f-11e1-8495-0024e8f90cc0",
    "type": "file",
    "name": "letter.pdf",
    "parent": "9e6bde98-474f-11e1-9a62-0024e8f90cc0",
    "ctime": 20232142212,
    "mtime": 21232145373,
    "user": "bc93f42a-45d6-11e1-b856-0024e8f90cc0"
}

The commit field contains the commit UUID that this event relates to.

The file field contains the UUID of the file or folder (the name of the field is always file).

The volume field contains the UUID of the volume which contains the file.

The type field has a value of file if this event is about a file, or a value of folder if it is about a folder.

name is the file name of the file or folder.

The parent field is only present if the file or folder was not created on the root-level of the volume; it contains the parent folder UUID that the file or folder was created in.

The ctime and mtime fields contain the creation an modification timestamps of the file (seconds-since-epoch). Usually these reflect the current time if they were not set to a different value during file creation.

The user field contains the UUID of the user that created the file or folder.

Event file_modify

When a file or folder is modified, this event is sent to all users that have at least read access to the volume.

Note that there are no “hierarchical” events, that is, if a file is created, modified or deleted, no event will be sent for the folder that contains the file.

{
    "commit": "400f9be8-362f-11e3-b868-0024e8f90cc0",
    "file": "8aaf6000-474f-11e1-b0ba-0024e8f90cc0",
    "volume": "6a8432ec-474f-11e1-8495-0024e8f90cc0",
    "type": "file",
    "name": "letter2.pdf",
    "parent": "d5edfe04-4750-11e1-be06-0024e8f90cc0",
    "ctime": 20232142212,
    "mtime": 21232145373,
    "user": "bc93f42a-45d6-11e1-b856-0024e8f90cc0",
    "size": 386231,
    "mime_type": "application/pdf",
    "md5": "92f2e0728cd03376ed13a191734cc065"
}

The commit field contains the commit UUID that this event relates to.

The file field contains the UUID of the file or folder (the name of the field is always file).

The volume field contains the UUID of the volume which contains the file.

The type field has a value of file if this event is about a file, or a value of folder if it is about a folder.

The name field is only present if the file name of the file or folder was changed; it contains the new file name of the file or folder.

The parent field is only present if the file or folder was re-located (moved) within the volume.; it contains the new parent folder UUID that the file or folder was moved to.

The ctime and mtime fields contain the creation an modification timestamps of the file (seconds-since-epoch). Either field is only present if the value has changed.

The user field contains the UUID of the user that modified the file or folder.

The size, mime_type and md5 fields contain the file size (in octets), the MIME type (for example “image/png”) and the md5 checksum of the file contents. These fields are only present if new content was uploaded to the file.

Event file_delete

When a file or folder is deleted, this event is sent to all users that have at least read access to the volume.

Note that if a folder is deleted, all the contents of this folder is recursively deleted without sending file_delete events for every element that was deleted in the recursion.

{
    "commit": "46bf0e74-362f-11e3-a637-0024e8f90cc0",
    "file": "8aaf6000-474f-11e1-b0ba-0024e8f90cc0",
    "volume": "6a8432ec-474f-11e1-8495-0024e8f90cc0"
}

The commit field contains the commit UUID that this event relates to.

The file field contains the UUID of the file or folder (the name of the field is always file). As a special case, the file field may also contain the UUID of the volume itself to signal that all of the volume’s content were deleted (root-level delete).

The volume field contains the UUID of the volume which contains the file.

Box events

Event box_online

When a device comes online, this event is sent to all users that have access to the associated box object.

{
    "box": "964ae742-77fe-11e1-89b7-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "description": "box in office basement",
    "ip_addr": "192.168.0.13",
    "mac_addr": "00:24:d6:83:c1:54",
    "sw_version": "1.0",
    "hw_version": "X86"
}

The box field contains the UUID of the box object.

The owner field contains the UUID of user who ownes the object.

The description field, if present, contains a short, human-readable description of the box object.

The ip_addr field contains the current IP address of the device.

The mac_addr field contains the current MAC address of the device.

The sw_version field contains the running software version of the device.

The hw_version field contains the hardware model of the device.

Event box_offline

When a device goes offline, this event is sent to all users that have access to the associated box object.

{
    "box": "964ae742-77fe-11e1-89b7-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "description": "box in office basement"
}

The box field contains the UUID of the box object.

The owner field contains the UUID of user who ownes the object.

The description field, if present, contains a short, human-readable description of the box object.

Dialplan events

Event dialplan_modify

When a user’s dialplan is modified, this event it sent to the user.

{}

Event dialplan_callreverse_start

When an incoming phone call to the user’s dialplan activates the call-reverse function, this event is sent to the user.

{
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

The phone_from field contains the calling phone number.

The phone_to field contains the called phone number.

Event dialplan_callreverse_stop

When a call-reverse function ends, this event is sent to the user.

{
    "phone_from": "+4989123248278",
    "phone_to": "+492216698000"
}

The phone_from field contains the calling phone number.

The phone_to field contains the called phone number.

SIP events

Event sip_new

When a SIP account is created, this event is sent to the user that owns the account.

{
    "user": "joe_01",
    "domain": "cospace.de",
    "description": "office phone"
}

The user field contains the user part of the SIP account.

The domain field contains the domain part of the SIP account.

The description field will only be present if a description was set when creating the account.

Event sip_modify

When a SIP account is modified, this event is sent to the user that owns the account.

{
    "user": "joe_01",
    "domain": "cospace.de",
    "description": "softclient smartphone"
}

The user field contains the user part of the SIP account.

The domain field contains the domain part of the SIP account.

The description field will only be present if the description of the account was actually changed.

Event sip_delete

When a SIP account is deleted, this event is sent to the user that owned the account.

{
    "user": "joe_01",
    "domain": "cospace.de"
}

The user field contains the user part of the SIP account.

The domain field contains the domain part of the SIP account.

Event sip_register

When a SIP end-device registers with a SIP account, this event is sent to the user that owns the account.

{
    "user": "joe_01",
    "domain": "cospace.de",
    "contact": "212.202.0.32:5060",
    "expire": 1340107084
}

The user field contains the user part of the SIP account.

The domain field contains the domain part of the SIP account.

The contact field contains the IP address (and optional a port number) of the endpoint, the so-called contact information of the SIP registration.

The expire field contains the absolute time of registration expiration in seconds-since-epoch.

Event sip_unregister

When a SIP account is modified, this event is sent to the user that owns the account.

{
    "user": "joe_01",
    "domain": "cospace.de",
    "contact": "212.202.0.32:5060"
}

The user field contains the user part of the SIP account.

The domain field contains the domain part of the SIP account.

The contact field contains the IP address (and optional a port number) of the endpoint, the so-called contact information of the SIP registration.

Presentation events

Event presentation_convert

When the page contents of an existing presentation are updated (after an upload and the following format conversion is finished), this event is sent to all users that have at least read access.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "page_count": 12
}

The presentation field contains the UUID of the presentation object.

In case of successful format conversion, the page_count field is present and contains the number of pages.

Event presentation_start

When a presentation is started, this event is sent to all users that have at least read access to the conference. It serves as a signal that this presentation is now „live”.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "cc8a411a-13ab-11e2-bf75-0024e8f90cc0",
    "description": "Why The Sky Is Black At Nighttime"
}

The presentation field contains the UUID of the presentation object.

The owner field contains the UUID of user who owns the object.

The user field contains the UUID of user who started the presentation and is now the first member and moderator of the conference.

The description field, if present, contains a short, human-readable description of the presentation.

Event presentation_stop

When a presentation is ended, this event is sent to all users that have at least read access to the presentation.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "owner": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
    "user": "cc8a411a-13ab-11e2-bf75-0024e8f90cc0",
    "description": "Why The Sky Is Black At Nighttime"
}

The presentation field contains the UUID of the presentation object.

The owner field contains the UUID of user who owns the object.

The user field contains the UUID of user who ended the presentation (and who was the moderator). This field might be missing if the presentation is not actively ended by the moderator, but through other means (e.g., a timeout or failure condition).

The description field, if present, contains a short, human-readable description of the presentation.

Event presentation_join

To receive this event, the user needs to subscribe to the detailed event stream of the presentation using the GET /api/presentation/(uuid)/event call.

This event is sent when a new member joins the presentation. It will not be sent for the first conference member (the first member included in the presentation_start event).

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "user": "cc8a411a-13ab-11e2-bf75-0024e8f90cc0"
}

The presentation field contains the UUID of the presentation object.

The user field contains the UUID of user who joined the presentation.

Event presentation_leave

To receive this event, the user needs to subscribe to the detailed event stream of the presentation using the GET /api/presentation/(uuid)/event call.

This event is sent when a member leaves the presentation. It will not be sent if the conference is stopped completely (in this case, the conference_stop should be considered as an implicit leave for all conference members).

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "user": "cc8a411a-13ab-11e2-bf75-0024e8f90cc0"
}

The presentation field contains the UUID of the presentation object.

The user field contains the UUID of user who left the presentation.

Event presentation_status

To receive this event, the user needs to subscribe to the detailed event stream of the presentation using the GET /api/presentation/(uuid)/event call.

The server will send this event once after receiving the event stream subscription, and may send this event again in regular intervals as long as the subscription exists.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "page": 2,
    "x": 0.45,
    "y": 0.8,
    "visible": true,
    "moderator": "2d515d81-a459-471b-917b-bcf6424575b1",
    "member": [
        "3068ef3f-eba4-421a-90e6-02f443ac52ff",
        "2d515d81-a459-471b-917b-bcf6424575b1",
        "e1eaa085-58b7-4e56-8fcb-581393bd7bc6"
    ]
}

The presentation field contains the UUID of the presentation object.

The page field contains number of the current page.

The x field contains horizontal position of the pointer between 0.0 (left) and 1.0 (right).

The y field contains vertical position of the pointer between 0.0 (top) and 1.0 (bottom).

The visible field denotes whether the pointer is visible (true) or not (false).

The moderator field contains the UUID of the moderator.

The member array lists all participants of the presentation.

Event presentation_update

To receive this event, the user needs to subscribe to the detailed event stream of the presentation using the GET /api/presentation/(uuid)/event call.

The server will send this event if one or more properties of the presentation have changed.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "page": 3,
    "x": 0.53,
    "y": 0.8,
    "visible": true,
    "moderator": "2d515d81-a459-471b-917b-bcf6424575b1"
}

The fields in the event are a subset of the fields in the presentation_status event (see there).

All fields all optional, usually the server will only send fields that have changed values since the last event.

Event presentation_keepalive

This event is sent periodically to all members who have joined a presentation. Clients are requested to answer with a keepalive control message (POST /api/presentation/(uuid)/control) to refresh the join state at the presentation controller. Clients that receive this event and that are not joined to the presentation should not send a leave control message, because other clients for the same user might be joining the presentation.

{
    "presentation": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0"
}

The presentation field contains the UUID of the presentation object.

Chat events

Event chat_new

When a chat is created, this event is sent to the user who created the chat (directly after creating a chat, this user is the only one in the chat).

{
    "chat": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "create_time": 1362587184
}

The chat field contains the UUID of the chat.

The create_time field contains the creation time of the chat in seconds-since-epoch.

Event chat_message

When a message is sent within a chat, this event is sent to all users participating in the chat.

{
    "chat": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "message": {
        "c1aa1566-84d7-11e2-a7a8-0024e8f90cc0": {
            "user": "1de7257a-4f34-11e0-ab6e-0024e8f90cc1",
            "time": 1362407297,
            "type": "text",
            "text": "what's for lunch today?"
        }
    }
}

The chat field contains the UUID of the chat.

The message section corresponds to the format of the GET /api/chat/(uuid)/message call. For a description about possible message types, refer to the POST /api/chat/(uuid)/message call.

If type is add, this event will be the first for this chat that is delivered to the user who entered the chat. The member field will show the user that was added to the chat. In this case, a create_time field will be present in the main section of this event that contains the creation time of the chat in seconds-since-epoch and a description field will be present if the chat has a description.

If type is leave, this event will be the last for this chat that is delivered to the user who left the chat. Since a user can only leave the chat by herself, the user field will also tell who left the chat.

Event chat_user

When the expiration time of a transient user state within a chat changes, this event is sent to all users participating in the chat.

{
    "chat": "52a9fd3c-8aad-11e0-9138-0024e8f90cc0",
    "user": {
        "1de7257a-4f34-11e0-ab6e-0024e8f90cc1": {
            "typing": 10
        }
    }
}

The chat field contains the UUID of the chat.

The user section corresponds to the format of the GET /api/chat/(uuid)/user call. This event will not deliver a complete list of user states, but will only contain states that have a changed expiration time. The message_read field will be present if the message read pointer was modified for the corresponding user.

Note that the reception of a chat_user event does not in every case mean that the user state actually changed, but is used only to deliver a modified expiration time for the transient change to other participant. Actual state changes will only happen if an expire value > 0 is given for a state that is currently inactive in the client, or if a timer set by this event expires. As a special case, this event might carry a timer of 0, which will immediately set the state to inactive.

Call events

Please note that all events described in this chapter are part of the call API and only delivered in case that the user enables call API events with the GET /api/call/event method.

Event call_update

This event signals changes in the call parameters for the call given in the call section (the key is the call UUID). The fields match those defined in the GET /api/call method. Only parameters that are actually changed will be included in the event.

{
    "call": {
        "2b3b70ce-8677-11e2-a7c1-0024e8f90cc0": {
            "answer_time": 1362587197,
            "status": "answered"
        }
    }
}

In the special case of the current_control parameter, an empty value string signals that no control is currently operating on the call (in the GET /api/call method, the current_control field will be absent in this case). An empty bridge field signals that the call is no longer bridged to another call.

Event call_dtmf

If DTMF detection and delivery is enabled on a call, incoming DTMF digits will be delivered via this event.

{
    "call": "2b3b70ce-8677-11e2-a7c1-0024e8f90cc0",
    "digit": "2",
    "duration": 143
}

The digit field contains the DTMF digit that was detected.

The duration field contains duration of the digit.

Sensor events

Event sensor_data

When a sensor delivers data to the cloud, this event is delivered to all user sessions that requested the delivery of sensor data events with GET /api/sensor/(uuid)/event.

{
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc0",
    "data": {
        "1363623247000": [
            20.5,
            [
                0,
                255
            ]
        ]
    }
}

The sensor field holds the UUID of the sensor object.

The data section lists the new sensor data, typically a single entry. The format is the same as in the GET /api/sensor/(uuid)/data call.

Event sensor_action

When an action was carried out on a sensor, this event is delivered to all user sessions that requested the delivery of sensor data events with GET /api/sensor/(uuid)/event.

{
    "status": "ok",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc0",
    "action": {
        "1363623253000": [
            1,
            null
        ]
    },
    "action-uuid": "97a1f558-9167-11e2-892a-0024e8f90cc0"
}

The status field contains ok if the action was carried out. It might contain replaced if the action was superseded by another action while waiting for the sensor to become available for radio transmittion.

The action section lists the action that was carried out, typically a single entry. The format is the same as in the GET /api/sensor/(uuid)/action call.

The action-uuid field holds the action UUID that corresponds to the action-uuid field in the response of the POST /api/sensor/(uuid)/action call.