Architecture overview

The RCS platform consists of several components which use various interfaces and protocols to realize different RCS features. Details of their technical realization are described further in the document.

The solution is divided on the RCS backend (server side), RCS clients and additional web applications. The minimal configuration comprise of a Windows 2008 or 2013 server and Linux Ubuntu machine. The picture below depicts a setup in which there is one more server dedicated for the database which is a recommended approach for service providers.

The server side software include:

Applications running on Windows

• voipswitch SIP server – location server (Registrar), SIP B2BUA, Presence server
• VoipBox – a media server responsible for IVR, Voicemail, Transcoding, Recording
• VSServices – web services responsible for SMS communication, callback, DID management
• VUP – self-care user portal with voice and video communicator

Applications hosted on Linux

• EMCI and EMCD APIs (EMC) – RCS API, set of web methods responsible for the RCS features; EMCI is for internal communication between voipswitch, VUP, VSServices and EMCI API. It is server to server communication. EMCD provides set of methods which are called directly from the RCS clients.
• PUSH service – a service connecting the RCS API with supported PUSH mechanism (Apple, Google, Blackberry, Windows Phone)
• MariaDB (formerly MYSQL) – database storing the platform’s schemas

The diagram represents the components and their interconnections. 

The RCS clients connect to the edge servers using different interfaces depending on the type of the features. The functional division is following:  

HTTPS, Web Services:

• Provisioning (Sign Up, Log in)
• Multimedia sending
• Enhanced Address Book
• My Profile
• Avatars

SIP TLS

• Calling
• Instant Messaging
• Presence

Exemplary hardware configuration

The server side software can be installed in various configuration. Below is an exemplary setup with a pair of servers for the softswitch, EMC API and database. Only the web applications are on single server as their redundant copy can be installed on one of the softswitch’s servers.

The servers should have two network interfaces. One with public IP which will be used for communication with the softphones and the private IP address for connection with the other components such as EMC which contains several methods which are limited to the access from authorized IP addresses only.  Also the database server is hidden from the outside world and can be accessed only through the private interface.

The public addresses have to be associated with the FQDN (Fully Qualified Domain Name). You can assign freely any name of course, the prefixes used in the names on the diagram are only our suggestions. 

The web servers hosting the API and VUP must have an SSL certificate. It cannot be a self-signed one as it will fail on android softphone. By default we set a subdomain for the api server on our DNS and use our wild card certificate.  For the VUP however the domain should be related to your service and so should be the SSL certificate.

Initial configuration

This section describes the initial configuration. In further parts you can learn how to configure particular features.

Voipswitch

Voipswitch’s configuration is done through VSM (admin portal). The changes applied there are reflected in the database and taken into effect immediately.  Some of the settings are in the voipswitch_config.xml file, which is located in the Voipswitch’s main directory, usually Program files/Voipswitch. Changes in the file require restarting voipswitch application.

Below instruction pertains only to the RCS part of configuration. Detailed documentation on Voipswitch’s core functions is located here.

TLS SIP listener

The RCS clients communicates with voipswitch using encrypted SIP protocol. In order to enable the TLS listeners you have to add appropriate entries in the voipwitc_conifg.xml file:

<listener type="sip">

  <param name="ipaddr" value="1.2.3.4" />

  <param name="port" value="5061" />

  <param name="transport" value="tls-tcp" />

  <param name="tls-certificate" value="VPS.cert" />

</listener>

<listener type="registrar">

  <param name="ipaddr" value="1.2.3.4" />

  <param name="port" value="5061" />

  <param name="register-expiration" value="3600" />

  <param name="subscribe-expiration" value="3600" />

  <param name="transport" value="tls-tcp" />

</listener>

The above two entries are for the main SIP listener (calls, messages) and the SIP Registrar (Registration, Presence).

TLS requires a certificate used by its encryption procedures. In the tls-certificate value enter the name of the certificate file which should be located in the main voipswitch directory.

It is sufficient to define the certificate only for the main SIP listener, the Registrar will use the same settings.

TODO opisac jak sprawdzic czy jest cert? Co jak nie ma albo wygasl? Jak widac na vpsie ze listenere wystartowal screen.

STUN listener

The clients use STUN protocol to get information about its reflexive IP addresses which are then used in ICE mechanism for peer to peer calling and NAT traversal.

STUN is implemented in voipswitch application as a separate listener. As it is not enabled by default you have to check if the appropriate entry is added to the voipswitch_config.xml file.

<listener type="stun">

  <param name="ipaddr" value="1.2.3.4"/>

  <param name="port" value="3478"/>

</listener>

The RCS clients communicates with voipswitch using encrypted SIP protocol. In order to enable the TLS listeners you have to add appropriate entries in the voipwitc_conifg.xml file:

TODO jak sprawdzic czy diala? Screen z logs vpsa

Buddy list URL

This setting is in the voipswitch_config.xml file.  The service key is the name of the EMCI method which is called by the voipswitch every time when a client sends SUBSCRIBE requests. The method’s name is by default bl.ashx.

The ipaddr value should be the IP address of the EMCI server used for connection with voipswitch. It can be either public or private IP.

The method is secured by the username and password. TODO gdzie to ustawiac w EMCI?

<web_service>

    <param name="ipaddr" value="1.2.3.4"/> - IP WebApi

    <param name="port" value="81"/>

    <param name="username" value=""/>

    <param name="password" value=""/>

    <param name="service" value="bl.ashx"/>

</web_service>

EMCD

The RCS API responsible for serving the clients. Its configuration files are stored in the config files located at /var/www/emcd/ directory. The RCS functions related settings are in the AppSettings.config file. The database connections are defined in the DataBase.config file.

Changes made in these files require the Apache restart. To do it use the following command:

service apache2 restart

Database access

EMCD requires access to the following database schemas:

• api
• storage
• voipswitch

Connection strings for each schema have to be added to the DataBase.config. Below is an example.

<connectionStrings>

  <clear/>

  <add name="vps" connectionString="Server=192.168.1.2;

                         Database=voipswitch;

                         User ID=root;

                         Password=p455wrty;

                         Connection Timeout=60;

                         Pooling=true;

                         Min Pool Size=0;

                         Max Pool Size=100;

                         Connection Lifetime=0;

                         Connection Reset=true;

                         Old Guids=true"

  />

  <add name="api" connectionString="Server=localhost;

                         Database=api;

                         User ID=root;

                         Password=p455w0rD;

                         Connection Timeout=60;

                         Pooling=true;

                         Min Pool Size=0;

                         Max Pool Size=100;

                         Connection Lifetime=0;

                         Connection Reset=true;

                         Old Guids=true"

  />

  <add name="storage" connectionString="Server=localhost;

                         Database=storage;

                         User ID=root;

                         Password=p455w0rD;

                         Connection Timeout=60;

                         Pooling=true;

                         Min Pool Size=0;

                         Max Pool Size=50;

                         Connection Lifetime=0;

                         Connection Reset=true;

                         Old Guids=true"

  />

</connectionStrings>

Apache configuration

The web server used by the RCS platform is by default Apache2. Its configuration files are located at /etc/apache2/ directory.

The web server should be listening on port 81. The port is set in the /etc/apache2/ports.conf
Listen 81.

In the main configuration file apache2.conf the following section has to be present:

<Directory /var/www/>

 <------>Options Indexes FollowSymLinks

 <------>AllowOverride All

 <------>Require all granted

 </Directory>

TODO gdzie sie ustawia nazwe domeny? Pozostala konfiguracja?

