Signal

This is the documentation of the generic JSON representation of innovaphone signaling messages. These messages are defined transport independent and are used inside different protocols implemented in the PBX, the Gateway or different Apps. These signaling messages can be mapped to SIP or H.323/EFC signaling.

General structure

{
    "type": "Signaling message type",
    "...": "more properties"
}

A property type identifies the signaling message. The names used here are based on the names defined in Q.931 ISDN signaling:

type
Type
Message types
Signaling Objects - Objects used for call signaling
Facility Objects - Objects used for supplementary services
Channel Objects - Objects used for media negotiation

setup

{
    "type": "setup",
    "bc": BearerCapability
    "cg": EP,
    "cd": EP,
    "complete": DialingComplete,
    "channel": Channel,
    "fty": [Fty,Fty, ...],
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
    "uui":UserUserInformation,
    "llc":LowerLayerCompatibility,
    "hlc":HigherLayerCompatibility,
    "pi":ProgressIndicator,
    "confId":ConferenceId,
    "callId":CallId,
    "dsp":Display
}

The setup message is used to start a call

accept

{
    "type": "accept"
    "fty": [Fty,Fty, ...]
}

Used only together with some special supplementary services. See description there.

info

{
    "type": "accept"
    "cg": EP,
    "cd": EP,
    "complete": DialingComplete,
    "dsp":Display
}

The info message is used for additional dialing information after a setup_ack message is received or for additional information like charging display information when the call is connected.

progress

{
    "type": "progress",
    "inband_info": InbandInfo,
    "cau":Cause
    "pi":ProgressIndicator,
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
}

Maps to the ISDN PROGRESS message. It is used to report, that in-band information is# available in the call. Together with a cau property present it indicates that the call was disconnected.

call_proc

{
    "type": "call_proc",
    "inband_info": InbandInfo,
    "channel": Channel,
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
}

Maps to the ISDN PROGRESS message. It is used to report, that in-band information is# available in the call. Together with a cau property present it indicates that the call was disconnected.

alert

{
    "type": "alert",
    "inband_info": InbandInfo,
    "pi":ProgressIndicator,
    "fty": [Fty,Fty, ...],
    "channel": Channel,
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
}

Indicates that the called endpoint is alerting.

conn

{
    "type": "conn",
    "uui":UserUserInformation,
    "dsp":Display
    "fty": [Fty,Fty, ...],
    "channel": Channel,
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
}

Indicates that the called endpoint has connected the call.

disc

{
    "type": "disc",
    "inband_info": InbandInfo,
    "cau":Cause
    "pi":ProgressIndicator,
    "uui":UserUserInformation,
    "dsp":Display
    "fty": [Fty,Fty, ...],
}

Sent by a network component to indicate that the remote endpoint has disconnected the call, but still inband information may be available

rel

{
    "type": "rel",
    "cau":Cause
    "uui":UserUserInformation,
    "dsp":Display
    "fty": [Fty,Fty, ...],
}

Releases the call.

channels

{
    "type": "channels",
    "channel": Channel,
    "channels_cmd": ChannelsCmd,
    "channels":Channels,
    "faststart":Faststart,
}

Message used for media negotiation, if the information cannot be transported with another signaling message

facility

{
    "type": "facility",
    "fty": [Fty,Fty, ...],
}

Used for facility objects if no other signaling message can be used.

user_info

{
    "type": "user_info",
    "uui":UserUserInformation,
}

Used for transparent user user information when a call is connected.

Signaling Objects

BearerCapability

The ISDN Bearer Compatibility Information element as hex string. If not set an appropriate value has to be chosen for the Bearer Capability when sending the call to ISDN, based on channel. For calls without media channel (channel=0), a value of "a880" for calls with media channel a value of "8090a2" is recommended.

CallIdentifier

The H.323 callIdentifier. This identifies a single leg of a call.

Cause
{
    "loc": "Location",
    "num": "Cause"
}

The ISDN Cause information element. Used to report error conditions or the reason why a call was disconnected.

loc
The location of the cause as defined in Q.931
num
The cause number as defined in Q.931
Channel

