Messages

The PbxMessages protocol is available on AppWebsocket connections to the Messages App. There are different applications for this protocol

Store Chat messages: The PBX Messages object uses this protocol to store chat messages, for users having this object as messages object configured.
Retrieve Chat messages: A chat client can use this protocol to retrieve stored chat messages. For this the PbxMessages protocol is used to forward messages of this protocol from the AppWebsocket connection to the PBX to the messages App.
Post messages in general: The Topic App or other Apps can use the Protocol to post messages, and monitor for posted messages with filters based on hashtags and topics.

General structure

{
    "src": string,
    "mt": string,
}

src: The AppWebsocket src mechanism is supported on the interface. So a src property may be used
mt: The message type identifies the requested operation

Note: No api property is used by the Messages protocol. The messages sent on an AppWebsocket connection to an App implementing the Messages protocol are interpreted by default as belonging to the Messages protocol.

Messages to the Messages App

Post - Post a message
ReadChats - Read the list of chat destinations
ReadChat - Read messages of a chat destination
CreateFileBuffer - Create a file buffer, to which an attachment can be uploaded. A URL is returned to which the file can be posted. This URL is also send with the chat message
WriteGroup - Create or update a group. The sip URI of the group is created
ReadGroups - Read the list of available Groups
WriteMember - Add a member to a group or delete a member of a group
SetFilter - Set a filter to receive messages matching this filter
Discussion - Read the messages belonging to a discussion
Attachments - Read the attachments to a message
SetRead - Mark a message as read
Update - Update a message
Delete - Delete a message
GetMore - Get more, older messages

Messages from the Messages App

PostResult - Confirmation of a message being posted
ReadChatsInd - A chat destination is returned with this message
ReadChatsResults - Send as response to ReadChats as last message
ReadChatInd - A chat message is returned with this message
ReadChatResult - Send as response to ReadChat as last message
CreateFileBufferResult - Send when the file buffer is created
WriteGroupResult - Send when the group is created
ReadGroupsInd - A group is returned
ReadGroupsResult - Send as response to ReadGroups as last message
WriteMemberResult - Send when write member is complete
Add - Send as response to a SetFilter, to add a message to the display of messages matching the filter
SetFilterResult - Send as response to a SetFilter after the initial list of messages was sent (Add).
DiscussionResult - Send as response to Discussion after the list of messages was sent (Add).
AttachmentsResult - Send as response to Discussion after the list of messages was sent (Add).
SetReadResult - SetRead is complete
UpdateResult - Update complete
DeleteResult - Delete complete
GetMoreResult - GetMore complete

Objects - Objects used for this protocol

Post

{
    "src": string,
    "mt": "Post",
    "author": string,
    "filterSrc": string,
    "type": unsigned,
    "repliesTo": ulong64,
    "topic": string,
    "text": string,
    "notify": [string, ...],
    "tags": [string, ...],
    "attach": string
}

Post a message

author: The sip URI of the author of the message. If the author is from the local domain only the user part of the URI is used
filterSrc: Optionally a the src used by a messages display using SetFilter, in which context this message is posted, so that it does not need to be sent back as updated.
type: Optional type of the message. If no type is given 0 is assumed, which is a normal message. The type 1 is reserved for chat messages.
repliesTo: If set it refers to the id of another message and indicates that this message is a reply to this other message.
topic: Required. Indicates the SIP uri of the topic. Topics are used to structure the message storage and to control access. The sip URI of any App object, the user has given access to may be used as topic.
text: The text of the message coded as HTML.
notity: Array of SIP URIs of users, which shall be notified about this message
tags: Array of tags associated to this message.
attach: List of URL encoded URLs seperated by blank. From these URLs the files are read and stored as attachment on the message.

PostResult

{
    "src": string,
    "mt": "PostResult",
    "error": bool,
    "session": ulong64,
    "key": ulon64,
    "id": ulong64,
    "addsTo"; ulong64
}

Send as response to Post.

error: true indicates, that the post has failed
session, key: Session which can be used to POST attachments
id: The id of the new message
addsTo: The id of the discussion, this message belongs to

ReadChats

{
    "src": string,
    "mt": "ReadChats",
    "topic": string,
    "unread": bool
}

Read all destinations of the stored chat messages.

topic: The topic for which the messages are read. The topic is typically the SIP uri of the user, as chat messages are stored in the personal topic of the user.
unread: If true, chat destinations with an unread count only are returned.

ReadChatsInd