dodajemy na końcu tego pliku linię ServerName localhost
włączamy moduły apache2
a2enmod ssl
a2enmod rewrite
usuwamy zbędny moduł w katalogu /etc/apache2/mods-enabled kasując pliki @mod_mono.conf i @mod_mono.load
upewnijcie się, że w katalogu mods-enabled znajdują się pliki @mod_mono_auto.conf i @mod_mono_auto.load
u siebie na komputerze otwieramy paczkę do rcs i edytujemy dwa pliki emc\apache2\emci.conf i emc\apache2\emcd.conf
w pliku emcd.conf podmieniamy domenę na klienta lub taką z wildcardem od Radka (*.hstsrv.net)
w pliku emci.conf podmieniamy ip_lin na ip linuxa a w linii 23 Allow from ip_win (ip_win podmieniamy na ip gdzie stoi vup)

SSL

Communication from the RCS clients to the EMCD API is encrypted using SSL. The SSL certificate files are located at /etc/apache2/ssl directory. Their names are based on the domain name used for the project:

domain.ca-bundle.crt
domain.key
domain.crt

The certificate can be provided by you but by default for new installation we use a wild card certificate for the domain *.hstsrv.net 

Communication with clients (system commands)

The EMCD API uses SIP MESSAGE requests to convey various commands to the RCS clients. Therefore the EMCD has to have an access to both VSServices API over https and voipswitch’s SIP listener. In order to check the SIP connectivity you can use telnet command from the EMCD linux server and try to connect to the IP address and port of the voipswitch SIP UDP listener. Please note that even though the clients use TLS for the internal communication we use SIP over UDP on the default port 5060. If connection fails you need to check your network settings (firewall) and voipswitch logs if it shows the UDP listener as started on the required IP and port.

The format of the body of the messages containing commands are the same regardless of the protocol used. In the case of http the EMCD sends http request with the body and recipient’s URI to the VSServices which in turn converts the message to SIP MESSAGE request. In the case when EMCD sends the message over SIP it is already in the SIP MESSAGE format.

At the moment EMCD uses VSServices for sending some types of system messages. This however will be deprecated in future and replaced fully by the SIP protocol.

The entry for the VSServices has to contain the valid URL and the username and password of the account used for system communication. 

Below is the entry for the SIP communication.

The account used by EMCD has to be created in voipswitch.clientsshared table. You should use the VSM and add new account in the Retail clients menu. Make sure that the assigned tariff contains allowed prefixes with zero rates so the account will not run out of money.

EMCI

The RCS API part used for internal communication with voipswitch and VSServices. It provides also the admin methods for integration with 3^rd party systems.

Its configuration files are stored in the config files located at /var/www/emci/ directory. The RCS functions related settings are in the AppSettings.config file. The database connections are defined in the DataBase.config file.

Changes made in these files require the Apache restart. To do it use the following command:

service apache2 restart

Database settings

The database config file is the same as for the EMCD, similarly the EMCI requires access to all the three schemas.

Allowed IPs

The access to the EMCI API should be limited to IP addresses of the authorized network elements. By default they are:

• VUP server
• Voipswitch server
• VSM server

TODO dodac gdzie to sie ustawia

Database

Database configuration is stored in the my.cnf file.

The following parameters have to be set:

sql-mode = ""

max_allowed_packet = 96M

innodb_file_per_table = 1

innodb_file_format = barracuda

The RCS platform uses the following schemas:

voipswitch schema

This is the core schema for the SIP server and billing applications.

api schema

RCS API’s schema, used for RCS features. It stores the Networks Address Book (NAB), mobile contacts and RCS client accounts.

The clients table contains social profile information such as public IDs, personal details and avatars. Also it keeps data on sign up attempts.

The api.clients are associated with voipswitch.clientsshared through the login field.

Seperating RCS clients from the voipswitch accounts allows for integrating the RCS API with 3^rd party softswitches.

storage schema

This schema is used for storing the attachments.

TODO dokonczyc

Logs

EMC APIs

Voipswitch

Accounts

RCS platform stores the client accounts in both api.clients and voipswitch.clientsshared tables.

Each record in the api.clients table contains data on a particular client. Among other columns the ones related to the cleint’s identity include:

• login
• username
• phone

The login field is used to associate the client’s record with the relevant record from the voipswitch.clientsshared table. The login value has to be the same as the login in the voipswitch.clientsshared.  The latter is used as a SIP login in sip communication.

This approach allows to detach the SIP login from a service username which is a public identity. Thus you can hide the SIP login increasing the security of the system.

In most cases however the SIP login is one of the public identities. This mode of RCS platform operation is called RCS generic mode and is set by default for new deployments. At the moment the supported public ID types are username and phone number, more IDs can be added in future.

The RCS generic mode has the main advantage that it is easier to implement in an existing system with a regular sip accounts based on SIP logins known to users and used for direct addressing the called party. In the case if there is an existing account in clientsshared only but not in the api.clients the relevant entry will be added to api.clients by the EMCD or EMCI API on the first client’s log in to either the softphone or the VUP (more about this process in the logging in section).

Whether the login will be a phone number or username depends on the method chosen during the sign up procedure.

Managing accounts using VSM

The accounts can be managed from the VSM. Make sure that in the VSM’s web.config file the appropriate key is added:

TODO

The RCS client accounts belong to the retail type which in the VSM are in the Clients\Retail clients menu. More information on the retail clients can be found in voipswitch’s documentation under the following link.

When the RCS generic mode is enabled the profile data in the Profile tab is retrieved from the api.clients.

From VSM you can also add new accounts but be careful as the VSM will create just a plain account without any predefined configuration. It is different when an account is created by the EMCD or EMCI API as they use a template configuration. If you have already an account created by the RCS API, for example from the softphone or VUP, you can create a template from it by clicking Save as template option.

Next, when adding a new account choose the option use template and chose the saved one. The new account will have all the settings, except for login and password, copied from the template.

SIP and Web password

The platform supports two types of password:

• SIP password – used only for SIP communication
• Access password – used for logging in to the softphones and VUP

You can decide whether both types should be used by ticking the Use web passwords checkbox in the VSM>Settings>General menu. If this checkbox is off the system will use the SIP passwords only.

The advantage of using a separate password for access to applications is security as the users will not know the SIP passwords which are sent from the EMCD to the dialer over an encrypted channel.

When a user enters username and access password during the logging in in the softphone the EMCD carries the authentication procedure and if successful sends the SIP login and SIP password back in response. The SIP credentials are then stored locally in the application.

Sign up – softphone applications

The sign up procedure creates new accounts in both api and voipswitch schemas. The sip login can be either a phone number or a username, depending on the sign up modes – either with phone number or with username.

The procedure is executed by the EMCD only for sign up with phone number made from the RCS softphones.  If sign up is made with the use of the VUP it is the EMCI which creates new account. Please note that sign up with username initiated from the softphone uses the VUP to complete the verification procedure.

The APIs create account based on parameters received from softphone or VUP and on the settings defined in the template section in the AppSettings.config file. An example of the account creation settings is given below:

<!--Account creation settings-->

  <add key="tariff" value="1"/>

  <add key="currency" value="1"/>

  <add key="tech_prefix" value="DP:int->;TP:int->"/>

  <add key="tariff_plan" value="false"/>

  <add key="tariff_plan_id" value="1"/>

  <add key="tariff_plan_value" value="600"/>

TODO – dokonczy opis, tez opisac TYPE keys. Dodac o initial balance..

Remember that the EMCI and EMCD uses separate AppSettings.config files from their respective directories. Hence you have to make sure that any changes done in one of the files should be also copied to the other.

Phone number registration