Integer value indicating the channel used for a call. For calls without media a value of 0 is used. For VOIP calls with media a value of -1 is used.

DialingComplete

A boolean value, indicating that no more dialing information will be sent.

ConferenceID

The H.323 conferenceID. This id is the same for all legs of a call.

Diversion Entry
{
    "procedure": Diversion Procedure,
    "remote_enabled": boolean
    "served": EP
    "diverted_to": EP
}
procedure
The diversion procedure
remote_enabled
True if enabled by endpoint
served
The endpoint which is diverted
diverted_to
The destination of the diversion

Diversion Procedure

A string value identifying a call diversion procedure

ALWAYSCall forward unconditional (CFU)
BUSYCall on busy (CFB)
NO_ANSWERCall forward on no response (CFNR)

EP
{
    "num": "phone number",
    "sip": "sip uri"
}

The EP object is used in general to address the endpoint of a call. The endpoint may be addressed by a phone number or by a sip uri.

num
A phone number as used on the PSTN. It may consist of dialing digits ("0" ... "9", "*", "#") and the following prefixes:
RPresentation Restricted number, which means this number should not be forward out of the system
SSubscriber number
NNational number
IInternational number
sip
A sip URI. If the call is to/from the local domain only the user part is used.
FTY

An array of FacilityObjects.

HigherLayerCompatibility

The ISDN Higher Layer Compatibility Information element as hex string. Only used together with ISDN signaling.

InbandInfo

Boolean value, which indicates that inband info is availabe in the call.

LowerLayerCompatibility

The ISDN Lower Layer Compatibility Information element as hex string. Only used together with ISDN signaling.

ProgressIndicator

Array of hex strings of ISDN Progress Indicator information elements. The hexstrings do not include the type and length field of the information elements. Only used together with ISDN signaling.

Presence Activity

Defines the current activity. Allowed values are:

busyThe user is busy

Presence Contact

The contact URI defines where this presence information originates from. New presence information only overwrites the presence from the same contact URI. The following contact URIs are used by innovaphone

tel:The presence is set on the phone
im:The presence is set on the client
cal:The presence is set by the calendar

Presence Note

A note entered by the user

Presence Status

The status of the user in respect to the contact URI. This indicates if the device of the user with this contact URI is active. Allowed values are "open", "closed".

Remote Control

A string value defining a remote control operation. The following values are defined:

CONNECT
MULTICAST
ANNOUNCE
3PTY_TOGGLE
ACCEPT
CC_ON
CC_OFF
REC_ON
REC_OFF
3PTY_ON
3PTY_OFF
DTMF_DIGIT
ON_HOLD
MIC_ON
MIC_OFF
HANDSET
HEADSET
HANDSFREE
MONITOR_ON
MONITOR_OFF
INTRUDE_MONITOR
INTRUDE_CONFERENCE
RECEIVE_ON
RECEIVE_OFF
CONFERENCE_EXCLUSIVE_ON
CONFERENCE_EXCLUSIVE_OFF
KNOCK_ON
KNOCK_OFF
ACTIVATE_APP_HOME
ACTIVATE_APP_PHONE
ACTIVATE_APP_FAVS
ACTIVATE_APP_LIST
ACTIVATE_APP_DIR
ACTIVATE_APP_CONFIG
ACTIVATE_APP_CAMERA
HOLD
RETRIEVE

UserUserInformation

The ISDN/H.323 User User Information as string. The protocol discriminator is not included and is assumed as hex 50. A maximimum length of 128 bytes is allowed.

Facility Objects

{
    "type": "Type of Facility element",
    "...": "more properties"
}

Depending on the value of the type property, different objects are defined. The following types are defined:

ct_identifyCall Transfer Identify
ct_identify_result
ct_initiate
ct_initiate_result
ct_setup
ct_setup_result
ct_complete
diversion_interrogate
diversion_interrogate_result
diversion_callreroute
diversion_calldeflection
diverting_leg1
diverting_leg2
diverting_leg3
diverting_leg4
hold_notify
retrieve_notify
remote_hold
remote_hold_result
remote_retrieve
remote_retrieve_result
cp_park
cp_group_indication_on
cp_group_indication_off
cp_pick_req
cp_pick_exe
call_waiting
mwi_activate
mwi_deactivate
mwi_interrogate
mwi_interrogate_result
name_identification
co_alerting
presence_publish
presence_subscribe
presence_notify
dialog_info_subscribe
im_setup
im_message
cli_override
innovaphone_remote_control

