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.

Operations
Objects - Objects used for this protocol

Post

Request

{
    "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.

Result

{
    "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

Request

{
    "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.

Indications

{
    "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

Result

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

Send as response to ReadChats as last message

ReadChat

Request

{
    "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.

Indication

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

Returns a chat message

msg
An object containing the message

Result

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

ReadChat is complete

CreateFileBuffer

Request

{
    "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

Result

{
    "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

Request

{
    "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

Result

{
    "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

Request

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

Read all available groups

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

Indication

{
    "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

Result

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

ReadGroups is complete

WriteMember

Request

{
    "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

Result

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

Indicate the member is written

SetFilter

Request

{
    "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.

Indications

{
    "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.

Result

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

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

Discussion

Request

{
    "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

Result

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

Indicate that all requested messages are sent for the Discussion.

Attachments

Request

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

Read the list of attachments of a message

id
The id of the message.

Result

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

Provides the list of attachments

files
An array of objects decribing a file

SetRead

Request

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

Mark a message as read

id
The id of the message.

Result

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

SetRead complete

id
The id of the message.

Update

Request

{
    "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.

Result

{
    "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

Request

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

Delete a message

id
The id of the message.

Result

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

Delete complete

error
True if delete failed.

GetMore

Request

{
    "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

Result

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

GetMore complete

ReadTopics

This allows to read the currently available topics. The available topics depend on the currently logged in user and the App object which is used to access.

Request

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

Indications

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

For each available topic this message is sent.

id
The id of the topic. This id is present only for topics, which can be edited by this API. The topics defined by other Apps having access to this messages instance or by the user for the personal topic, the id is not present.
sip
The sip URI of the topic. This is usually the name of the App object. Subtopics may be added by this API. These Subtopics use <topic>>?<subtopic> as sip URI
dn
The display name of the topic. For the topics defined by other App objects, this is the Display Name of the App object in the PBX. For subtopics this can be any name.

Result

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

Sent after all topics are sent

WriteTopic

Can be used to add, update or delete subtopics. This means only topics, which are subtopics to the topics, which are defined by the App objects can be written

Request

{
    "src": string,
    "mt": "WriteTopic"
    "id": id,
    "sip": string,
    "dn": string
}
id
Must be provided when updating or deleting a topic
sip
The sip URI of a topic. If a topic is updated or deleted, the correct sip URI must be provided in addition to the id
dn
The display name of the topic. If no display name is provided, the topic is deleted.

Result

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

Writing of the topic is complete

id

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.