Sign up with the phone number allows to associate user’s GSM phone number with his RCS account. This feature is crucial as it is the base of the active address book functionality where existing phone numbers are matched with the RCS service users. Thanks to this a new client can immediately communicate with his phone contacts which are marked as the RCS.

Before a phone number is added to the RCS account the system has to verify the authenticity of the request, i.e. if the phone number really belongs to the person initiating the sign up procedure. The verification is based on sending an SMS with code (one time password) to the given phone number.

Sign up with the phone number is supported in the RCS mobile softphones and can be also enabled on the PC/MAC softphone. In the latter case the code will be sent to the phone number and then the user has to manually type the code from the SMS in the softphone.

In the first step a client has to enter his phone number into the appropriate field in the application’s signup screen. On android devices the number is obtained from the SIM card, however on some SIMs this function is forbidden. If the number can be read from the SIM it will be presented in the application.

After submitting the application sends a request to the EMCD register.ashx method. Besides the phone number the request carries information on the phone’s operating system and the device UDID.

The UDID and phone number pair will be then used to detect if future sign up or log in requests originate from the same device as in the initial registration.

UDID is a Unique Device Identifier and is generated based on device’s hardware parameters.

On receiving the request the EMCD checks if the phone number already exists in the api.clients table. If not a four digits code is generated and sent to the provided phone number via SMS.

The phone, UDID and other information that are sent with the registration request are stored in the dialer_requests table. The field sms_left is used for limiting the number of SMS sent to the same number, from the same device. By default the maximum number is set to 5. With each new SMS sent by the RCS API the number is decreased. When reaches zero the client request is declined with “Too many SMSes” error response which is shown in the application. To allow user for more SMS requests you will need to remove the records for his phone number from the dialer_requests table. Another option is to increase the number in the sms_left field.

Note: if a user already has an account and reinstalled the application the EMCD detects that the registration request comes from the same device-phone number pair and sends the SIP login and password back in the response, skipping the verification procedure.

Sending SMS with code

The EMCD uses an SMS provider for sending verification codes. The API communicates with the provider’s API directly, it does not use voipswitch and its SMS routes which are used for SMS communication from and to clients.

Therefore the relevant settings have to be added to the AppSettings.config file in the SMS API section.

By default EMCD is configured to use NEXMO as the SMS provider for verification process. If you want to use any other SMS provider you should follow the instruction here TODO dodac opis 3^rd party sms.

The first key allows to define the SMS text, the [CODE] is replaced by the actual code when SMS is being prepared. Change the string to reflect your service or app name.

Next three keys contain information obtained from your NEXMO account.

US DID (phone number) is required for SMS delivery in the USA. The number will be shown to the user as the sender number.

And the last key allows to define the sender name which will be shown to the user. Usually it will be your service name. This feature works only in the networks where alphanumeric sender names are allowed. In the USA it is not and hence we needed to get a US DID.

Delivery status

If you use NEXMO it provides delivery state for sent SMS. The softphone sends request to the ds.ashx method to check the current state. The EMCD response can contain a definite state, either success or error/failed or unknown/in progress state. In the latter case the application repeats the request up to several times until it gets a response with a definite state or the process timeouts.

Successful verification

On Android devices the softphone is capable of obtaining the code from the SMS. The moment it arrives the code is put in the code input field.  On other operating systems the user has to type the code manually.

Once the code is submitted the application sends a request again to the register.ashx method, this time with the code as a parameter.

The EMCD then creates a new account in voipswitch.clientsshared using the template from the AppSettings.config. The sip login is the phone number in the e164 format. A random password is generated.

 Next, an entry in the api.clients is added with the login being phone number, in addition the phone number is put in the phone field.

The EMCD completes the operation by sending the sip login and sip password back to the client. The softphone stores these credentials locally and uses them in subsequent requests to the API and in SIP communication.

The entry from the client requests is then…… TODO

Failure

The failure is when a user enters wrong code. The system allows for up to three attempts and then rejects further requests from the same device.

Also it may happen that the SMS has not been received by the user due to the route problem or some other reasons. After requesting the code the softphone’s screen shows a timer counting down 60 seconds, the send button is grayed out. When elapsed, the send button is enabled again. An exception can happen when the delivery state method will return an error, in such case the timer is hidden.

The number of SMS that can be requested by a user is limited, if the limit is reached the system will return an error Too many SMS. You can increase the number of attempts by changing the sms_left value in the api.dialer_requests table.

After the first request, if an error occurs or the time elapses, the user is presented with an option for the system to call him. There is a Call me button shown on the screen. After pressing the button a request is sent to the EMCD.

Callback

To trigger the callback the RCS client calls the EMCD register method again, this time with a parameter which tells EMCD to initiate the phone call instead.

The EMCD sends then a request to VSServices/callback.ashx. The full URL and other parameters are defined in the EMCD/AppSettings.config file:

The callback_user and callback_pass are username and password of a retail client type of account created on voipswitch for this purpose only, i.e. for making verification calls. You have to make sure that there is appropriate routing and tariff in place.

Besides the login and password the request contains two more parameters which are the source and destination numbers. 

http://domain/VSServices/callback.aspx?source=999999913456&dest=442081368111&login=test1&password=pass1x&type=0

The source number is the number defined in the Routing Plan which points to the IVR (VoipBox) scenario responsible for playing the code. The code itself is the last four digits from the source number. It is being added by EMCD in each request.

In the advanced tab there is a rule set which strips the first eight digits so the number that is passed to the Say verification code scenario comprises the code only.

The destination number parameter is the client’s phone number. The voipswitch will call it through a PSTN carrier (gateway) defined in Destinations menu. When a user answers the call he will hear the IVR saying the code, it is being repeated twice before the call is disconnected.

Flow diagram

Username registration

Sign up with username is based on verification via email. A new user has to propose his username which is also called a service ID (for example Vippie ID), then create a password and provide his email address. In addition the country code information is collected, a user has to choose his country from the drop down list, by default it is set to the country code obtained from the SIM card (if available). The country code is needed for further phone numbers synchronization. These parameters are sent to the register.ashx method. The EMCD first checks if the ID is available (not used by other user) and if so it will add the request to the dialer_requests table, then will generate verification code and send an activation email to the address provided in the request.

Email template

The activation email is composed using the template file located in the var/www/emcd directory. The name of the template file is defined in the AppSettings.config file in the following section:

<!--Mail settings - Account Activation-->

  <add key="account_activation_mail_subject" value="Using XXX - confirm your registration"/>

  <add key="account_activation_mail_body_file" value="/var/www/emcd/aa.txt"/>

  <add key="account_activation_mail_body_html" value="true"/>

  <add key="account_activation_mail_display_name" value=""/>

  <add key="account_activation_mail_bcc" value=""/>

  <add key="account_activation_mail_reply_to" value=""/>

The key name is “account activation mail body file”.

The other keys allow to define other email settings like:

• subject – change the XXX to your application name
• html or plain text
• bcc email
• reply to address

Here is the default file, you can freely change its content. TODO

This is important to put the proper URL of the VUP in the body of the email in the template. The activation link there is the only place where the VUP URL is set.

SMTP settings

The SMTP server for sending email has to be defined in the AppSettings.config file in the EMCD directory:

<!--SMTP Settings-->

  <add key="smtp_host" value="ip"/>

  <add key="smtp_port" value="25"/>

  <add key="smtp_from" value=""/>

  <add key="smtp_user" value=""/>

  <add key="smtp_pass" value=""/>

  <add key="smtp_ssl" value="true"/>

Verification procedure

The purpose of the activation email is to verify if the address really belongs to the user before creating new account.

