VoIP/VoIP X Call State Commands

Using the TTP Call State Commands

The VoIP Control Status Block supports the use of Call State monitoring in order to poll information about the current call state of the telephone card. The response will include multiple information fields for all lines and call appearances of the card. Call State is also available as a subscribed service to allow unsolicited feedback to a connected control system via TTP. A full call state subscription update will be sent if any single part of the call state has changed.

VoIP Definitions

Line - A single extension on the SVC-2 card. A line will have a dedicated phone number and the voice signals for this line are available as an independent input and output in the Tesira system. Each SVC-2 card supports two lines and these lines may be used at the same time.

Call Appearance - Each line supports up to 6 call appearances. A call appearance can be viewed as a voice connection point on a line. A call appearance can be used to open another call from the same line by placing an active call on hold. Call appearances also allow the SVC-2 card to support call waiting.

Conference - The SVC card can create a local conference by joining two call appearances into a single active call. There is no support for a conference larger than a 3-way conference (two call appearances). It is possible to have an active 3-way conference on both lines of the SVC card at the same time.

VoIP X Definitions

Line - A line will have a dedicated phone number and the voice signals for this line are available as an independent input and output in the Tesira system. Each VoIP X supports one line.

Call Appearance - Each line supports up to 2 call appearances. A call appearance can be viewed as a voice connection point on a line. A call appearance can be used to open another call from the same line by placing an active call on hold. Call appearances also allow the VoIP X to support call waiting.

Conference - The VoIP X can create a local conference by joining two call appearances into a single active call.

Call State Requests

This command will give a onetime indication of the current state of the VoIP phone. The Instance Tag is variable and needs to match what is running in the current configuration.

Get the status of the Call State:

Instance Tag	Command	Attribute Code
VoIPControlStatus1	get	callState

NOTE: The following details and examples are specific to the SVC-2 VoIP implementation. VoIP X implementation will be limited according to its line and call appearance capability.

Subscriptions

Subscribe to a Call State

This command will set a subscription to a VoIP card’s current state. Please review the subscriptions section for more details. If any portion of the card’s call state changes, a subscription response will be provided indicating the current status of all call states.

The response of the subscription depends on the SESSION verbose State that was active at the time the subscription was setup. Examples will be given to show the response of a call state in both verbose and non-verbose formats.

Instance Tag	Command	Attribute Code	Index	Value
VoIPControlStatus1	subscribe	callState	[CustomLabel]	[Time(ms)]

Index can be used to assign a custom label to the subscription. This label is not required but is recommended, especially if there is more than one SVC-2 card in the system. The label would indicate to the control system which card is providing the state change. Instance Tags are not included in call state subscriptions responses.
Value can be used to throttle the rate of response to the control system. Since a call state subscription update is only provided after a state change there should be no need to place a value in this field. Placing a value, especially if it is too high, could introduce a missed update effectively getting the SVC card and the control system out of sync. By default the call state subscription has a 200ms delay, this ensures that the as many changed states as possible are included in a single call state response.
Subscriptions are lost when the Tesira server is rebooted.
Subscriptions can be revalidated by subscribing to the same block at regular intervals. If this is done ensure that the custom label used in Index is used in the re-subscription. If this label is not included it is possible to inadvertently open multiple subscriptions to the same call state.

Unsubscribing from a Call state.

This command will cancel a previously set subscription.

Instance Tag	Command	Attribute Code	Index
VoIPControlStatus1	unsubscribe	callState	[CustomLabel]

Call State Indication Fields

A Call State response will provide information for the entire SVC-2 card. The response will include both VoIP lines with 6 call appearances per line.

Example - Note Line feeds are shown to aid readability

! "publishToken":" Room1" "value":{"callStateInfo":[ {"state":VOIP_CALL_STATE_RINGBACK "lineId":0 "callId":0 "action":UI_DISPLAY_STATUS "cid":"\"07131038\"\"146\"\"\"" "prompt":VOIP_PROMPT_CONNECTING} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":1 "action": UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":2 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":3 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":4 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":5 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":0 "action":UI_DISPLAY_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":1 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":2 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":3 "action":UI_CLEAR_STATUS"cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":4 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":5 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED}]}

Call Appearance - Information included in Call State Response

Each call appearance provides the following information fields in the Call State response.

State

The State response gives the current operating conditions of the call appearance on the VoIP line.
The verbose indicator for the State field is: “state”
Non-Verbose indicator responses will be numeric and are shown below.

Below is a list of the possible state responses from a VoIP instance:

