Meetings and public rooms

Meetings

Meetings are a special type of conferences with multiple participants, with the following characteristics:

• They have a URL is which know by every participant

• They have a start and end date

• They have a predefined list of attendees (participants)

• They can be created via a REST API

A meeting is accessed via a URL which is only valid for that specific meeting. This is URL is called the “meeting URL” and its starting path can be configured in the service configuration.

The meetings service allows users to schedule meetings where participants can be invited. The service will take care of sending a meeting invitation via email or SMS. For every email meeting invitation, an ICS (calendar) file is also sent as an attachment. This calendar file includes the meeting’s name, its URL, organizer and start and end dates.

Capabilities required

Users that want to create and manage meetings must have the meetings capability assigned. If no meetings capability is assigned for a user, that user will be unable to schedule new meetings (but he still will be able to join someone else’s meetings).

Configuring the service

The service is configured via the wac.ini file. It contains a top-level entry named [meetings] that holds the service’s details.

Parameter	Default value	Comment
linkHost	(blank)	(mandatory) The host that will be used to build invitation’s links. If not given, the public IP of the Quobis AS will be used.
inviteMechanisms[]	(blank)	Notification mechanisms used to inform the user about the meeting creation or update. Can be “email”, “sms” or both.
linkFormat	(blank)	The format to use for the meeting URL. If unique, the meeting ID is used. If user the creator user’s alias is used.
templatePath	meetings/tpl	Where to find the sms and email template folders, relative to config/
shortenerToken	(blank)	Needed token to short links by using a Bitly account. If left blank, this feature won’t be used.
languagesTemplates	Available languages	Languages of the templates that will be used. Currently available ones are es, en and ca. By default, all will be used.
remindBefore	(blank)	If specified, the platform will send a reminder to every participant in the meeting N minutes before the start time. Additionally, a push notification is also sent, unconditionally
pstnExtension	(blank)	If specified, the meeting invitations will contain information in order to join the meeting through a regular phone call

A configuration example of the meetings section in the wac.ini is shown below:

[meetings]
linkHost = https://meetings.wac/
inviteMechanisms[] = email
inviteMechanisms[] = sms
; templatePath = meetings/tpl
; shortenerToken = '<ACCESS TOKEN>'
; languagesTemplates[] = es
; languagesTemplates[] = en
; remindBefore = 10
; pstnExtension = +34999999999

Email notifications

When creating a meeting and specifying a valid email in the request, email notifications are sent to participants. These emails are sent using the optional mailer service. Templates are used in order to specify how the content of the email will look like. You can refer to the details reading the Email service documentation.

SMS notifications

When creating a meeting and specifying a valid phone (MSISDN format) in the participant information, SMS invites are sent to participants. Those SMS are sent using the optional sendsms service. To define how the invites look like, templates are used. You can refer to the details reading the SMS notifications documentation.

Mobile push notifications

Meetings makes use of the PushNotifications service for sending out a reminder of the meeting using mobile providers’ push notifications service. The push payload will be:

{
    "type": "meeting-reminder",
    "info": {
            "id": meeting.id,
            "name": meeting.name
        }
}

Please note that above payload is not admin-configurable.

Templates definition

One important aspect of the meetings service is the ability to configure the contents of the meeting notifications sent to participants. The service allows to configure them depending on the channel used to send them (SMS or email, currently) and the meeting’s defined language. Templates are defined in the given templatePath from the configuration (relative to ./config) and are structured in the following manner (default values used):

config/
 +- meetings/
     +- tpl/
         +- email/
         |   +- en/
         |   |   +- {from,html,subject,text}.hbs
         |   +- es/
         |       +- {from,html,subject,text}.hbs
         +- sms/
             +- en/
             |   +- {from,text}.hbs
             +- es/
                 +- {from,text}.hbs

As you can see, the file hierarchy is defined by the mechanism used to send the meeting invitation (sms or email) and, underneath, the language of the meeting. This way we have full control on how to build the meeting invitation. Additionally, for each of the mechanism, each of its parts is described in one single file for increased flexibility. For instance, in the case of the SMS, the sender of the SMS can be defined in the from.hbs file while the contents of the SMS itself, are defined in the text.hbs file. In the case of the email we have more fields available, so there are more files to be customized. Particularly for email we have both text.hbs and html.hbs. This way the email will be properly rendered in all email readers, no matter if they support HTML or not. All the templates are defined using hbs files, which are Handlebars files. Handlebars is a third party library that helps users to define templates by separating the JavaScript code from the HTML or text template itself. See the linked website above for further information.

Apart from the standard Handlebars tags and syntax, we provide the formatDate and formatTime helpers to localize the date strings to the meeting invitation’s language. For example:

Your meeting {{ meeting.name }} will start on {{ formatDate
meeting.validSince }} at {{ formatTime meeting.validSince
hour="numeric" minute="numeric" hour12=false timeZone=”Europe/Madrid” timeZoneName="short" }}