The EMCD composes an email and generates a token which is then appended to the link defined in the template. The EMCD first creates a code – same as with the phone number registration, which is stored along with other information sent by the softphone, in the dialer_requests table. Next, based on the code and some other parameters a token is generated.

When the receiver of the email clicks on the link the VUP is opened in a browser. Depends on the result – whether the clicked link was valid or not an appropriate VUP’s page will appear. If the verification is correct the page will show a message that the account has been successfully activated.

The VUP in fact only acts as an intermediary, on receiving the token after the link is clicked, the VUP passes it to the EMCI provisioning.doRegister method. Remember that the VUP is the only element accessible from a browser, hence the link points to the VUP and not to the EMCI or EMCD directly.

The EMCI decodes the token and compares the code and other parameters with the dialer_requests entry. If all agrees a new account is created and appropriate response is sent back to the VUP which in turn shows a page with either a success or failure text.

At the moment the user submitted the username, password and email the softphone shows the log in screen with an additional instruction to wait for the email in order to activate account. If the Log in button is pressed before a message is shown indicating that the account is not active yet.

When the user clicks the link and gets the “account created successfully” message he can now press Log in button.

On successful authentication the softphone receives the SIP login and password from the EMCD. The credentials are then stored locally, user does not have to enter them again.

Flow diagram

Account currency

TODO

Logging in

The system supports multiple devices under one account. A user can create an account on one mobile device and then log in to another mobile device, PC softphone or the VUP using the same account.

In order to log in the user has to provide one of the public IDs, either a phone number or username and password.

If the user created the account on the mobile phone with the phone number then he has to create a password in the My Profile menu.

If the initial registration was via email then the password is already set.

From the My Profile menu a user can also change the password.

The username or phone number and password pair is sent to the EMCD’s method authorize.ashx. The api looks for the provided public ID in the api.clients.phone and api.clients.username. If found it then retrieve the api.clients.login value which is the login in the voipswitch.clientsshared table and gets the password for that login. If the password agrees with the provided by the user then the authentication is successful. The SIP login and password is sent back in the response to the client. This pair will be stored locally by the application until the user logs out from the app.

Log in option on mobile RCS clients

On the first screen of the mobile client are two options – sign up and log in. When Log in is chosen a screen appears asking for entering phone number or username. By default a user has to enter his password even though the selected public ID is phone number.  

Another option, which can be enabled on request during the customization of the RCS clients is that a user enters phone number used during the registration. The EMCD sends then an SMS with code to that number. The user will have to type the code received on another phone into the one he wants to log in.

Forget password

Both in the mobile and desktop clients there is a “forget password” link on the Log in screen. The link is pointing to the VUP URL for example https://yourdomain.com/vup/resetpassword

The page shows a form where a user should enter his username or phone number. The system will then send an email containing a link with a token to the email address associated with the account.

The email is composed based on the settings from the EMCI/AppSettings.config file:

<!--Mail settings - Forgot password-->

  <add key="forgot_password_mail_subject" value="Using XXX - Reset password"/>

  <add key="forgot_password_mail_body_file" value="/var/www/emcd/forget_password.html"/>

  <add key="forgot_password_mail_body_html" value="true"/>

  <add key="forgot_password_mail_display_name" value=""/>

  <add key="forgot_password_mail_bcc" value=""/>

  <add key="forgot_password_mail_reply_to" value=""/>

The body file contains the template. There should be the URL to which the EMCI will add the part with token. Below is an example.

[USER_NAME]

To restore password on your account click here

After that you will be able to log in.

The link’s URL is https://yourdomain.com/VUP/ChangePassword?code=[CODE]

Once a user clicks on the link in email a browser will open the ChangePassword page with the token as a parameter. A form will appear where a user can set a new password.

My profile

The  My profile menu stores personal information which include:

• First name
• Last name
• Phone number
• Service ID
• Email
• Sex
• Birthday
• City
• Country
• Time zone
• Language (optional)

All these data are stored in the api.clients table. When the screen opens it connects to the EMCD/  profile.ashx and retrieves the data from there. Any changes are also uploaded to the EMCD. The exceptions are service ID which can be created only once and cannot be changed later. When a user creates new service ID (username) from the My Profile screen the softphone will call un.ashx to add the ID to the database. The EMCD will first check if the ID is available.

Changing password

There is one more field in the My Profile screen which is password. The password is stored in the voipswitch.clientsshared table and in fact is not retrieved from EMCD with the other data. It is also never shown to the user who can only change it from the My Profile screen. When doing so the softphone calls the scp.ashx with the newly entered password as the parameter.

Adding phone number

Avatar

Avatars for the RCS contacts are downloaded by the client application just after a contact has been marked as an RCS. The application connect to the EMC API method responsible for returning avatar for the requested username.  Once downloaded avatar file is then stored on the device.

On receiving a Notify packet with a presence document with a status of either particular user or the whole list of watched entities the client application parses the body part of the document where one of the parameter is a timestamp of the last update of user’s avatar. If the timestamp represents a newer date than the one associated to the downloaded avatar the client will call the API in order to download the latest version of the file.

A user can make a new avatar directly using the phone’s camera or choose a picture from gallery. The picture is then uploaded to the EMCD/avatar.ashx

Multidevice support

            SIP instances

Contacts

Enhanced Address Book (EAB) is the essential part of RCS applications. Its main feature is to show who from the Contacts is an RCS user. This information is shown in the main Contacts list in a form of a special icon. When a user clicks the RCS action icon a set of new icons will appear for the voice only call, video call and chat.

The actions refer only to over IP services among ONNET numbers (i.e. other RCS users). If a user wants to make a call or send an SMS to a GSM number he has to click on the contact and open the contact details view where the paid call and SMS options are.  

The Contact list supports following functions:

• search contact 
• filters: Vippie users only, all contacts, favorites
• add new contact 

Mobile versions of the RCS clients use the native address book (aka Terminal Address Book) as the source of Contacts. The app keeps a copy of the native contacts locally. The contacts data are extended by additional information related to the RCS service. In order to learn who from the native Contacts is already an RCS service user, the app uploads the Contacts’ phone numbers and names to the EMCD. The method used is contacts.ashx. The data are stored in the api.contacts table.

Before the phone numbers are uploaded the softphones normalize their formats to E164, i.e. the country code and number. Without any leading international prefixes.

Number normalization

The phone numbers are normalized according to the following rules, similarly to the rules applied by the GSM operators:

• international calling:
  • Prefix 00 or + at the beginning of a number is stripped e.g. +442085676789 will become 442085676789
  • Prefix 011 at the beginning of a number is stripped. This prefix is used in USA
  • Single prefix 0 (not double 0 which is in the first rule) is replaced by the country code associated with the user. For example number 0600345698 from Contacts of a user with country code 48 Poland will be changed to 48600345698 and in this form sent to the EMCD
• local calling
  • Numbers stored in the local phone Contacts without any of the prefixes mentioned above are treated as local numbers. Before they are sent to the EMCD the softphone adds the user’s country code in front, e.g. number stored as 600456789 will be changed to 48600456789 where 48 is the Poland country code – this is of course for the user who registered with Poland phone number.

The phone numbers used during a registration are also stored in E164 format which allows for easier matching them with the Contacts numbers.

RCS contacts discovery

After normalization and upload procedure the EMCD checks which from the uploaded phone numbers belong to other Vippie users. A user’s registered phone number is stored in api.clients.phone field. The EMCD compares phone numbers from contacts with the numbers stored in phone field in clients table. When a match is found the record in contacts is updated with value 1 in vippie field.  