Verbose	Non-Verbose	Description
VOIP_CALL_STATE_INIT	1	The call appearance is initializing indicating general setup is in place; DHCP in progress, registration is taking place, etc. This can also indicate that the line has not been configured. The SVC-2 card will not be able to dial when this state is displayed.
VOIP_CALL_STATE_FAULT	2	General Fault condition; Network link is down, IP address conflict in place. The SVC-2 card will not be able to dial when this state is displayed.
VOIP_CALL_STATE_IDLE	3	Call Appearance is part of a registered connection to a Proxy Server and is ready to make or receive a call.
VOIP_CALL_STATE_DIALTONE	4	Call appearance is off hook and dial tone is present.
VOIP_CALL_STATE_SILENT	5	User has started dialing numbers but has yet to hit send
VOIP_CALL_STATE_DIALING	6	User has hit send on the call appearance and the card has sent an INVITE to the proxy or the called party. No response has been received at this point.
VOIP_CALL_STATE_RINGBACK	7	The far end is ringing
VOIP_CALL_STATE_RINGING	8	The call appearance has an incoming call
VOIP_CALL_STATE_ANSWER_CALL	9	The call has been answered but the call isn't active yet
VOIP_CALL_STATE_BUSY	10	The far end is busy
VOIP_CALL_STATE_REJECT	11	User has rejected the incoming call
VOIP_CALL_STATE_INVALID_NUMBER	12	The user has dialed an invalid number on this call appearance
VOIP_CALL_STATE_ACTIVE	13	A call has been connected to the call appearance
VOIP_CALL_STATE_ACTIVE_MUTED	14	A call is established but audio is muted in the VoIP Receive block
VOIP_CALL_STATE_ON_HOLD	15	The near end has placed the call appearance on hold
VOIP_CALL_STATE_WAITING_RING	16	The call appearance has received a call waiting indication
VOIP_CALL_STATE_CONF_ACTIVE	17	The call appearance has been placed in a local conference
VOIP_CALL_STATE_CONF_HOLD	18	The call appearance is part of a local conference that has been placed on hold
VOIP_CALL_STATE_XFER_INIT	19	The call appearance is initializing
VOIP_CALL_STATE_XFER_SILENT	20	The call appearance is silent
VOIP_CALL_STATE_XFER_REQ_DIALING	21	The call appearance is awaiting number to be dialed
VOIP_CALL_STATE_XFER_PROCESS	22	The call appearance is in a process of transferring
VOIP_CALL_STATE_XFER_REPLACES_PROCESS	23	The call appearance is updating the transfer process
VOIP_CALL_STATE_XFER_ACTIVE	24	The call appearance transfer is active
VOIP_CALL_STATE_XFER_RINGBACK	25	The call appearance is seeing DTMF tones from the proxy server
VOIP_CALL_STATE_XFER_ON_HOLD	26	The call appearance is on hold
VOIP_CALL_STATE_XFER_DECISION	27	The call appearance is awaiting confirmation to transfer
VOIP_CALL_STATE_XFER_INIT_ERROR	28	The call appearance has experienced an error initializing the transfer process
VOIP_CALL_STATE_XFER_WAIT	29	The call appearance is waiting

NOTE: The following details and examples are specific to the SVC-2 VoIP implementation. VoIP X implementation will be limited according to its line and call appearance capability.

Line ID

Each SVC-2 card supports two phone lines. A line is indicated as a unique extension on the VoIP system. The Line ID field indicates which line the particular Call State response is located on.
The first line is indicated as Line ID 0 and the second line is Line ID 1.
The verbose indicator for Line ID is: “lineId”. Note the upper case “I” in this indicator.

Call ID

Each line of the SVC-2 card supports six call appearances. A call appearance is defined as a separate phone connection point of a single phone extension. The Call ID field indicates which call appearance the particular Call State response is reporting.
The first call appearance of a line is indicated as Call ID 0 and the last call appearance of a line is indicated as Call ID 5.
The verbose indicator for Call ID is: “callId”. Note the upper case “I” in this indicator.

Action

The Tesira user interface supports the shifting of focus of a call appearance selection. For example if a call is in place on call appearance 1 and call appearance 2 rings, the user can shift focus in the UI to call appearance 2 to check Caller ID. This action would shift the focus from appearance 1 to 2.
The Call State response will indicate which call appearance is the point of focus for each line in the Action field. A control system program could track this action if multiple devices are providing VoIP dialer control.
There can only be a single focused call appearance per line.
The verbose indicator for Action is: “action”