You can see the full list of parameters that can be fed in the Intl documentation, under the options description. The data passed to the templates is the following:

party	The email address or phone number of the recipient
meeting.name	Name of the meeting.
meeting.user.id	Id of the user creating the meeting.
meeting.user.domain	Domain of the user creating the meeting.
meeting.user.username	Username of the user creating the meeting.
meeting.user.email	Email address of the user creating the meeting.
meeting.user.created	Timestamp of when the user creating the meeting was created.
meeting.user.lastLogin	Timestamp of when the user creating the meeting last logged in.
meeting.user.role	Role of the user creating the meeting.
meeting.user.capabilities[]	Capabilities of the user creating the meeting.
meeting.user.mobilePhone	Mobile phone number of the user creating the meeting.
meeting.user.landLineNumber	Number of the user creating the meeting.
meeting.user.alias	Alias of the user creating the meeting.
meeting.users[]	Ids of the users participating in the meeting.
meeting.language	Default language for the meeting.
meeting.participants[]	List of the participants in the meeting.
meeting.validSince	Timestamp of the date since which the meeting is available.
meeting.validUntil	Timestamp of the date until which the meeting URL is available.
meeting.url	URL of the meeting.
meeting.ddi.extension	Meeting DDI extension.

Please have a look at the provided templates in config/meetings/tpl to explore all the possibilities. A sample template may be:

<p>Hi {{ party }},<br/> you have been invited to a meeting via our communications platform.</p>
<p>To join us, please
<a href="{{ meeting.url}}">this link</a>
{{#if meeting.ddi.extension}} or dial {{meeting.ddi.extension}} and introduce the code{{meeting.ddi.pin}}{{/if}}.</p>
<p>If you cannot make it, please answer "No" to the RSVP.</p>
<p>Thanks!</p>

Calendar file

When sending a meeting invitation by email, a calendar file is attached. This file is formatted according to RFC-5545. The main fields to note that are included are: meeting’s starting and ending dates and times, meeting’s name, URL and organizer. The organizer is an RFC-defined value of the format Name <email@address.tld>. This service will use the meeting’s creator username as Name and its email address. If no email address is defined, a dummy none@example.org will be used.

Logs: known log messages

Error messages

• error: Invalid linkHost: the configuration parameter linkHost must be set to a valid URL. Do not include a trailing slash.

• error: Unable to send reminder for meeting: meetingId. Cause: msg: an error occurred when trying to send a meeting reminder using Push Notifications. Please review Push Notifications service’s logs.

• error: Error while processing onSessionRegistered: an error occurred when a user joined the meeting’s URL. The full error must be printed following this line, which will give you details about the precise failure.

• error: Error while processing onSessionDown: an error occurred when a user disconnected from the meeting. The full error must be printed following this line, which will give you details about the precise failure.

• error: Process onDeleteUser failed: an error occurred when a deleted user was removed from its meetings. The full error must be printed following this line, which will give you details about the precise failure.

Warning messages

• warn: unable to load resource for sms|email (msg): the service was unable to find the meeting invitation generator for the indicated mechanism. Probably the meeting invitation mechanism was misspelled or is not available.

• warn: Cannot send the meeting invitation, not available: a meeting invitation was not sent because the meeting created by the application was configured to do not send a meeting invitation from the sippo-server instance. This message is a confirmation that this server MUST NOT send a meeting invitation.

• warn: Cannot send meeting invitation by email: Email service not available: the meeting invitation cannot be sent by email because there’s no such service enabled.

• warn: Cannot send meeting invitation by sms: SMS service not available: the meeting invitation cannot be sent by SMS because there’s no such service enabled.

• warn: Failed to invite participant INVITE to meeting NAME(id): the service was unable to send the given meeting invitation.

• warn: The sms template TPL is too large. It will be sent several SMS by meeting: the configured template, named TPL is too large to fit one single SMS. It will span across several SMS. This message only appears when the languagesTemplates variable is set.

• warn: Field <FIELD> hasn't been used in TPL: if an optional field <FIELD> available for the configured template TPL has not been used, this warning is issued. This message only appears when the languagesTemplates variable is set.

Related REST API endpoints

All of the following endpoints MUST be authenticated with the proper Authorization header.

• GET /sapi/meetings

• POST /sapi/meetings

• GET /sapi/meetings/:id

• PUT /sapi/meetings/:id

• DELETE /sapi/meetings/:id

Public rooms

Public rooms are conferences that are always available and that don’t have a start or endtime. It’s URL is created “on the fly” and there user can access the conference room even if they are not authenticated. Public rooms are reachable under the following path: http://your-system-domain/c/any-identifier. Any identifier that follows this pattern will result in the setup of a conference room that is reachable by any user who knows this URL.

Warning

Public rooms can be a quite handy resource but the system administrator needs to take into account that anyone can use the service.