ct_identify
{
    "type": "ct_identify"
}

For a call transfer of two active calls, with this facility an id is requested from one active calls, which is sent to with ct_initiate to the other call.

ct_identify_result
{
    "type": "ct_identify_result",
    "id": unsigned id
    "dst": EP
}

return the id requested by ct_identify

ct_initiate
{
    "type": "ct_initiate",
    "id": unsigned id
    "dst": EP
}

Initiate a call transfer, either to the other active call, which is identified by id, or if id is not found to a new call to dst

ct_initiate_result
{
    "type": "ct_initiate_result",
    "error": unsigned error code
    "cause": isdn cause code
}

Send when the call transfer is complete. This is either when it failed, then error is set and if available cause, or when it succeeded. For a blind transfer (no id), the transfer succeeded, when a call_proc, alert or conn from the new call is received

ct_setup
{
    "type": "ct_setup",
    "id": unsigned id
    "dst": EP
}

Send with a new call created by a call transfer. id is the id sent with ct_initiate. dst identifies the endpoint which sent the ct_initiate

ct_setup_result
{
    "type": "ct_setup_result",
}

May be sent in response to ct_setup. No real meaning.

ct_complete
{
    "type": "ct_complete",
    "remote": EP
    "remote_name": Remote Name Id,
    "call_status": State of call,
    "end":
}

Send to transferd endpoints to announce the new endpoint to which they are connected. call_status and end are not used.

diversion_interrogate
{
    "type": "diversion_interrogate",
    "procedure": Diversion Procedure
    "served": EP
    "interrogating": EP
}

Used to interrogate the PBX for set call diversions.

procedure
The procedure, which shall be interrogated
served
Optional the endpoint which is interrogated. Does not work for any other then the interrogating endpoint on innovaphone PBX
interrogating
Optional the endpoint interrogating
diversion_interrogate_result
{
    "type": "diversion_interrogate_result",
    "procedure": Diversion Procedure,
    "error": error code if interrogate failed
    "num": number of entries
    "list": [Diversion Entry]
}

Returns a list of diversions

diversion_callreroute
{
    "type": "diversion_callreroute",
    "last_rerouting": EP,
    "called": EP,
    "calling": EP,
    "served": EP,
    "reason": Diversion Procedure
}

Request the rerouting of the call

called
Destination to the call is rerouted
last_rerouting, calling, served
Only used innovaphone PBX internally
diversion_calldeflection
{
    "type": "diversion_calldeflection"
}

Not implemented

diverting_leg1
{
    "type": "diverting_leg1",
    "reason": Diversion Procedure
    "nominated": EP,
    "redirecting": EP,
}

Send to the caller of an diverted call, when a diversion is performed

nominated
the new destination of the call
redirecting
the endpoint which initiated the diversion
diverting_leg2
{
    "type": "diverting_leg2",
    "diverting": EP,
    "original_called": EP,
    "diverting_name": String,
    "original_called_name": String
}

Send with the call to the new destination of the diversion

diverting
The endpoint performing the last diversion
original_called
The original called endpoint, only present if there is more then one diversion
diverting_leg3
{
    "type": "diverting_leg3",
    "redirection": EP,
}

Sent to the caller of the diverted call, with the conn message

diverting_leg4
{
    "type": "diverting_leg4",
    "reason": Diversion Procedure,
    "nominated": EP,
    "redirecting": EP
}

On innovaphone PBX this message is only used to inform an endpoint about update of configured diversions, by sending this message without reason, nominated or redirecting property.

hold_notify
{
    "type": "hold_notify"
}

Informs the endpoint that the peer endpoint of the call has initiated a hold

retrieve_notify
{
    "type": "retrieve_notify"
}