{
    "src": string,
    "mt": "ReadChatsInd",
    "sip": string,
    "dn": string,
    "grp": bool,
    "timestamp": ulong64,
    "unread": unsigned
}

Returns a chat destination

sip: SIP URI of the destinatio
dn: Display name of the destination
grp: If true the destination is a group
timestamp: The timestaamp of the last message to or from this destination
unread: Number of unread messages. Returned only if requested with the unread property in ReadChats

ReadChatsResult

{
    "src": string,
    "mt": "ReadChatsResult",
}

Send as response to ReadChats as last message

ReadChat

{
    "src": string,
    "mt": "ReadChat",
    "topic": string,
    "sip": string,
    "older": ulong64,
    "noind": bool,
    "count": unsigned,
    "session": ulong64,
    "user": string
}

Read all destinations of the stored chat messages.

topic: The topic from which messages are read. Typically the SIP URI of the user, as chat messages are stored in the personal topic of the user
sip: The chat destination
older: If present, only messages older then this timestamp are read
noind: If set no messages are returned, but only the unread status is cleared
count: The maximum number of messages to be read
session, user: Set by the PBX within the PbxMessages API to verify that the user is allowed to read these messages. So when using this message thru PbxMessages a Session needs to be established with the Session message and these properties should be omitted.

ReadChatInd

{
    "src": string,
    "mt": "ReadChatInd",
    "msg": msg
}

Returns a chat message

msg: An object containing the message

ReadChatResult

{
    "src": string,
    "mt": "ReadChatResult",
}

ReadChat is complete

CreateFileBuffer

{
    "src": string,
    "mt": "CreateFileBuffer",
    "name": string
}

Create a file buffer.

name: The file name. Only used for display purposes. No need to be unique in any way

CreateFileBufferResult

{
    "src": string,
    "mt": "CreateFileBufferResult",
    "id": ulong64,
    "url": string
}

Indicate the file buffer is create

id: Id of the buffer. Used to delete the file buffer
url: URL which can be used to POST the file to

WriteGroup

{
    "src": string,
    "mt": "WriteGroup",
    "id": ulong64,
    "dn": string,
    "user": string
}

Create/Update a group

id: The id of the group. If present, the message is used to update an existing group
dn: Display name of the group. If this is not present, the group is deleted
user: When using this Api thru PbxMessages, this property is added by the PBX

WriteGroupResult

{
    "src": string,
    "mt": "WriteGroupResult",
    "id": ulong64,
    "sip": string
}

Indicate the group is written

id: Id of the group
sip: SIP URI of the group. This can be used to send messages to the group.

ReadGroups

{
    "src": string,
    "mt": "ReadGroups",
    "user": string
}

Read all available groups

user: Added by the PBX, if this message was sent thru PbxMessages

ReadGroupsInd

{
    "src": string,
    "mt": "ReadGroupsInd",
    "id": ulong64,
    "sip": string
    "dn": string
}

Returns a group

id: The id of the group. Used for edit/delete
sip: The SIP URI of the group
dn: The display name of the group

ReadGroupsResult

{
    "src": string,
    "mt": "ReadGroupsResult",
}

ReadGroups is complete

WriteMember

{
    "src": string,
    "mt": "WriteMember",
    "id": ulong64,
    "grp": ulong64,
    "member": string,
    "admin": bool
}

Create/Update a group member

id: The id of the member. If present, the message is used to update an existing member.
grp: id of the group
member: SIP URI of the member
admin: If true this member is a group admin, who may edit the group and add/remove members

WriteMemberResult

{
    "src": string,
    "mt": "WriteMemberResult"
}

Indicate the member is written

SetFilter

{
    "src": string,
    "mt": "SetFilter",
    "count": unsigned,
    "addsTo": ulong64,
    "liked": bool,
    "filter": filter
}

Read all available groups

count: The maximum number of messages initially returned
addsTo: Only messages belonging to the discussion identified by this id are returned
liked: If set to true only messages which are liked by other users are returned.

Add

{
    "src": string,
    "mt": "Add",
    "addsTo": ulong64,
    "repliesTo": ulong64,
    "author": string,
    "dn": string,
    "topic": string,
    "text": string,
    "timestamp": ulong64,
    "rtimestamp": ulong64,
    "replies": unsigned,
    "likes": unsigned,
    "like": bool,
    "read": ulong64,
    "unread": unsigned
}

This message is sent to add a message to the display of messages matching to a given filter.