The server keeps the copy of the phone contacts and performs user discovery procedures whenever a new user joins the service. Thus a Vippie user can immediately receive a notification when only his buddy registered in Vippie service.

The server version of the Address Book must be kept in sync with terminal address book (TAB). Therefore every change on the device must be detected and uploaded to the server. When a change is done from within the app the change should be uploaded immediately (assuming internet connection is present). If this is not possible the record has to be kept in a queue and be sent once the connection to the server is restored. When a change is done from some other application the application should upload the record as soon as it detects the change. There is also a special procedure implemented which periodically checks the consistency of both copies.

When the application sends the address book entries to the EMCD contacts.ashx it gets a response with a token. Within next several seconds the application calls the contacts method with the token as a parameter. The EMCD responds with a pending status or with the list of entries which are registered in the platform that is other RCS users. If the address book has a significant size the application divides it in smaller parts and sends one by one.

The server side procedures search the RCS database asynchronously and every found item (an RCS user associated with one of the uploaded items) is then added to the queue which is in turn queried by the client.

When the discovery procedure completes the application shows the RCS capable contacts marked with a special icon and the presence status information.

The list of RCS contacts returned by EMCD comprises pairs of logins and phone numbers. The logins can be same as phone numbers if user registered with the phone number. In other cases they can be usernames or as in non-generic mode, sequential numbers. Therefore the RCS client has to keep the association between phone number from contacts and its login.

New RCS contact

When the EMCD registers a new phone number (with new user registration or when an existing user adds a phone number) it runs a look up for occurrences of the phone number in other users address books. When a match is found in the api.contacts the EMCD sets the api.contacts.vippie field to 1 which denotes that the number is RCS capable and notify the user who owns the entry. The user’s application upon receiving the message marks the contact in the address book as RCS.

The command to set a contact as RCS is sent to the client via SIP MESSAGE, same way as chat messages. The message carrier a system command Contacts add in its body which is processed by the application but not shown to the user. Also the messages which deliver system commands are not sent over PUSH when user is offline. Instead they are put into the deferred messages table and delivered when the user comes online.

The format of the Contacts add command is following:

The example shows the command telling the app to add new user under the certain contact from the TAB. The contact is recognized based on the id and the phone number.  

Parameters:

• id - a contact's id (taken from the TAB and uploaded to the server)
• n - phone number
• l - login (SIP username)
• os - device operating system 

On receiving the Contacts add command the app must store the relevant info in the local copy of the TAB. 

The Contacts add command is sent to voipswitch through VSServices/sendsms.ashx. Its configuration is described in TODO dodac link do Communication with clients. The use of sendsms.ashx for this function will be deprecated in near future and will be replaced by direct SIP communication between EMCD and voipswitch as it takes place for other system commands already.

The procedure is repeated for all occurrences of the number in api.contacts table, i.e. for each user’s phone book.

New user joined Vippie notification

When a new user joins the service the system besides the system command generates also a text message which is sent to all the users which have the new account in their Contacts. The message is sent on behalf of the user, with its login and display name in the FROM header. Thus a recipient can see the name as it is defined in his Contacts and can respond to the message directly or initiate a call to the sender.

The “User joined” message is sent by EMCD using direct SIP communication with voipswitch. If the recipient is offline the message will be sent using PUSH notification like any other chat message.

If the message does not come even if you have the newly registered number in your contacts you should check the SIP client settings in the EMCD/AppSettings.config. Next, check connectivity from the EMCD server to voipswitch using SIP over UDP which is used for internal server to server communication.

Removing RCS association from a contact

When a user decides to remove his account and stop using the service the EMCD searches for his phone number in all other user's phone books in api.contacts. When a match is found the server sends a system message with Contacts del command so that the application can update the local contacts accordingly.

The format of the Contacts add command is following:

When the RCS client receives this command it should remove the RCS login assigned to the

contact item with the received id and number.

Flow diagram

Find friends

This function allows to look for other RCS users by the following criteria:

• username
• first name, last name
• email

The client application sends the parameters to the EMCD/search.ashx. When the match or matches are found the list of RCS users is sent back in response and displayed in the application screen.

Presence

Presence is based on SIP SIMPLE framework with support for the Resource List. The RCS client connects to the voipswitch, which role in this case is a presence server, and subscribes to his buddy list. The buddies, in the RCS services, are the RCS users from the phone contacts. The application does not send the whole list of RCS contacts to the server as this information is already stored in the api database. Instead it sends only subscribe request to the resource list and then the voipswitch obtains the buddies from the EMCI.  The URL of the EMCI/bl.ashx is defined in the “web service” section in the voipswitch_conifg.xml file (todo read more here).

The EMCI returns the list of logins with information who supports PUSH notification. The voipswitch checks the presence document for each of the logins and creates the Notify message which will be send over SIP to the subscriber. The role of the voipswitch’s presence service is also to monitor the changes in the presence document of each watched buddy and sending Notify messages whenever a change occurs.

The presence document is updated on receiving Publish request from a client with a new status. The application sends Publish when a user changes his status description in My profile or when the application is being closed or opened. When closed it sends Publish with Closed status or on PUSH -half circle icon, when PUSH is supported. When the application opens it sends Publish with Open status – full circle icon in green color.

The presence documents are stored in voipswitch.presence_publications table.

When all the RCS contacts are shown as offline – full gray circle, check if there is connectivity between voipswitch and EMCI/bl.ashx

Calling

A call is initiated by sending an INVITE request. For user to user calls the request line URI will contain the SIP login of the user associated with the called contact item. The contact item can be a phone number or a username (service ID) both of which are public IDs of a called RCS user but not necessarily they are equal to the user’s SIP login. RCS users can sign up with username or phone number and therefore their logins can be either. Also in non-generic RCS mode the SIP logins are different from both the username and phone number as they are sequential numbers.

When the INVITE is composed the user part of the URI is the login, not public ID.

When the call is sent to PSTN numbers the user part of the URI will be the phone number.

ONNET and OFFNET

Calls are divided into two types:

• ONNET – within the network, in the OTT service it means calls made over internet, among the users of the same service, this type of calls is free
• OFFNET – outside the network, in the case of OTT it will be calls to voice termination carriers which terminate calls to PSTN (landline or mobile) networks

The RCS clients can recognize when the call is ONNET or OFFNET as the softphone’s UI is designed in such a way that a user can decide whether he wants to connect to another RCS user directly over internet or to call the user’s phone number over PSTN network.

If a contact is not RCS user there are only “paid call” and “paid SMS” icons available, allowing only for OFFNET communication.

Calls to PSTN are realized through the gateways (carriers) defined in the Destinations menu in VSM. More on configuring the routing and gateways you can find in voipswitch documentation in a dedicated chapter TODO link.

The RCS client uses two separate SIP accounts with different configuration for each of the types. It may also use different SIP login and password pairs which can be necessary in some scenarios, for example when the OFFNET traffic requires 3^rd party billing (read more in the Integration chapter). In general the credentials are the same. The difference is in their configuration.

• ONNET configuration – calls are made with ICE, SRTP encryption, audio codecs OPUS, video codec vp8
• OFFNET configuration – ICE is disabled, no encryption, audio codecs: g729, g711 (other can be added on request)

The difference in offered codecs is because at the moment OPUS is not supported by the termination carriers. The most widespread codec is still g729. The set of codecs can be narrowed on the gateway definition in the VSM.

Prefixes

In order to differentiate the ONNET and OFFNET traffic and to be able to set a separate routing for each, there is a special prefix being added to one of the types. Which one depends on particular deployment but in general the prefix int is used to distinguish the OFFNET calls and messages.