Informs the endpoint that the peer endpoint of the call has initiated a retrieve

remote_hold
{
    "type": "remote_hold",
}

Request the call to be held

remote_hold_result
{
    "type": "remote_hold_result"
}

No real meaning, hold does not fail

remote_retrieve
{
    "type": "remote_retrieve"
}

Request a held call to be retrieved

remote_retrieve_result
{
    "type": "remote_retrieve_result"
}

No real meaning, retrieve does not fail

cp_park
{
    "type": "cp_park",
    "parking": EP,
    "parked": EP,
    "parked_to": EP,
    "park_position": unsigned
}

Used to park a call at a new destination. If initiated by an endpoint only parked_to is used to address the new endpoint

cp_group_indication_on
{
    "type": "cp_group_indication_on",
    "callId": CallId
    "member": EP,
    "parked_calling": EP,
    "parked_to_alerting": EP,
    "parked_to_alerting_ext": EP,
    "park_position": unsigned,
    "inbound_call": bool,
    "duration": unsigned,
    "name_id_calling": string,
    "name_id_alerting": string,
    "sig_call_state": unsigned
}

This object is used on configured group indication to announce a call that may be picked. This can either be a parked or an alerting call. On dialog sibscription calls, this object is used for any active calls at the monitored destination

callId
CallIdentifier of the call
member
The monitored endpoint
parked_calling
Identifies the endpoint which was calling for parked or alerting calls, or in general the remote end of the call
parked_to_alerting
The local end of the call. Typlically identical to member
park_position
Park position if the is a parked call, which was parked to a position
inbound_call
True if is a call initiated by the parked_to_alerting endpoint, which means it is the other call direction, as would be an alerting call.
duration
Duration of the call in seconds
name_id_calling
Name Id to parked_calling
name_id_alerzing
Name Id to parked_to_alerting
sig_call_state
innovaphone call state definition
cp_group_indication_off
{
    "type": "cp_group_indication_off",
    "callId": CallId,
    "member": EP,
    "clear_all": bool
}

On configured group indications, this message indicates, that the call is not in a state anymore in which it can be picked. For dialog subscriptions this message is sent, when the call was released.

callId
CallIdentifier of the call
member
The monitored endpoint
clear_all
All calls of the monitored endpoint are not monitored anymore
cp_pick_req
{
    "type": "cp_pick_req",
    "callId": CallId,
    "picking": EP,
    "parked_calling": EP,
    "parked_to_alerting": EP,
    "park_position": unsigned
}

Send in a setup message of a no media call to request to pick a call. If successful the picked call will be sent with the facility pick_exe to the picking endpoint

callId
CallIdentifier, if a specific call shall be picked
picking
The picking endpoint, which may not be any other then the originator of the pickup call
parked_calling
Optionally the remote endpoint of the picked call to identify the call
parked_to_alerting
Endpoint where the call is picked
park_position
Identify the position if only a call parked to a given position is to be picked
cp_pick_exe
{
    "type": "cp_pick_exe",
    "callId": CallId,
    "picking": EP,
    "parked_calling": EP
}

Sent with the setup of a picked call

callId
CallIdentifier of the picked call
picking
Endpoint requesting the picking
parked_calling
The endpoint from where the call was picked
call_waiting
{
    "type": "call_waiting"
}

Included in a alert message if the call is waiting, which means another call is currently active at the called endpoint

mwi_activate
{
    "type": "mwi_activate",
    "served_user": EP,
    "message_center": EP,
    "originating_user": EP,
    "time": string,
    "service": unsigned,
    "number": unsigned,
    "priority"
}

Send in a setup of a no media call to activate message waiting indication

mwi_deactivate
{
    "type": "mwi_deactivate",
    "served_user": EP,
    "message_center": EP,
    "service": unsigned,
    "call_back": unsigned
}

Send in a setup of a no media call to deactivate a message waiting indication

mwi_interrogate
{
    "type": "mwi_interrogate",
    "served_user": EP,
    "message_center": EP,
    "service": unsigned,
    "call_back": unsigned
}