addsTo: The id of the discussion this message is assigned to.
repliesTo: The id of the message, this message is a reply to.
author: SIP URI of the author
dn: Display name of the author
topics: SIP URI of the topic
text: The message text
timestamp: The timestamp, when this message was posted
rtimestamp: The timestamp of the latest message belonging to the same discussion
replies: The number of replies to this message
likes: The number of likes of this message
like: true if liked by the user requesting this message
unread: Number of unread messages, which are posted as reply to this message.

SetFilterResult

{
    "src": string,
    "mt": "SetFilterResult"
}

Send as response to SetFilter, after the initial list of messages are sent.

Discussion

{
    "src": string,
    "mt": "Discussion",
    "discussion": ulong64,
    "count": unsigned
}

Read the messages belonging to a discussion

discussion: The id of the discussion as provided as addsTo property in an Add message
count/dt>: The maximum number of messages sent

DiscussionResult

{
    "src": string,
    "mt": "DiscussionResult"
}

Indicate that all requested messages are sent for the Discussion.

Attachments

{
    "src": string,
    "mt": "Attachments",
    "id": ulong64
}

Read the list of attachments of a message

id: The id of the message.

AttachmentsResult

{
    "src": string,
    "mt": "AttachmentsResult",
    "files": [file, ...]
}

Provides the list of attachments

files: An array of objects decribing a file

SetRead

{
    "src": string,
    "mt": "SetRead",
    "id": ulong64
}

Mark a message as read

id: The id of the message.

SetReadResult

{
    "src": string,
    "mt": "SetReadResult",
    "id": ulong64
}

SetRead complete

id: The id of the message.

Update

{
    "src": string,
    "mt": "Update",
    "id": ulong64,
    "text": string,
    "notify": [string, ...],
    "tags": [string, ...]
}

Update a message

id: The id of the message to be updated
text: The text of the message coded as HTML.
notity: Array of SIP URIs of users, which shall be notified about this message
tags: Array of tags associated to this message.

UpdateResult

{
    "src": string,
    "mt": "UpdateResult",
    "error": bool,
    "session": ulong64,
    "key": ulon64
}

Send as response to Update.

error: true indicates, that the post has failed
session, key: Session which can be used to POST attachments

Delete

{
    "src": string,
    "mt": "Delete",
    "id": ulong64
}

Delete a message

id: The id of the message.

DeleteResult

{
    "src": string,
    "mt": "DeleteResult",
    "error": bool
}

Delete complete

error: True if delete failed.

GetMore

{
    "src": string,
    "mt": "GetMore",
    "count": unsigned,
    "addsTo": ulong64,
    "liked": bool,
    "read": bool,
    "timestamp": ulong64,
    "id": id
}

Get more message related to a given filter. src is used to identify the filter in this case. The messages are sent with an Add message.

count: Maximum number of messages to be read
addsTo: Limit messages to the discussion identified by this
liked: Only liked messages
read: Include information about number of unread messages
timestamp: Messages older then this timestamp
id: Exclude the message identified by this id

GetMoreResult

{
    "src": string,
    "mt": "GetMoreResult"
}

GetMore complete

Objects

msg

{
    "id": ulong64,
    "author": string,
    "dn": string,
    "text": string,
    "timestamp": ulong64,
    "attached": [attach]
}

id: Id of the message. Used to delete or update
author: SIP URI of the author
dn: Display name of the author
text: The message text
timestamp: The timestamp of the message
attached: Array of objects decribing attachments.

attach

{
    "name": string,
    "url": string
}

name: The name of the attachment.
url: The URL which can be used to download the attachment.

filter

{
    "op": string,
    "topics": [string, ...],
    "tags": [string, ...],
    "authors": [string, ...],
    "notifies": [string, ...],
    "filters": [filter, ...]
}

op: The operation, which shall be used for the items in the filter. Default is "and", meaning that all items must match. The other available operation is "or".
topics: The topics, which should match. With an and operation, more then one topic does not make sense, because a message is only assigned to a single topic.
tags: Tags of the message, which should match
authors: The author, which should match. With an and operation, more then one author does not make sense, because a message only has one author.
notifies: SIP URIs of users, which are notified with this message
filters: List of filters which are combined to this filter with the same operation.

file

{
    "id": ulong64,
    "url": string,
    "name": string
}

id: The id of the file
url: An URL, which can be used to download the file in the context of the current session.
name: The name of the file. This is used for display purposes only.