When a call is made to an OFFNET number the softphones adds int to the number before it is sent to voipswitch. For example if the number is 44208745690  (after normalization to E164 format), the number will be changed to int44208745690.

If the number 44208745690 belongs to the RCS contact it may be also the user’s SIP login[1]. For ONNET call the number will come to voipswitch as it is, without a prefix. If we did not have a prefix for OFFNET there would be no way of differentiating the routing.

By default, in RCS deployments, all accounts have the dialing plan rule set to

DP:int->  OR onnet

This rule makes voipswitch strip the int prefix if exists, otherwise add onnet prefix to the number. Dialing plan has an entry for onnet which points to the Retail client/User lookup function (in older VSM versions it is Map to username).

The lookup function search for users with login equal the phone number. If there is a match the call is directed to that user.

OFFNET calls, as they come with prefix int, are stripped the int first so they are in E164 format. Then the voipswitch looks for entries for matching prefixed in the dialing plan.

You can wonder why the int is added to OFFNET on the app and then stripped on the server. Instead we could add “onnet” prefix to ONNET calls so that we would not need any modification on the voipswitch side. It is true and so we can do now, however in the past we used the approach with int and had a separate dialing plan entries beginning with int. All other entries were for ONNET. As we introduced alphanumeric logins the approach became difficult to manage as it required entries in the dialing plan for all possible characters. To eliminate this need we added the dialing plan rule which now groups all ONNET calls under single entry in the dialing plan. Adding the rule does not require any changes in the softphones which can be problematic for existing services.

Local dialing plan

The RCS platform uses the client based routing, which is also referred to as local dialing plan. The RCS client uses the routing plan to determine its location server (home server) and to determine the servicing server for calls and messages addressed to particular user.

The home server is a voipswitch to which the client registers. Also by default all requests related to presence i.e. Publish and Subscribe are sent to the same server.

The servicing server is a voipswitch to which INVITE and MESSAGE requests addressed to certain SIP URI in the request line are sent to. Depending on the URI the requests can be sent to different servers. In a single server deployment one voipswitch can act as both home server and servicing server. In a cluster solution you can split the traffic among many servers using the client routing.

Finding the home server

When the RCS client starts first downloads the routing plan from the EMCD. The EMCD reads the plan’s entries from the api.local_dialing_plan table and creates a json list which consists of one or more records with two columns – prefix and SIP server FQDN.

The RCS client looks for the entry with prefix value best matching the user’s SIP login. When the entry is found the respective SIP server is then used as a home server. The client will store this information and will keep refreshing the local dialing plan periodically. Also when registration fails it will try to update the list from EMCD.

Routing calls and messages

Before the INVITE request is sent the client tries to find best matching entry in the local dialing plan for the user part of the request line URI. For ONNET calls it will be the SIP login of the called user. If we use special prefix for onnet calls then the SIP login will be preceded by the prefix in the URI. This procedure is repeated for every call. If you call user A the client will find a matching route, if then you call user B the system will look for a route again, this time for user B.

Thus you can divide the traffic among many servers. Or you can have the servers in different locations and distribute the traffic based on the country code – in the case when logins are phone numbers.

Example:

Local dialing plan

If a user has a login which is a phone number and it starts with 44 the application will register to SIP server with address sip1.company.com

If the user wants to call another user with SIP login starting with 3 for example a French number, the INVITE will be sent directly to the server sip2.company.com

OFFNET calls are configured to be sent with prefix int, therefore the application looks for the prefix beginning with int and finds the server offnet.company.com

If you have one server for all prefixes enough is just to create entries from 1 to 9 and point to the same address.

Note: if you allow for alphanumeric SIP logins (usernames) you should use a prefix for ONNET calls. For example a prefix “onnet” which will be added to each outgoing SIP login. Before placing a call the softphone will look for a prefix beginning with onnet, thus you can avoid adding all the entries for all allowed characters. The example below shows a dialing plan with two prefixes only.

Support for ICE

ICE is supported for ONNET calls only, for OFFNET it is disabled. The ICE framework provides a mechanism for finding the most efficient media path. The preference is set for direct peer to peer calls between users.

 Call request is sent from client A to B using SIP through voipswitch. When answered by B both dialers start sending packets to one another trying direct path – to their NATs IP addresses, and the path via media relay server. In most cases (more than 95% of NATs) the peer to peer path will be established successfully. If for some reasons the direct path cannot be established the ICE framework will seamlessly connect through the server.

The ICE framework comprises a set of mechanisms which not only help to find the best route but also are the most efficient in NAT traversing. ICE has been selected also by the WebRTC and is now obligatory in their standard.

In our RCS clients the media relay server can be either voipswitch or a TURN server configured in the clients explicitly. It depends only on your deployment plan.

In the case when voipswitch is used as media relay server the RCS client A gathers only reflexive (IP of NAT as seen from the server side) and host ICE candidates. It does not establish any binding with server. When the ICE candidates are sent in SDP in the INVITE request the voipswitch checks the SDP and if the ICE relay candidate is missing it adds own IP address and port as the relay candidate which is sent to client B. The same with 200 OK from B, before it is forwarded to A the relay voipswitch candidate is added.

Another method is to use separate TURN server. In this case the softphone has to have the IP or FQDN of TURN server added to its settings. This configuration has to be done on the client application before it is compiled. When TURN is used the client during ICE candidates gathering procedure sends binding request to the TURN server which responds with IP and port which should be passed to B as the relay candidate.

Signalling TLS

The RCS clients use SIP over TLS which guarantees high level of encryption. Make sure that the TLS listener is up and running on voipswitch. If it is not started the softphones will not register.

The TLS configuration is described here TODO dac link.

CLI – FROM header

The FROM header is composed as in the example below:

From: “44208765444” <sip:44208765444@10.0.0.2>

The display name is the phone number, the user part of the SIP URI is the SIP login. In this example it is a phone number but can be also a service ID or non-generic RCS login.

For ONNET calls the display name can be a username. The called client will always show the Display Name on the user interface. The SIP login is hidden.

In the OFFNET calling PSTN gateways often ignore Display Name and present the SIP URI’s user part as the caller ID. If you allow logins different than phone numbers you will have to make sure they are replaced with Display Name before leaving voipswitch. Otherwise the receiver will see the username or unknown as the CLI. To use the Display Name instead TODO field rules…. 

Instant messaging

Instant messaging is realized through the SIP SIMPLE. The addressing mechanism is based on the local dialing plan the same way as it is used for calling (todo link).

When a user sends a message to another user a SIP MESSAGE request is created with the text of the message in its body. The To header contain the SIP login of the user B (addressee). The FROM header is constructed similarly as for INVITE. The softphones always show the Display Name for incoming messages, unless the user is added to the Contacts already, then the Contact name is shown.

On voipswitch the routing for ONNET messages is same as for calls, it goes through the entry in the dialing plan which points to “look up” function with Retail client type.

The MESSAGE request is delivered to the user B immediately if B is online. Its copy is saved to the sms_inbox table in voipswitch scheme with status field set to (TODO ile?)

Deferred messages

When the B is offline the message is stored into the sms_inbox table with status = todo ?. When the softphone comes online and registers to voipswitch, all the messages with status …. Are sent to the client. In addition, when client is offline, the message’s body or at least part of it is sent to the client over PUSH notification.

OFFNET SMS

When a new message arrives voipswitch checks if there is an entry in the dialing plan, for the destination number and if the entry is pointing to the user lookup (Retail clients). If there is then the message is sent to the user. In all other cases the message is sent from voipswitch to VSServices\sms_send.ashx