Send in a setup of a no media call to interrogate active message waiting indications.

mwi_interrogate_result
{
    "type": "mwi_interrogate_result",
    "sub": mwi_activate
}

Returns last mwi_activate

name_identification
{
    "type": "name_identification",
    "name": string
}

Included in setup, alert or conn messages to indicate the display name of the sender

co_alerting
{
    "type": "co_alerting"
}

?

presence_publish
{
    "type": "presence_publish",
    "status": Presence Status,
    "activity": Presence Activity,
    "note": Presence Note,
    "contact": Presence Contact
}

This object is sent in a setup message of a no media call to publish a presence item

presence_subscribe
{
    "type": "presence_subscribe"
}

This object is included in the setup message of a no media call to indicate, that this is a presence subscription

presence_notify
{
    "type": "presence_notify",
    "status": Presence Status,
    "activity": Presence Activity,
    "note": Presence Note,
    "contact": Presence Contact
}

This object is sent in a facility message of a presence subscription call to indicate the current presence status.

dialog_info_subscribe
{
    "type": "dialog_info_subscribe"
}

This object is included in the setup message of a no media call to indicate, that this is a dialog info subscription. The dialog information is then sent with cp_group_indication objects in facility messages.

im_setup
{
    "type": "im_setup"
}

This object is included in the setup message of a no media call to indicate, that this is a instant messaging (chat) call.

{
    "type": "im_message",
    "sender": string,
    "sender_dn": string,
    "subject": string,
    "participants": string,
    "data"; string,
    "attach": string,
    "typing": bool,
    "mime": string,
    "more": bool
}

This object is sent with a facility message within a instant messging call to transmit chat messages

sender
SIP URI of the sender of the message
sender_dn
Display name of the sender
subject
A subject line of the message
participants
Comma separated list of participants in a group chat (not supported anymore)
data
The message data formated according the mime type
typing
True if sender is typing
mime
The mime type of the message. It is recommended to use html
more
true if the data of the message is not complete and more data follows in more messages
cli_override
{
    "type": "cli_override"
}

If present in a call the PBX uses the calling line identification from the setup instead of replacing it by what is defined for the endpoint.

innovaphone_remote_control
{
    "type": "innovaphone_remote_control",
    "control": Remote Control,
    "digit": string
}

Maybe sent in signaling messages to perform remote control operations at the phone. Some operations may use digit as argument.

Channel Objects

ChannelsCmd

The channels_cmd property implements the SIP offer/answer as the H.323EFC Proposal/Select procedure. The basic idea is, that one side sends an offer for media descriptions (proposal) and the other side chooses supported media descriptions and sends these back as answer (select).

In addition to this basic procedure, media can be closed or one side can request an new offer from the other side.

This result in the following string values for the channels_cmd property:

NONENo media negotiation is associated with this message
SELECTSelect a media channels. The accompanied channels property must contain the answer
PROPOSALSend a media offer (proposal), the accompanied channels property must contain the offer
REQUESTRequest a new offer (proposal)
CLOSEClose all media channels

Channels
{
    "source": Source,
    "id": Id,
    "guid": GUID,
    "key":Key,

    "audio_rtcp_mux":Audio RTCP multiplxing,
    "t38_rtcp_mux":T.38 RTCP multiplxing,
    "video_rtcp_mux":Video RTCP multiplxing,
    "collab_rtcp_mux":Collab RTCP multiplxing,

    "audio_setup_role":Audio Setup Role,
    "t38_setup_role":T.38 Setup Role,
    "video_setup_role":Video Setup Role,
    "collab_setup_role":Collab Setup Role,

    "audio_ice":Audio ICE,
    "t38_ice":T.38 ICE,
    "video_ice":Video ICE,
    "collab_ice":Collab ICE,

    "ch":[Channel,...]
}

The Channels object is a complete media description for the call. Together with a channels_cmd of "PROPOSAL", it is a media offer (proposal) and together with a channels_cmd of "SELECT" it is a media answer (select).

Source

This is a string defining the source of the media channels. Based on the source different modes of operations may be used in signaling entities. The following values are defined:

LOCAL The channels are originating from a local physical interface like a ISDN or Conference channel. This is only used on an interface, where these channels are sent back to the same system (e.g. EpSignal). On a remote system the channels are useless, because no RTP entities are associated with these.
REMOTE Generic remote channels, from any kind of VOIP signaling. The remote side has RTP entities associated with these, so the channels can be terminated.
RELAY Used on interfaces where the channels are sent back to the same system (e.g. EpSignal) to switch both ends of the signaling in a Media Relay (RTP Proxy) mode.
H323 Same es REMOTE, but from a H.323 non EFC entity. This means that media re-negotiation is not possible.
H323EFC Same as REMOTE, but from a H.323EFC entity. Full media negotiation support.
SKINNY Obsolete. Reserved for the Cisco Skinny protocol.
SIP Same as REMOTE, but from a SIP entity. Full media negotiation support.

Id

An unsigned integer, as id of the channels (???/tac)

GUID

A hex string for a 16 bytes GUID, which identifies the system from which these channels originate. If this is forwared to the other end of the call it is used to detect if the call is terminated on the same system again, so that a local PCM connection may be switched.

Key
{
    "tag": SRTP tag as unsigned integer,
    "mode": SRTP Mode,
    "mki": MKI,
    "mki_len": MKI length,
    "b": hexstring of SRTP key,
}

The SRTP key used for the audio channel, in case no DTLS can be done.

RTCP Mux

Boolean value indicating the RTCP multiplexing can be done, meaning that RTP and RTCP is sent on the same UDP port. The side sending the offer can set this value to true if it supports RTCP multiplexing. The side sending the answer may send back a value of true in this case to turn on RTCP multiplexing.

Setup Role

This string property may be added, if not the default ICE setup role shall be used, which is defined by who is sending the offer and who the answer.

The following values are defined:

active???/tac/msc
passive???/tac/msc
actpass???/tac/msc
holdconn???/tac/msc

ICE
{
    "lite": Only ICE lite support,
    "fingerprint": ICE fingerprint as hexstring,
    "usr": ICE authentication user,
    "pwd": ICE authentication password,
    "candidate": [Candidate, ...],
}

The ICE parameters for the respective channel

Candidate
{
    "addr": address,
    "r_addr": ???/msc,
    "rtp": ?,
    "rtcp": ?,
    "r_rtp": ?,
    "r_rtcp": ?,
    "rtp_prio": ?,
    "rtcp_prio": ?,
    "type": ?,
    "foundation": ?
}

The ICE candiates, which where locally found and transmitted to the other side, so that ICE testing can find a matching pair.

Channel
{
    "coder": Coder,
    "number": Number ???/tac,
    "xmit": xmit,
    "rate": recv,
    "addr": Media address,
    "port": Media Port,
    "mc_addr": Multicast address,
    "mc_port": Multicast port,
    "pt": Payload type,
    "flags": Flags
}
Coder
The coder used for this media channel. The following Coder values are defined:
G711_AG.711 A-Law
G711-uG.711 u-Law
G723_53G.723 using low bitrate
G723_63G.723 using high bitrate
G729G.729
G729AG.729 reduced complexity
G729BG.729 including comfort noice updates
G729ABG.729 reduced complexity, with comfort noice upüdates
T38UDPT.38 Fax
G722G.722
XPARENTBit transparent coder
H264H.264 Video
JRFBInnovaphone Json Remote Frame Buffer protocol for application sharing
OPUS_NBOpus narrow band
OPUS_WBOpus wide band
VPBVP8 Video
Number
?
xmit
Packetization for transmitting in ms. With the offer a proposed value is sent, which may be reduced in the answer.
recv
Packetization for receiving in ms. With the offer a proposed value is sent, which may be reduced in the answer.
addr/port
Transport address to receive media. This is the RTP port. The RTCP port is assumed to be port+1
mc_addr/port
Multicast address if the the media is to be sent to a multicast address.
pt
The payload type if not the default payload types are used, or if not default payload type is defined for the coder
flags
?
Faststart

Array of H.323 faststart elements, coded as hex strings.