Possible action responses from a SVC-2 card:

Verbose	Non-Verbose	Description
UI_CLEAR_STATUS	1	This call appearance is not the current point of focus in the user interface.
UI_DISPLAY_STATUS	2	This call appearance is the current point of focus in the user interface.

Caller ID

If caller ID information is available it will be included in the Call State response

Format

"\"MMDDHHmm\"\"incoming_number\"\"caller_Name\""

If no caller ID is available the Call State response for this field will be ""
The first set of quotes contains the date and time in the format MMDDHHmm.
The second set of quotes represents the incoming phone number in the format 5036417287.
The third set of quotes contains the name of the caller. If there are quotes contained within the name, there will be a backslash preceding the quotes within the name, i.e. “John \"Johnny\" Doe"
A Backslash ( \ ) is used as a separator in the caller ID string

Example of a caller ID response with all information provided

"\"07131134\"\"15036260281\"\"Biamp Systems\""

Example of a caller ID response without all information provided

"\"07131134\"\"15036260281\"\"\""

The verbose indicator for Caller ID is: “cid”

Prompt

The Tesira user interface provides prompting indications of the state of the call appearance that is currently in focus. This prompting information is also included in the Call State response. A control system can use the prompt indications to provide users information about the individual call appearance states. Note that a prompt is provided for each call appearance in the Call State response.

The verbose indicator for Prompt is: "prompt"

Below is a list of the possible prompt responses from a SVC-2 card:

Verbose	Non-Verbose	Description
VOIP_PROMPT_NONE	1	Nothing to display in prompt field
VOIP_PROMPT_STARTING	2	SVC-2 card is booting. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_REGISTERING	3	SVC-2 is registering to a Proxy Server. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_SIP_USER_NOT_CONFIGURED	6	SIP User field has not been configured on the line properties page. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_ENTER_NUMBER	7	SVC-2 card is off hook and waiting for a number entry
VOIP_PROMPT_CONNECTING	8	Connecting to the number dialed
VOIP_PROMPT_INCOMING_CALL_FROM	9	Incoming call from a far end
VOIP_PROMPT_PEER_BUSY	10	The far end device is busy
VOIP_PROMPT_CALL_CANNOT_BE_COMPLETED	11	The number called from the SVC-2 card cannot be completed
VOIP_PROMPT_ON_HOLD	12	The SVC-2 card has placed the call on hold
VOIP_PROMPT_CALL_ON_HELD	13	The far end device has placed the call on hold
VOIP_PROMPT_CONFERENCE	14	The SVC-2 card has placed this call appearances into a conference
VOIP_PROMPT_CONFERENCE_ON_HOLD	15	The SVC-2 card has placed a conference on hold
VOIP_PROMPT_CONNECTED	16	The call appearance is connected to a far end device
VOIP_PROMPT_CONNECTED_MUTED	17	The call appearance is connected to a far end device but the VoIP Receive block has been muted
VOIP_PROMPT_AUTH_FAILURE	18	Authentication to Proxy Server has failed
VOIP_PROMPT_PROXY_NOT_CONFIGURED	19	A Proxy Address has not been entered in the SVC line properties page
VOIP_PROMPT_NETWORK_INIT	20	The SVC-2 card is setting up network communications. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_DHCP_IN_PROGRESS	21	The SVC-2 card is requesting an IP address via DHCP. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_NETWORK_LINK_DOWN	22	The SVC-2 network link sees no connection. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_NETWORK_LINK_UP	23	The SVC-2 network port sees a connection point but cannot make use of it due to its current IP settings. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_IPADDR_CONFLICT	24	An IP Address is conflict has been detected. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_NETWORK_CONFIGURED	25	The SVC network interface has been configured. The SVC-2 card will not be able to dial when this prompt is displayed.
VOIP_PROMPT_CODEC_NEGOTIATION_FAILURE	26	Codec negotiation between the endpoints has failed
VOIP_PROMPT_UNEXPECTED_ERROR	27	The SVC card has encountered an unexpected error
VOIP_PROMPT_AUTH_USER_NOT_CONFIGURED	28	Authentication Username has not been configured in the SVC line properties page
VOIP_PROMPT_AUTH_PASSWORD_NOT_CONFIGURED	29	Authentication Password has not been configured in the SVC line properties page
VOIP_PROMPT_DND	30	Do Not Disturb
VOIP_PROMPT_INVALID_NUMBER	31	Invalid Dialed Number (Number not routable by proxy server)
VOIP_PROMPT_TEMP_UNAVAILABLE	32	Temporary Not Available (The callee is temporarily unavailable such as DND is on)
VOIP_PROMPT_DECLINED	33	Call is Declined (the call is declined by the far end or the server)
VOIP_PROMPT_SERVICE_UNAVAILABLE	34	Service Unavailable (such as a PSTN call but PSTN gateway isn’t configured or no rule to get there)
VOIP_PROMPT_FORBIDDEN	35	Call Forbidden (The call is prohibited because of policy)
VOIP_PROMPT_BEING_XFER_TO	36	Call is Being Transfer to
VOIP_PROMPT_XFER_IN_PROCESS	37	Transfer in Process
VOIP_PROMPT_XFER_TIME_OUT	38	Transfer Timeout (Transfer not finished in a designated time)
VOIP_PROMPT_PROXY_UNAVAILABLE	39	Proxy Unavailable (such as the configurable proxy is down)