SMS dialing plan configuration is described in voipswitch documentation here. TODO dodac link

Sending multimedia

Supported multimedia include:

• Picture
• Short video
• Audio note

The file sharing works only among the service users, does not work for OFFNET numbers.

The process is as follows:

1. In a chat window a user creates a file to be sent, either selecting exsiting file or making new one
2. The file is first uploaded over https to the EMCD, as a request’s parameter the list of recipients is sent
3. The EMCD copies the received file to the database along with the list of recipients
4. The EMCD confirms successful upload by sending a file identifier back to the client
5. The client sends a SIP MESSAGE with a special system command which contains information on the type of the file and its identifier
6. Receiving client displays information on the received file (type) or shows a thumbnail (for pictures)
7. When the recipient taps on the message the application connects to the EMCD and requests the file with given identifier. The file is returned to the application.
8. Once the file is downloaded the EMCD checks if there are more addressee who has not downloaded yet, if not the file is removed. If there are the file is kept until is download by all addresses

All files are stored in the storage schema in the database. The schema can be located on a different database server. Connection string to this schema is defined in the /var/www/emcd/DataBase.config i /var/www/emci/DataBase.config

The files are sent to the EMCD/upload.ashx. An example request looks as follows:

The EMCD checks the Content-Type parameter from the request header. The supported types include:

• image/gif, image/jpeg, image/png
• audio/mpeg, audio/aiff, audio/3gpp, audio/wav, audio/amr
• video/mp4, video/quicktime, video/x-m4v, video/3gpp

The files are stored in the database in storage scheme. The maximal size of a sent file is defined in the /etc/mysql/my.cnf   in max_allowed_packet   parameter, by default its value is 96M.

On the receiver side the application sends request to the EMCD/download.ashx

The parameters will include the login, the file’s identifier and optionally for pictures there is width and height parameters which let the application to request a smaller version of the original file to be displayed as a thumbnail. In this case, when width and height is specified, the EMCD will not mark the file as downloaded.

As the file sharing is based on chat messages it inherits all its features such as deferred messages and PUSH.

Share location

The location is sent through the SIP MESSAGE with a special system command which instructs the recipient’s application to display the received location on a map. The location is encoded in the GPS coordinates.

The file sharing works only among the service users, does not work for OFFNET numbers.

Group chat

PUSH

PUSH is a service responsible for delivery of notifications to a mobile device and is natively supported by operating systems. Voipswitch RCS platform supports following PUSH services:

• Apple APNS
• Android GCM
• Windows Phone
• Blackberry

The purpose of using PUSH notifications in the RCS platform is to ensure communication with the client. When the RCS application is open it registers to the SIP server so all SIP requests can be delivered directly. When the application is closed or for some reason lost registration with the server the only way of communicating with client is to send him PUSH notification. Also in the Windows Phone version when the application goes to background it cannot keep any network connectivity with the server and therefore it always uses PUSH when not in foreground.

PUSH notification types

The payload of the PUSH notification contains information about the type of notification which can be:

• Text message
• Voicemail
• Incoming call
• Missed call
• Attachment – picture
• Attachment –video
• Attachment – audio

The type lets the PUSH to be formatted in special way, for example showing proper icon from the application resources.

In addition the payload carries information about the calling party display name, calling party login and the timestamp of the event. For the incoming call there is also the callID of the parked  call. For the text message the payload delivers the message’s body or its excerpt only if the length of the entire text is bigger than 40 characters.

On receiving the PUSH notification there are two paths how it is  handled by a device which varies between Android and iOS.

On Android the notification is intercepted by the application. The system starts the application which can process the payload. This approach allows for full control on the app behaviour and allows for retaining similar user experience as when receiving a call over SIP.

On iOS the system intercepts the notification and displays a popup which shows CallerID and a short text (e.g. “incoming call from %contact_name”). A user has to manually accept (answer the call) or decline. When accepted the notification event is passed to the application. The contact name is retrived by the EMCI from the mobile contacts stored in the database before sending PUSH.

On the first start the RCS application connects to the respective PUSH service and obtains a token used for identifying the device in the PUSH service. The token is sent to the EMCD/pn.ashx method. Every time the application detects that the token has changed it will send the new token to the EMCD again. The token is stored in the voipswitch.push_device_token table. The token is always associated with the device’s instance from the voipswitch.aa_ue_instance which represents a particular user’s device. 

Incoming call

When a SIP INVITE request is routed to a user which is not registered at the moment or there has not been any response for 3 seconds, the voipswitch looks up the callee instances from the aa_ue_instance table and checks if there is at least one token associated with any of the instances. If there is, a request is sent over http to the EMCI/emc.ashx. The request contains all relevant information about the call such as the caller login, display name, destination URI and callID of the pending call. From the moment the request is sent to the EMCI the voipswitch waits until timeout, meanwhile the call is placed on the parking. When the time elapses the voipswitch processes the call further i.e. proceeds with the answering rules action or just ends the call. At the same time it sends the “missed call” request to the EMCD.

The EMCI creates payload for PUSH notification which will carry the information received from voipswitch to the client’s device. Next it checks the destination PUSH service provider. If the provider is APNS the EMCI looks up for the api.contact_name associated with the calling login. If the caller is not in the destination user’s contacts the display name is used instead. Either of the names will be shown as the caller name in the iOS remote notification popup. This additional operation of obtaining a friendlier name than login is necessary as on the iOS the application is not woken up the moment when PUSH arrives and cannot influence the content of the notification’s window.

The EMCI sends the request to PUSH service for each user device.

On the client’s GUI push notifications are presented as incoming calls. On answering the application automatically sends an invite to pick up the call with the CallID received in the PUSH payload. The INVITE request contains the Replaces header with the call ID of the parked call.

If the calling party cancels the call before the timeout occurs and before the called party answers, the voipswitch will send the “missed call” request to the EMCI which will cause sending a notification to the client with a text informing that the call has been ended. The same will be happen when the timeout has occurred.

Voipswitch waits for the user to answer PUSH for 30 seconds which is the default timeout. After that time it proceeds further according to the user’s “answering rules” or if not set the call is ended.

The PUSH mechanism supports both video and audio calls.

Call forking

Each mobile device or desktop PC assigned to the same account has different SIP instance value. The instances are stored in the voipswitch.aa_ue_instance table. Each softphones sends its own SIP instance in the REGISTER request. On incoming call voipswitch checks which instances are registered at the moment and if there are more instances assigned to the account which are not registered. If there are not registered instances voipswitch will send PUSH request to the EMCI/emc.ashx and will pass the not registered instances as parameters. The EMCI will proceed with sending PUSH only to these instances. At the same time voipswitch will send the INVITE to the registered instances. In effect, it will ring on all the user devices, both registered and not registered.

Inbound messages and voicemail notification

PUSH for ONNET messages (chats) is realized through database triggers. The triggers have to be added to the….

When a new record is inserted the trigger launches UDF which sends request to the EMCI.

On receiving PUSH notification with message or voicemail the app calls the EMCD method which provides call history per account. The EMCD responds with the latest communication which should include the latest message for which the PUSH was sent

Sending multimedia files, as based on the SIP MESSAGES, uses the PUSH framework same way as other chat messages. The difference is in the type parameter of the PUSH message. When the type indicates a file the app will present appropriate popup.

Same approach is used for voicemails. The triggers are set on the voicemessages table.

PUSH providers

PUSH providers have to be defined in the EMCI/AppSettings.config file. The settings contain authentication data specific for each provider. These credentials have to be obtained from the particular service’s account for the RCS application.

Voipswitch PUSH settings

