SIP intercom iDFace

The iDFace access controller has a VoIP intercom system based on the SIP (Session Initiation Protocol). Once configured, the controller registers the user on the indicated server and thus allows making and receiving voice calls.

To access this functionality, it is necessary to obtain a PRO license for iDFace.

Below are some of the configurable parameters of the SIP intercom in iDFace. They can be determined through the device and web interface or through the API.

SIP connection

For the connection to the SIP server to be established, it is necessary to ensure that the intercom is enabled. Then, you must provide the access data to the SIP server and the user account registered on it that you wish to use. This can be done via the SIP Settings Menu or through our API.

Field	Type	Description
enabled	string	Enable SIP intercom.
server_ip	string	Address of the SIP server, which can be passed as a URL or as an IP address.
server_port	int	Server access port.
server_outbound_port	int	RTP initial port of the SIP. If set to 0, uses any available port.
server_outbound_port_range	int	RTP port range of the SIP. SIP will only use the available network ports within the specified range.
numeric_branch_enabled	string	Enables or disables reading the user's branch as a numeric value. Values: "0" for alphanumeric and "1" for numeric.
branch	string	Branch registered on the SIP server.
login	string	User name registered on the SIP server.
password	string	Password for logging into the SIP server. To use Digest Authentication, the password must have a maximum of 16 characters.
peer_to_peer_enabled	string	Enables peer-to-peer communication on the call, with the possible options being "1" for enabled and "0" for disabled.

Request example

This request configures the SIP connection parameters.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "enabled": "1",
                "server_ip": "my_server",
                "server_port": "5060",
                "server_outbound_port": "10000",
                "server_outbound_port_range": "1000",
                "numeric_branch_enabled": "1",
                "branch": "987",
                "login": "987",
                "password": "123456",
                "peer_to_peer_enabled": "0"
            }
        }
    )
});

General Call Settings

Configuration of call's timers

We can configure, through the API, the timeout parameters, such as the register time, max call time or the keep-alive timeout, according to the following examples:

Field	Type	Description
reg_status_query_period	int	Period, in seconds, to query the register's status.
server_retry_interval	int	Period, in seconds, to send the keep-alive.
max_call_time	int	Maximum duration of a call, in seconds.
push_button_debounce	int	Debounce time on the button to avoid unnintentional calls, in millisseconds.

Request example

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "reg_status_query_period": "60",
                "server_retry_interval": "5",
                "max_call_time": "300",
                "push_button_debounce": "50"
            }
        }
    )
});

Auto Answer

Enabling Auto Answer allows the device to automatically accept incoming calls. It is possible to configure an interval, in seconds, between the receipt of the call and its answer by the device.

The auto_answer_enabled parameter of the pjsip module, determines whether auto-answer will be enabled or not. Once enabled, the auto-answer time is set by the auto_answer_delay parameter, also from the pjsip module.

Field	Type	Description
auto_answer_enabled	string	Enables the auto-answer of SIP calls. Values: "0" for auto-answer off and "1" for auto-answer on.
auto_answer_delay	string	Waiting time in seconds for auto-answer.

Request example

Request to configure automatic answering enabled in 5 seconds of a call.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "auto_answer_enabled": "1",
                "auto_answer_delay": "5"
            }
        }
    }
    )
});

Dialing mode

By default, when the intercom is enabled and properly configured, a dialing button is shown on the device's main screen, by which it is possible to initiate a new call. The visibility of this button can be configured according to the user's needs with the parameter auto_call_button_enabled. Important: Please be aware that when the dial button visibility is disabled on the device's screen, it's required the usage of the external dial button for a SIP call to be executed. The external dial button can be configured according to the user's needs with the parameter rex_enabled.

Another important setting is the dialing mode when the button is pressed, which can be set with the parameter dialing_display_mode. There are 3 possible dialing modes and the user can customize them as desired. The table below shows the parameter that should be used for customization, the possible inputs and the description of the dialing modes. All the parameters in this section are part of the pjsip module.

Parameter	Value	Description
auto_call_button_enabled	string	Enables or disables the visibility of the call button on the device's main screen. Values: "0" to disable the button and "1" to enable it.
rex_enabled	string	Enables or disables the functionality of the call by external dial button. Values: "0" to disable the button and "1" to enable it.
dialing_display_mode	string	Values: "0" for Auto Dialing, when the dialing button is pressed, a number is called directly; "1" for Dialing from the contact list. When the dialing button is pressed, the contact list is shown and the call is made to the selected contact; "2" for Dialing from the numeric keypad or from the contact list. When the dialing button is pressed, a new screen is displayed with a numeric keypad and an icon to go to the contact list. To make the call, the user can choose between entering a number on the keypad or searching for a contact in the list.

When selecting auto-dial mode it is necessary to set the number to which the call will be made. This is done with the auto_call_target parameter. In addition, you can define a name related to this number. This is defined with the parameter custom_identifier_auto_call. This name will be shown on the iDFace display when making or receiving calls. If no name is filled in and there is no saved contact linked to this number, the display will show only the number entered.

Note: the parameter auto_call_enabled, which was used to configure automatic dialing, is no longer used. Setting autodialing must be done exclusively by dialing_display_mode.

Request example

Request to enable the dial button, enable automatic dialing to the number 456, set the number name to Reception desk and enable the external dial button.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "auto_call_button_enabled": "1",
                "rex_enabled": "1",
                "auto_call_target": "456",
                "custom_identifier_auto_call": "Reception desk",
                "dialing_display_mode": "0"
            }
        }
    }
    )
});

Configuration of video SIP call

We may configure the call to be made with a video transmission (depending also if the client on the other side is well-configured and accepts h264 video). In order to make it, we must configure the device through the following parameter:

Parameter	Value	Description
video_enabled	int	Defines the state of the video SIP call configuration, being "1" to activate and "0" to deactivate it.

It is worth noting that, after configuring the device in the video SIP mode, one must restart the equipment to assure that the video_streamis properly configured.

Request Example

To configure a call with video SIP mode, we can send a request as the following example:

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "video_enabled": "1"
            }
        }
    }
    )
});

Custom Ring Sound Settings

Custom Ring Tone

You can enable a custom ringtone for your device. In this way, when a call request is made by the device, while the answer is not received, the custom audio will be played. If you choose to activate this setting, you must previously perform the upload of the customized audio through the endpoint set_pjsip_audio_message or through the Intercom setting at iDFace Web interface. When enabling this setting, you must restart the device for the changes to take effect.

In addition, it is possible to configure the volume of the custom ringtone. The volume is configured through three possible gain levels, being "1" for the original volume, "2" for a gain of twice the original volume, and "3" for a gain of three times the original volume.

Enabling the custom call sound is done through the pjsip_custom_audio_enabled parameter of the pjsip module, and the custom call sound volume level configuration is set by the custom_audio_volume_gain parameter, also of the pjsip module.

Field	Type	Description
pjsip_custom_audio_enabled	string	Enables the use of custom ringtone. Values: "0" for custom audio disabled and "1" for custom audio enabled.
custom_audio_volume_gain	string	Controls the volume of the custom call sound through its gain. Values: "1", "2" and "3".

Request example

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "pjsip_custom_audio_enabled": "1",
                "custom_audio_volume_gain": "1"
            }
        }
    )
});

POST /set_pjsip_audio_message.fcgi

Allows you to upload the audio that will be used in making calls. The audio sent must be a binary file, in .wav format, and have a size smaller than 5 MB and, due to network protocol limitations, it must be sent in blocks of no more than 2 MB. Blocks must be sent sequentially, specifying the parameters current and total for that purpose.

Parameters

• current (int): Current block of the sound file.
• total (int): Total number of blocks in the sound file.

Response

• This request has no response.

Request example

$.ajax({
    url: "/set_pjsip_audio_message.fcgi?session=" + session + "&current=" + current + "&total=" + total,
    type: 'POST',
    contentType: 'application/octet-stream',
    data: data_sound
    )
});

POST /get_pjsip_audio_message.fcgi

Allows you to download the custom audio file used when making calls.

• This request has no parameters.

Response

• Custom audio file in binary format, present in the response body, if it exists. (Content-Type: audio/wav)

Request example

$.ajax({
    url: "/get_pjsip_audio_message.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json'
});

POST /has_pjsip_audio_message.fcgi

Allows you to check if there is any custom audio file on the device.

• This request has no parameters.

Response

• file_exists (bool): Returns true if a custom audio file already exists on the device and false otherwise.

Request example

$.ajax({
    url: "/has_pjsip_audio_message.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json'
});

Volume Settings

Also through the intercom configuration interface, it is possible to determine the volumes of the microphone and the speaker of the device. Both volumes can be set to values between 1 and 10.

Request example

Microphone and speaker volume configuration request.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "mic_volume": "5",
                "speaker_volume": "7"
            }
        }
    )
});

Make Calls via API

After the SIP is properly configured, it is possible to make calls on the device via API. Calls can be controlled from three endpoints which will be explained below.

POST /make_sip_call.fcgi

Responsible for initiating a call. The call will only be made if the device is on its home screen or in identification streaming.

Parameters

• target (string): Extension that will receive the call.

Response

• This request has no response.

Request example

$.ajax({
    url: "/make_sip_call.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "target": "503"
        }
    )
});

POST /finalize_sip_call.fcgi

Responsible for terminating an ongoing call.

Parameters

• This request has no parameters.

Response

• This request has no response.

Request example

$.ajax({
    url: "/finalize_sip_call.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json'
});

POST /get_sip_status.fcgi

Returns the current status of the SIP, including the status code and whether a call is in progress.

Parameters

• This request has no parameters.

Response

• status (int): Indicates call status code. The codes are consistent with the standard definition of the SIP protocol. Some of the possible returns are:
  • -1 : "Disabled"
  • 0/100 : "Connecting"
  • 200 : "Connected"
  • 401/403 : "Authentication failed"
  • 408 : "Failed to connect to server"
  • 503 : "Network connection failed"
• in_call (bool): Indicates whether a call is in progress. Returns true if there is an active call and false otherwise.

Request example

$.ajax({
    url: "/get_sip_status.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json'
});

Access authorization via intercom

Warning: The access authorization via intercom of iDFace uses codes sent by DTMF according to RFC 2833.

It is possible to authorize access with a code dialed through the intercom during a call. To do this, you must first enable the feature and register a new code. To enable/disable you must use the open_door_enabled parameter of the pjsip module. It accepts the values "0" (disabled) or "1" (enabled) as valid inputs.

To register the release code, use the open_door_command parameter, also from the pjsip module. It accepts numeric characters and the following special characters as input: '+', '*' and '#'.

Request example

Request to enable intercom access release by dialing code 12345.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "open_door_enabled": "1",
                "open_door_command": "12345"
            }
        }
    )
});

Identification during intercom

Warning: iDFace's functionality to enable identification during a SIP call is available from firmware version 6.13.1.

It is possible to perform identification during a SIP call. To do this, you must first enable the feature. To enable/disable you must use the facial_id_during_call_enabled parameter in the pjsip module. It accepts the values "0" (disabled) or "1" (enabled) as valid entries.

Request example

Request to enable the identification during intercom.

$.ajax({
    url: "/set_configuration.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify(
        {
            "pjsip": {
                "facial_id_during_call_enabled": "1"
            }
        }
    )
});