Syntax of the Call State Response

Call State response information order:

The Call State response will present the information listed above for each line and call appearance of the VoIP instance. If a subscription to a Call State response is setup, the subscription will update if a change is detected in any of the information fields. Call State is available in both verbose and non-verbose responses. Below is an example of the order of information in a Call State response. Note that the “{….}” field indicates the additional lines and call appearances on the VoIP instance.

HEADER_TOKEN:[{STATE: LINE_ID: CALL_ID: ACTION: CALLER_ID: PROMPT} {….} {….}]

Call State subscription header examples

All subscription responses will start with the “!” character for easy recognition. The response will also include token information in the form of the custom label associated with the subscription. Custom labels are defined in the Index command when the subscription is setup. Below is an example or the subscription header of a Call State response in both verbose and non-verbose formats. In each case the custom label was defines as “Room_1” and the “{…}” symbol indicates the additional responses from the specific call appearances.

NOTE: The following details and examples are specific to the SVC-2 VoIP implementation. VoIP X implementation will be limited according to its line and call appearance capability.

Verbose Format

! "publishToken":" Room_1" "value":{"callStateInfo":[{….} {….}]}

Non-Verbose Format

! "Room_1" [[….] [….]]

Single Call Appearance response examples

Below is an example of a response from a single call appearance in both verbose and non-verbose formats. This information is intended to show a clear example of the response order of a single appearance.

The call in each example shows the call state after a call was placed on line 0, call appearance 3, with the far end currently ringing. Caller ID information is also included.

Verbose Format

{"state":VOIP_CALL_STATE_RINGBACK "lineId":0 "callId":3 "action":UI_DISPLAY_STATUS "cid":"\"07131124\”\”146\”\”John Smith\”” "prompt":VOIP_PROMPT_CONNECTING}

Non-Verbose Format

[7 0 3 2 "\"07131124\”\”146\”\”John Smith\”” 8]

Call State full command examples

An actual Call State response will include two separate lines, each with 6 call appearances. An example of a full response is provided below in both verbose and non-verbose formats. The following responses show a ring-back on line 0, call appearance 0. All other call appearances on line 0 are idle. Line 1 has not been configured.

Verbose Format

! "publishToken":" Room 1" "value":{"callStateInfo":[{"state":VOIP_CALL_STATE_RINGBACK "lineId":0 "callId":0 "action":UI_DISPLAY_STATUS "cid":"\"07131038\"\"146\"\"\"" "prompt":VOIP_PROMPT_CONNECTING} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":1 "action": UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":2 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":3 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":4 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_IDLE "lineId":0 "callId":5 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_NONE} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":0 "action":UI_DISPLAY_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":1 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":2 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":3 "action":UI_CLEAR_STATUS"cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":4 "action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED} {"state":VOIP_CALL_STATE_INIT "lineId":1 "callId":5"action":UI_CLEAR_STATUS "cid":"" "prompt":VOIP_PROMPT_SIP_USER_NOT_CONFIGURED}]}

Non-Verbose Format

! "Room_1" [[[7 0 0 2 "\"07131038\"\"146\"\"\"" 8] [3 0 1 1 “” 1] [3 0 2 1 “” 1] [3 0 3 1 "" 1] [3 0 4 1 "" 1] [3 0 5 1 "" 1] [1 1 0 2 "" 6] [1 1 1 1 “” 6] [1 1 2 1 “” 6] [1 1 3 1 "" 6] [1 1 4 1 "" 6] [1 1 5 1 "" 6]]]