In voipswitch_config.xml file the following section must be added:

Make sure that the IP address (not FQDN) is entered properly and that there is connectivity from voipswitch server to the EMCI API on the specified port.

On the EMCI side add the IP of voipswitch server in the allowed IP addresses section in the EMCI/App.Settings file.

On voipswitch’s monitor window you can see when voipswitch sends the PUSH. On the picture below the first message is that the called device is not logged in. The call is placed on parking and PUSH is sent – “PUSH activated” message.

In this example the call was picked up successfully.

If there is a problem that PUSH notifications are not being received check first if you see voipswitch sends PUSH. If so then check connectivity to the emc.ashx and the EMCI’s logs.

Voicemail

Voicemail is a service realized by Voipbox. The call has to first hit the voipswitch which then routes it to the voipbox with instruction to execute voicemail scenario. Information on clients that have voicemail enabled are stored in the voipswitch.voicemailusers table. Both in the VUP and the RCS clients a user can enable/disable voicemail.

By default voicemail is enabled for all calls when they are declined by the client or timeout occurs. The timeout is set to 30 seconds.

In the VUP a client can manage the Answering Rules which allows to define different actions for calls coming from different caller IDs. Voicemail is one of the actions.

Messages left by callers are stored in a directory defined in voipbox.config file (TODO). The additional data about each message are stored in the voipswitch.voicemessages table.

When a client registers it subscribes to MWI (Message Waiting Indicator) service and receives information on number of received voicemails. In addition the application receives details of all new voicemails. They are sent over SIP or through the offline history EMCD API – depending on implementation used in the app. The details include information such as duration, time of recording, caller ID and the system ID of the message.

The list of all voicemails is presented in a list in Voicemail menu in the RCS application. The user can tap on a particular message to connect to voicemail service and hear the selected message being played.

The URI (number) of the voicemail is hardcoded in the softphones and if not requested otherwise it is by default 950. The number has to be prefixed with the dialing plan prefix used for ONNET calls. Usually it is set to onnet so the voicemail number will be onnet950.

To request a particular message the application sends an INVITE to the voicemail service number with a suffix added which is composed of “msg” part and the ID of the message, e.g. onnet950msg230 which tells voipbox to play the voicemail message with ID 230.

The above picture shows the Routing plan with voicemail service numbers.

Recording the welcome greeting

From the softphone a user can tap on the “Record welcome message” button in order to connect to the voicemail’s record greeting scenario. By default the number is 750, as on the previous picture the entry will be onnet750 with the prefix for internal calling.  Calling to this number will make Voipbox start the scenario intended to record welcome message. The welcome message will be then played for ever call reaching voicemail. If a user does not record own greeting the voipbox will use a standard welcome greeting delivered with the platform.

From the VUP users have more options as they can select a different greeting for calls coming from different caller ID.

Voicemail to email

 A user can enable this functionality by filling the email address in the Voicemail menu in the RCS application of through the VUP. The email will be added to the voipswitch.voicemailusers table.

When a new voicemail is left the system sends a request to Voipbox to convert the message from the raw PCM format in which voicemails are stored to mp3 format. When the mp3 is ready it is added to an email as attachment and is sent to the user email address.

More on how exactly voicemail to email service works you can read in the voipswitch documentation.

The content of the email and other properties are defined in VSM in the System\Event manager\ menu. In the first tab Jobs find the voicemail notification job in the list and click on it to enter the edition mode.

TODO

Account

The account related information on paid services are aggregated in the Account screen with few exceptions for the rates.

On the top position is the balance information obtained by the softphones through the EMCD\balance.ashx. The currency is received from the EMCD along with the balance and is the actual currency assigned to the client’s tariff.

Rates

The information on the cost of one minute connection to the OFFNET numbers is presented in three places:

• In the Rates menu in the Account screen
• On the dialpad screen
• In the contact details screen

In the Account menu a user can choose a country from the list. The request is sent to EMCD\rates.ashx with the ISO code of the country as parameter. In response the EMCD sends the json object with list of rates associated with descriptions.

The rates are read by the EMCD from the tariff assigned to the client who sent the request. The rates are selected based on the country ISO code. Therefore it is important to assign an ISO code to each row in the tariff which we want to show in the rates menu. The ISO code is not mandatory and the rows which do not have this value set will not be shown.

Note: the ISO code is not the same as country code. The ISO code is not used by the charging function, it is used only for presentation purposes to group the entries from the tariff which we want to show when a user requests rates for a given country.

Usually the tariff consists of hundreds or even thousands of detailed breakouts. For reporting and billing related tasks we need all of those prefixes, even if their selling price is the same for multiple entries. On the other hand we do not want to confuse a user with dozens of entries per one country. What you can do to limit the number of the presented entries is to choose the desired entries and only for them set the ISO code of the country to which the prefixes belong.

If you do not see the rates in the softphone even though they are in the assigned tariff it is probably the lack of the ISO codes as it is the most frequent reason.

The rates are also shown in the dialpad. When typing the number the app sends request to the EMCD\rates.ashx with the phone number as parameter. The EMCD checks if there is a matching prefix in the rates table and returns it to the app.  In this request the ISO code is not used.

Another place is the Contact details view.  When opened the application sends request with phone number as parameter, same as in the dialpad.

Plans

Plans are described in great details in voipswitch documentation. In the RCS clients the plans created through VSM are presented in the Plans screen. A user can buy one or many plans. The purchased plans are marked as active and cannot be bought again.

All the tasks related with handling plans and charging for them are done on the server side. On the client they can only be ordered.

The plans can be recurring or one time. Although this setting depends on the configuration on the server the RCS applications do not have an option to cancel subscription as it was designed for one time plans.

Note: In order to allow users to buy plans this option has to be enabled in the application. Make sure you select this option in the deployment document form you receive from us. Once the applications are generated and published this option cannot be enabled without going through the whole process again.

Phone numbers (DIDs)

The RCS client applications allow for ordering virtual numbers (DIDs). The DID service has to be configured on the server side in VSM. The DIDs can be stored in blocks in the database or the system can be connected to DID providers offering their service through API. Please check the voipswitch documentation to learn more.

Note: In order to allow users to buy DIDs this option has to be enabled in the application. Make sure you select this option in the deployment document form you receive from us. Once the applications are generated and published this option cannot be enabled without going through the whole process again.

Top up

The recharge functionality differs per platform. Besides the native payment methods our RCS clients can work with the 3^rd party payment systems.

The native systems:

• Android google play In App Billing
• Apple inApp Purchase (IAP)

The 3^rd party payments are realized by opening a web view within the application. The component opens a mobile version of the top up page from VUP. The page shows the offered payment methods for example Paypal, credit cards, CashU and others.

The detailed list of supported payment providers can be found in voipswitch documentation.

Please let us know which of the method you would like to implement when filling our deployment form.

Vouchers

The voucher support is based on the recharge PINs generated in VSM (TODO add link). In the softphone’s GUI it is implemented natively (not through the web page).

Please inform us in the deployment form if you wish to have vouchers enabled.

Mobile transfer – to external (offnet) numbers

User to user balance transfer

<listener type="sip">

  <param name="ipaddr" value="1.2.3.4" />

  <param name="port" value="5061" />

  <param name="transport" value="tls-tcp" />

  <param name="tls-certificate" value="VPS.cert" />

</listener>

<listener type="registrar">

  <param name="ipaddr" value="1.2.3.4" />

  <param name="port" value="5061" />

  <param name="register-expiration" value="3600" />

  <param name="subscribe-expiration" value="3600" />

  <param name="transport" value="tls-tcp" />

</listener>