A Call Macro is a token that holds a value relating to the current call. For example, to vocalize a phrase to a caller such as "Hello 02071234567" (where 02071234567 is the caller’s number), a routing policy needs to be able to find out the caller number, which is different on each call received. To identify the caller number for the current call, the notation $(CallerNumber) is used.
Macro names are always expressed in the form $(<MacroName>), for example, $(CallerNumber). There are both simple and complex macros. When used with a Data or Scripting app (AVS) or component (Portal), complex macros can allow multiple items of data to be stored and referenced.
This is a list of macros that are supported and which are relevant to Call and Non-CallPolicies. These can be utilized in
Routing Policies
Natterbox Call Centre Configuration
The following is a full list of macros supported to be used within the Natterbox system when routing calls, ordered alphabetically:
Macro Name
Type
Call Policy
Category
Non-Call Policy
Description
A
$(ActiveRecAnswerEpochMS)
Simple
NO
Time/Date
YES
The epoch value (in milliseconds) for when the Active Record Call was answered by the Call Recorder. This epoch value is synced to NTP and is provided to millisecond granularity. Together with the $(ActiveRecCLI) macro, this allows a call on the recorder to be identified unambiguously.
$(ActiveRecAudio)
Simple
NO
Active Record
YES
An indication as to whether there is audio included in the Active Record channel. If Active Record couldn't send audio to the remote recorder because the call was relayed via a Non Camel network or the Active Record channel couldn't be connected, this will be set to 'no'. If audio was successfully streamed, then the value will be set to 'yes'.
$(ActiveRecCLI)
Simple
NO
Active Record
YES
The E164 CLI that was presented in the Active Record Call Leg to the Call Recorder. This will be used by the Call Recorder to associate the metadata item with the audio record in the recorder.
$(ActiveRecCLILocal)
Simple
NO
Active Record
YES
The CLI (Calling Line Indicator) that was sent to the Active Recorder. This is typically used in non-call policies to send metadata to the call recorder and provide an indication of the CLI that was specified on a given call. This macro provides the CLI in national format according to the Organisation's Home Country Code setting.
$(ActiveRecCreatedEpochMS)
Simple
NO
Active Record
YES
The epoch value (in milliseconds) when the Active Record channel for a given call was created by the platform.
$(ActiveRecName)
Simple
YES
Active Record
YES
The identity name of the Active Record recorder that was used by the switch. In a scenario where multiple recorders are configured in a parallel or serial dialed architecture for redundancy, the $(RecordName) macro indicates which Recorder answered the call. The name is taken from the Identity configuration on the Active Record sub-item.
$(ActiveRecSetupDelayMS)
Simple
NO
Active Record
YES
Value in milliseconds of how long the Active Record Call leg took to establish. Useful for diagnostics purposes.
$(ActiveRecStatus)
Simple
NO
Active Record
YES
Indicates the recording status of the Conversational Call relating to this metadata item.
Initialised: The Active Record sub-item has been initialized, but the AR Leg has not yet been answered.
Answered: The Active Record Leg has now been answered and is parked ready to connect to the Conversational A Leg as soon as it answers.
Streamed: Call was successfully streamed to the call recorder
Buffered: Call was successfully buffered and then submitted to the call recorder
DisruptedHangup: The Active Record Channel was disrupted. There may be a partial recording on the call recorder. The conversational A->B call has been hung up (according to policy)
DisruptedContinue: The Active Record Channel was disrupted. There may be a partial recording on the call recorder. The conversational A->B call continued (according to policy)
NoConnectHangup: The Active Record Channel could not be established in time. There shouldn’t be any record of the Call on the recorder (although note that there are race condition possibilities that could cause millisecond recordings). The conversational A->B call was hung up (according to policy)
NoConnectContinue: The Active Record Channel could not be established in time. There shouldn’t be any record of the Call on the recorder (although note that there are race condition possibilities that could cause millisecond recordings). The conversational A->B call continued (according to policy)
NonCamel: The Metadata that this call is associated with does not have any audio associated with it as is a Non Camel record.
C
$(CallAnswerEpochMS)
Simple
NO
Time/Date
YES
The epoch value (in milliseconds) detailing when the call was answered. This epoch value is synced to NTP and is provided to millisecond granularity. Note that this value may significantly differ from the $(RecordAnswerEpochMS) value since a call may have been buffered and re-streamed.
$(CallCategory)
Simple
NO
Call Properties
YES
Returns the Call Category type for a channel. See the section Call Categories at the end of this document for details on the Call Category codes.
$(CallComponentStartName)
Simple
YES
Call Properties
YES
The sub-item Start Name that was activated when the channel activated the dial-plan policy.
$(CallConnected)
Simple
NO
Call Statistics
YES
Indicates if the call was connected to the called party. If connected then the macro will expand to the value 'Yes'. If not connected, then it expands to the value 'No'.
$(CallDurationSeconds)
Simple
YES
Call Statistics
YES
The number of seconds that the call was active for from the point that the caller first initiates the call, to the point they hang up, regardless of whether or not the called party picks up the phone.
$(CalledCountryShort)
Simple
YES
Call Properties
YES
The three letter ISO code of the country that was called. For example GBR or FRA (for UK and France) respectively.
$(CalledNumber)
Simple
YES
Numbers
YES
Expands to the dialed number.
If the call is an Inbound Call, then this will be the PSTN number that the call was accepted on. It will be in national dial format if the number matches the Home Country Code of the Organisation or User, e.g. 07740123456. If it is an international caller number then it will be in E164 format without the +, e.g. 3339329328392 for a French Caller Number (note the leading 33 French country code).
If the call is an Outbound Call, then this will be a PSTN number the user dialed. It will be in national dial format if the number matches the Home Country Code of the Organisation or User, e.g. 07740123456. If it is an international caller number then it will be in E164 format without the +, e.g. 3339329328392 for a French Caller Number (note the leading 33 French country code).
If call withheld and/or external access prefixes have been used on the number then these are all stripped, e.g.
If country code is UK (44), external access is 9 and withheld is 141, then:
07740980123 -> 07740980123
0033243123456 -> 33243123456
907740980123 -> 07740980123
914107740980123 -> 07740980123
$(CalledNumberIn)
Simple
YES
Numbers
YES
Expands to the inbound dialed number.
If the call is an Inbound Call from the PSTN, then this will be the PSTN number that was dialed and subsequently accepted by the dial-plan policy. If this is a DDI, then it will be the dialed DDI number that the call was accepted on. It will be in national dial format if the number matches the Home Country Code of the Organisation or User, e.g. 0158223456. If the number is an international number, then it will be in E164 format without the +, e.g. 3339329328392 for a French Caller Number (note the leading 33 french country code).
If this macro is used elsewhere on a dial-plan policy where a call has not been received from the PSTN, then it will expand as empty.
$(CalledRoaming)
Simple
YES
Call Properties
YES
If the called number (of the Conversational Call) is a roaming mobile (must be a subscriber of the service), then this indicates the country the call is being made to. The format is the three letter ISO country code. For example GBR or FRA (for UK and France) respectively.
$(CallEndDate)
Simple
NO
Time/Date
YES
Expands to the end date and time of the call. The format is yyyy-mm-dd hh:mm:ss, e.g. 2011-05-28 23:43:21.
$(CallEndDateShort)
Simple
NO
Time/Date
YES
The date that the call was hung up. This is presented in the format yyyy-mm-dd, e.g. 2015-05-12.
$(CallEndDateUTC)
Simple
NO
Time/Date
YES
The time that the call was hung up in UTC format, e.g. yyyy-mm-dd\Thh:mm:ss\Z, e.g. 2015-05-12T12:34:54Z.
$(CallEndEpoch)
Simple
YES
Time/Date
YES
The time that the call was hung up in epoch time, i.e. number of seconds since 1st January 1970 GMT.
$(CallEndEpochMS)
Simple
NO
Time/Date
YES
The time that the call was hung up in epoch time, i.e. number of milliseconds since 1st January 1970 GMT.
$(CallEndTime)
Simple
NO
Time/Date
YES
The time that the call was hung up. This is presented in the format hh:mm:ss, e.g. 12:34:54.
$(CallerCountryShort)
Simple
YES
Call Properties
YES
The three letter country code associated with the caller number, e.g. FRA for France.
$(CallerEmailAddress)
Simple
YES
Call Properties
YES
The caller's email address (which will be the same as their login name), if the caller has an account on the service, otherwise the result is blank.
$(CallerFirstName)
Simple
YES
Call Properties
YES
The caller's first name, if the caller has an account on the service, otherwise the result is blank.
$(CallerGroup)
Simple
YES
Call Properties
YES
The caller's primary group name, if the caller has an account on the service, otherwise the result is blank.
$(CallerIdentity)
Simple
YES
Call Properties
NO
$(CallerLastName)
Simple
YES
Call Properties
YES
The caller's last name, if the caller has an account on the service, otherwise the result is blank.
$(CallerNumber)
Simple
YES
Numbers
YES
$(CallerNumber) expands to the caller number.
If the call is an Inbound Call, then this will be a PSTN number. It will be in national dial format if the number matches the Home Country Code of the Organisation or User, e.g. 07740123456. If it is an international caller number then it will be in E164 format without the +, e.g. 3339329328392 for a French Caller Number (note the leading 33 french country code).
If the call is an Outbound Call, then this will be the user's extension if a user is mapped to a device.
If no user is mapped to the calling device, then this will be the device extension number.
The value returned will be the SIP User part (in preference) from the P-Preferred-Identity, P-Asserted-Identity, Remote-Party-ID, and the From header received by the Soft Switch.
$(CallerRoaming)
Simple
YES
Call Properties
YES
If the caller (of the Conversational Call) is a roaming mobile (must be a subscriber of the service), then this indicates the country from which the call is being made from. The format is the three letter ISO country code. For example GBR or FRA (for UK and France) respectively.
$(CallerType)
Simple
YES
Call Properties
YES
$(CallerType) indicates the type of caller. It will be one of three values:
device: indicates the caller is a device and no user is mapped to that device
user: indicates the caller is a user
external: indicates the caller is external
$(CallerUserAgent)
Simple
YES
Call Properties
YES
If the calling phone makes its user agent name available in the SIP headers, then this expands the name.
$(CallHuntSeconds)
Simple
NO
Call Statistics
YES
Number of seconds that the call took to hunt for a connection. Hunt time is calculated as the time between which the call is answered by the platform and the time to then connect that call to a device, e.g. a sip phone, PSTN line, etc.
$(CallOwner)
Simple
YES
Call Properties
YES
Indicates which platform subscriber logically owns the call, i.e. which user the call is associated with. Values are 'Caller', 'Called', 'Unknown'.
$(CallPolicyStartName)
Simple
YES
Call Properties
YES
The dial-plan policy that was activated when the channel was initiated.
$(CallQueueLastDisposition)
Simple
NO
Call Properties
YES
Indicates result of last call queue caller was in during the call. Will be one of answered, timeout, hangup or abandoned (where abandoned means caller pressed a configured DTMF key to exit the queue)
$(CallQueueLastWaitTimeSeconds)
Simple
NO
Call Properties
YES
Indicates the time in seconds the caller waited in the last call queue they were in during the call
$(CallQueuePos)
Simple
YES
Call Properties
NO
Expands to the position of the call in the call queue. Note that this can only be used in Call Queues.
$(CallQueueTotalWaitTimeSeconds)
Simple
NO
Call Properties
YES
Indicates the total time in seconds the caller waited in all call queues during the course of the call
$(CallRingSeconds)
Simple
NO
Call Statistics
YES
Number of seconds the channel was ringing for before the platform answered the call.
$(CallSecondsToAnswer)
Simple
NO
Call Statistics
YES
Number of seconds the channel was in a ring state before it was answered.
$(CallStartDate)
Simple
YES
Time/Date
YES
The start date and time of the call. The format is yyyy-mm-dd hh:mm:ss, e.g. 2011-05-28 23:43:21.
$(CallStartDateShort)
Simple
NO
Time/Date
YES
The date that the call was initiated, i.e. received by the platform or initiated by the platform. This is presented in the format yyyy-mm-dd, e.g. 2015-05-12.
$(CallStartDateUTC)
Simple
NO
Time/Date
YES
The time that the call was initiated, i.e. received by the platform or initiated by the platform in UTC format, e.g. yyyy-mm-dd\Thh:mm:ss\Z, e.g. 2015-05-12T12:34:54Z.
$(CallStartEpoch)
Simple
YES
Time/Date
YES
The time that the call was initiated, i.e. received by the platform or initiated by the platform in epoch time, i.e. number of seconds since 1st January 1970 GMT.
$(CallStartEpochMS)
Simple
NO
Time/Date
YES
The time that the call was initiated, i.e. received by the platform or initiated by the platform in epoch time, i.e. number of milliseconds since 1st January 1970 GMT.
$(CallStartTime)
Simple
NO
Time/Date
YES
The time that the call was initiated, i.e. received by the platform or initiated by the platform. This is presented in the format hh:mm:ss, e.g. 12:34:54.
$(CallTalkSeconds)
Simple
NO
Call Statistics
YES
The number of seconds that the call was active for from the point that the called party accepted the call, i.e. the number of seconds that the two parties were connected for.
$(ConnectedEmailAddress)
Simple
YES
Call Properties
YES
If the call is connected to the called party, and the called party has an account on the service, then the $(ConnectedEmailAddress) macro will expand to their configured to their email address, which will be the same as their login name. If no account is found and/or the call is not connected then the result will be blank.
$(ConnectedFirstName)
Simple
YES
Call Properties
YES
If the call is connected to the called party, and the called party has an account on the service, then the $(ConnectedFirstName) macro will expand to their configured first name, otherwise the result is blank.
$(ConnectedGroup)
Simple
NO
Call Properties
YES
If the call is connected to the called party, and the called party has an account on the service, then the $(ConnectedGroup) macro will expand to their configured primary group if one is configured, otherwise the result is blank.
$(ConnectedLastName)
Simple
YES
Call Properties
YES
If the call is connected to the called party, and the called party has an account on the service, then the $(ConnectedLastName) macro will expand to their configured last name.
$(ConnectedNumber)
Simple
YES
Call Properties
YES
If the call is connected to the called party, and the called party is an external PSTN number, this will be the number of that party.
It will be in national dial format if the number matches the Home Country Code of the Organisation or User, e.g. 07740123456. If it is an international caller number then it will be in E164 format without the +, e.g. 3339329328392 for a French Caller Number (note the leading 33 French country code).
$(ConnectedType)
Simple
YES
Call Properties
YES
The type of the target that the call was connected to. If the call is connected to an external number, then this will be external. If connected to a user, then the value will be user, and finally if connected to an internal phone with no user mapped, the value will be device. If the call is not connected, the value will be blank.
$(ConnectedUserAgent)
Simple
YES
YES
If the connected phone makes its user agent name available in the SIP headers, then this expands the name.
$ConnectedUserId)
Simple
NO
Call Properties
YES
If the call is connected to another User in the organization, then this macro will expand to the User ID that is associated with that user.
$(ConnectedUUID)
Simple
YES
Call Properties
YES
Expands to the unique ID of the connected call leg.
$(Custom_
Complex
YES
Special
YES
A Custom Macro that has been created by the user of the platform. e.g. $(Custom_MyFavColour).
D
$(DialledNumber)
Simple
YES
Numbers
YES
The number that was actually dialed by the caller. This will include any prefix codes such as 9 (for an external number) or 141 (to withhold a CLI). If the call had been made via a dial-plan policy extension, then the DialledNumber would be the dial-plan policy extension that was dialed.
$(DeviceId)
Simple
NO
Call Properties
YES
The Device Id that is connected to the current channel being processed by the Non Call Policy. If no Device Id is connected to the channel, then an empty value is returned
E
$(E164CalledNumber)
Simple
YES
Numbers
YES
The dialed number is in E164 format. The same rules as for the $(CalledNumber) apply, except that the number will be an E164 formatted number without the leading +.
$(E164CalledNumberIn)
Simple
YES
Numbers
YES
The inbound dialed number in E164 format. The same rules as for the $(CalledNumberIn) apply, except that the number will always be an E164 formatted number without the leading +.
$(E164CallerNumber)
Simple
YES
Numbers
YES
The caller number is in E164 format. If the call is an Inbound Call, then this will be a PSTN number. It will be in E164 format without the +, e.g. 447740123456 for a UK number.
If the Call is an Outbound Call, then the macro will be empty, i.e. there is no E164 version of a user extension. The value returned will be the SIP User part (in preference) from the P-Preferred-Identity, P-Asserted-Identity, Remote-Party-ID, and the From header received by the Soft Switch.
$(E164ConnectedNumber)
Simple
YES
Numbers
YES
If the call is connected to the called party, and the called party is an external PSTN number, this will be the number of that party.
The same rules as for $(ConnectedNumber) apply, except that the number will be an E164 formatted number without the leading +.
$(E164DiversionNumber)
Simple
YES
Numbers
YES
If the called number has a diversion configured on it by an external provider, then this macro will expand to that number. Note that not all third party providers will provide diversion information.
$(ExtensionNumber)
Simple
YES
Numbers
YES
Expands to the Extension Number of the channel.
F
$(Fn_Rand{randNumLen})
Function
YES
Functions
NO
A Randomisation function to return a random number of up randNumLen length, e.g. $(Fn_Rand{4}) will generate a random number of 4 digits in length.
$(Fn_UUID)
Function
YES
Functions
NO
A function to return a UUID
H
$(HangupCause)
Simple
YES
Call Properties
YES
The hangup cause indicating how and why the call was terminated.
$(HoldTime)
Simple
NO
Call Statistics
YES
Amount of time in seconds the channel was placed on hold
$(HomeCountryCode)
Simple
YES
Call Properties
YES
The telephone country code that is defined for the user. For example, in the UK this will be 44.
$(HTTP_
Complex
YES
Data Source
YES
A Complex macro for access responses from the HTTP Connector.
M
$(MobileNumber)
Simple
YES
Numbers
NO
The Mobile Number associated with the user record. If a user is not associated with the call, then a blank entry is returned.
$(MSD_[resultset].[field])
Complex
YES
Data Source
YES
A Microsoft Dynamics result set is a complex macro that is created in an MSD Store or MSD Query sub-item. The [resultset] must be replaced with the result set name that was specified and [field] with the field name to be expanded.
N
$(Numbers_
Complex
YES
Special
YES
A complex macro allowing access to the Registered Users properties
O
$(OriginateDisposition)
Simple
NO
Call Properties
YES
Returns the origination disposition for a channel, e.g. an indication of whether the call was connected successfully, and if not the reason why. For example, if the channel was busy, the disposition value might be USER_BUSY.
$(OwnerEmail)
Simple
NO
Call Properties
YES
The email address for the owner of the call.
$(OwnerFirstName)
Simple
NO
Call Properties
YES
The first name for the owner of the call.
$(OwnerLastName)
Simple
NO
Call Properties
YES
The last name for the owner of the call.
$(OwnerUserId)
Simple
NO
Call Properties
YES
Returns the logical owner's UserId of the channel. For example, when a call is made to a DDI or a Mobile number, the A Leg of the channel will not be attached to the User and won't necessarily have a UserID; this will belong to the B Leg. However, since the number will most likely be connected to the User (by virtue of the fact they own the Number), this macro indicates that ownership.
P
$(PolicyStartType)
Simple
YES
Call Properties
YES
Indicates which Start sub-item type the call was initiated through:
public: The call initiated on the Start/Number sub-item
extension_hook: The call initiated on the Start/Extension sub-item
outbound_hook: The call initiated on the Start/Outbound sub-item
DDI: The call initiated on the Start/DDI sub-item
default: The call did not start on any of these sub-items and was handled internally via the default policies
R
$(Recording)
Simple
YES
Call Properties
YES
Expands to a URL link to the voice recording, if voice recording has been enabled on the call.
$(RecordingB)
Simple
YES
Call Properties
YES
Expands to a URL link to the voice recording on the B channel, if voice recording has been enabled on the call.
$(RecordingPaused)
Simple
NO
Call Properties
YES
Indicates if the recording was paused. Valid values are 'yes', 'no'
$(Redirected)
Simple
NO
Call Properties
YES
Indication if the call has been Redirected. There are two forms of redirect; a late forward (redirect has occurred on phone) and early forward (redirect has occurred as a result of the MNO). Possible values are 'LateFwd' and 'EarlyFwd'. In the case of a LateFwd, it is possible that the redirected call leg will cause another recording to occur on the recorder as in essence these are two separate call legs. Note that this feature is only available on selected MNO call flows.
S
$(ScreenCaller)
Simple
YES
Call Properties
NO
Only available in the Scripting Engine. Indicates if the B Leg has requested that Call Screening should be enabled. Valid values are 'yes' or 'no'
$(Service)
Simple
NO
Call Properties
YES
Indicates which service (if any) the Conversational Call was connected to. Typically, this would indicate voicemail. Other example services could include: Voicemail, Record, Call Return, Voicemail Login, Echo.
$(SForce_[resultset].[field])
Complex
YES
Complex
YES
A Sales Force result set is a complex macro that is created in an SF Store or SF Query sub-item. The [resultset] must be replaced with the result set name that was specified and [field] with the field name to be expanded.
$(SMSBody)
Simple
NO
Call Properties
YES
If processing an SMS, return the body of the SMS.
$(SMSDirection)
Simple
NO
YES
If processing an SMS, return the direction of the SMS. Valid values are sent and received.
$(SMSSentDateUTC)
Simple
NO
Time/Date
YES
If processing an SMS, return the Sent Date of the SMS in UTC format.
$(SMSSentEpoch)
Simple
NO
Time/Date
YES
If processing an SMS, return the Sent Date of the SMS in epoch format.
$(SolidCall)
Simple
NO
Call Statistics
YES
Expands to yes or no depending on whether the call is regarded as solid.
$(SolidCallThreshold)
Simple
NO
Call Statistics
YES
Expands to the value in seconds of the Solid Call Threshold.
$(Sugar_[resultset].[field])
Complex
YES
Data Source
YES
A Sugar result set is a complex macro that is created in a Sugar Store or Sugar Query sub-item. The [resultset] must be replaced with the result set name that was specified and [field] with the field name to be expanded.
$(System_Log.[field])
Complex
NO
Call Statistics
YES
Provides a set of records matching field for field with Portal Logs for a given conversation. Furthermore additional fields not available in the portal logs are provided.
It is important to note that the macro returns one record set per Interaction, where an interaction typically relates to a conversation between an A and B Party (From and To). Where calls are not connected, then this will also generate an Interaction. The From and/or To party may exist in multiple Interactions, e.g. when a call is transferred. The Instance fields on the From and To party records indicate how many times they have appeared in different Interactions for a given call.
Some of the fields relate to the totality of a From or To party's call, i.e. the start and end time regardless of how many times the other party was transferred. Other fields relate to a specific Interaction, i,e. the start and end time of an interaction. In general if performing reports, then when looking at total call stats for a given party, only query on records where the Instance value = 0.
Note that in order for this macro to be functional a given Non Call policy needs to contain the Call Log Capture component. In order to access this component, the Org needs to have its "Statistics Level" set to Advanced.
Field Name
Interaction|Call
Description
AUUID
Call
The UUID associated with the A Leg of the conversation
BUUID
Call
The UUID associated with the B Leg of the conversation
*From_Number
Call
The number that made the call, associated to the A Leg
From_NumberDialled
Call
The number that the From party dialed
From_DevID
Call
The SIP Device Id that the conversation originated from. Will be set to 0 if no Device ID was used to originate the call, i.e. originated from a PSTN number
From_UserID
Call
The User Id that the conversation originated from. Will be set to 0 if no User ID was used to originate the call, i.e. a call from an external source
From_Hangup
Call
The Hangup cause associated with the calling party
From_PolArchID
Call
The organization wide archiving policy Id that the conversation has been archived with is based on archiving from the point of view of the From (A Leg). Will be set to 0 if archiving hasn't taken place
From_PnArchID
Call
The personal archiving policy Id that the conversation has been archived with based on archiving from the point of view of the From (A Leg). Will be set to 0 if archiving hasn't taken place
From_Instance
Interaction
The instance of the conversation for this caller starts at 0. If this leg of the call has been transferred to multiple other legs throughout its life time the From_Instance defines which instance of a conversation this record relates to
From_TotalInstances
Call
Defines how many conversations this leg of the call has been a part of, i.e. if the From party is transferred from the To Party to another To party, then there will be 2 instances.
From_Channel_StartEpoch
Call
The epoch time at which the channel was initiated
From_Channel_AnswerEpoch
Call
The epoch time at which the channel was actually answered by the switch.
From_Channel_EndEpoch
Call
The epoch time at which the channel was actually hung up
From_Channel_StartTime
Call
The ISO 8601 date at which the channel was initiated
From_Channel_AnswerTime
Call
The ISO 8601 date at which the channel was actually answered by the switch.
From_Channel_EndTime
Call
The ISO 8601 date at which the channel was actually hung up
From_Duration
Call
The duration is seconds of when the leg was answered to when it hung up. Note that, if the call is transferred then the duration always refers to the total connection time for the From Party and not for the individual conversations.
From_StartEpoch
Interaction
The epoch time at which the conversation was started. For instance 0, this will be the time the call hits the switch. For instances > 0, will normally be the same as the From_BridgeEpoch
From_AnswerEpoch
Interaction
The epoch time at which the conversation was answered. For instance 0, this will be the time the call really gets answered by either an IVR or a Device. For instances > 0, will normally be the same as the From_BridgeEpoch
From_BridgeEpoch
Interaction
The epoch time at which the conversation was bridged to the To party in the conversation
From_EndEpoch
Interaction
The ISO 8601 date at which the conversation ended. For the last instance, this will be the time the call really hangs up. For all other instances, will be the time the call is bridged to the next party
From_StartTime
Interaction
The ISO 8601 date at which the conversation was started. For instance 0, this will be the time the call hits the switch. For instances > 0, will normally be the same as the From_Bridge
From_AnswerTime
Interaction
The ISO 8601 date at which the conversation was answered. For instance 0, this will be the time the call really gets answered by either an IVR or a Device. For instances > 0, will normally be the same as the From_Bridge
From_BridgeTime
Interaction
The ISO 8601 date at which the conversation was bridged to the To party in the conversation
From_EndTime
Interaction
The epoch time at which the conversation ended. For the last instance, this will be the time the call really hangs up. For all other instances, will be the time the call is bridged to the next party
From_CallType
Call
The Call Type of this channel. See Call Type definitions at end of this page
From_FirstName
Call
The first name of the From party if known
From_LastName
Call
The last name of the From party if known
From_EmailAddress
Call
The address associated with the From party if known
From_CallQueueLastDisposition
Call
The disposition of the last call queue that the From leg of this call was routed to: TIMEOUT (call queue timed out and call was passed to next item in policy), ANSWERED (call was connected to an agent), ABANDONED (caller pressed a key to exit from the call queue), HANGUP (caller hung up the call whilst still in the call queue)
From_CallQueueLastWaitTime
Call
The duration of time in seconds that this call spent waiting to be connected to an agent in the last call queue
From_CallQueueTotalWaitTime
Call
The duration of time in seconds that this call spent waiting to be connected to an agent in the all call queues
From_CallQueueLastQueue
Call
The Queue Id of the last call queue that was used on this channel
From_UsedOnHold
Call
The duration in seconds relating to how much time this party placed the other parties on hold
From_JSONCustomVars
Call
A JSON list of property/values corresponding to any Custom Variables that have been set in policies
*To_Number
Call
The number that the call was connected to
*To_NumberDialled
Call
The actual number that was dialed by the user on the A Leg
To_DevID
Call
The SIP Device Id that the conversation originated to. Will be set to 0 if no Device ID was used to originate the call, i.e. originated from a PSTN number
To_UserID
Call
The User Id that the conversation originated to. Will be set to 0 if no User ID was used to originate the call, i.e. a call from an external source
To_Hangup
Call
The Hangup cause associated with the called party
To_PolArchID
Call
The organization-wide archiving policy Id that the conversation has been archived with is based on archiving from the point of view of the To (B Leg). Will be set to 0 if archiving hasn't taken place
To_PnArchID
Call
The personal archiving policy Id that the conversation has been archived with based on archiving from the point of view of the To (B Leg). Will be set to 0 if archiving hasn't taken place
To_Instance
Interaction
The instance of the conversation for this caller starts at 0. If this leg of the call has been transferred to multiple other legs throughout its life time the To_Instance defines which instance of a conversation this record relates to
To_TotalInstances
Call
Defines how many conversations this leg of the call has been a part of, i.e. if the From party is transferred from the To Party to another To party, then there will be 2 instances.
To_RealStartEpoch
Call
The epoch time at which the channel was initiated
To_RealAnswerEpoch
Call
The epoch time at which the channel was actually answered by the switch.
To_RealEndEpoch
Call
The epoch time at which the channel was actually hung up
To_RealStart
Call
The ISO 8601 date at which the channel was initiated
To_RealAnswer
Call
The ISO 8601 date at which the channel was actually answered by the switch.
To_RealAnswer
Call
The ISO 8601 date at which the channel was actually hung up
To_Duration
Call
The duration is seconds of when the leg was answered to when it hung up. Note that, if the call is transferred then the duration always refers to the total connection time for the From Party and not for the individual conversations.
To_StartEpoch
Interaction
The epoch time at which the conversation was started. For instance 0, this will be the time the call hits the switch. For instances > 0, will normally be the same as the To_BridgeEpoch
To_AnswerEpoch
Interaction
The epoch time at which the conversation was answered. For instance 0, this will be the time the call really gets answered by either an IVR or a Device. For instances > 0, will normally be the same as the To_BridgeEpoch
To_BridgeEpoch
Interaction
The epoch time at which the conversation was bridged to the To party in the conversation
To_EndEpoch
Interaction
The ISO 8601 date at which the conversation ended. For the last instance, this will be the time the call really hangs up. For all other instances, will be the time the call is bridged to the next party
To_StartTime
Interaction
The ISO 8601 date at which the conversation was started. For instance 0, this will be the time the call hits the switch. For instances > 0, will normally be the same as the To_Bridge
To_AnswerTime
Interaction
The ISO 8601 date at which the conversation was answered. For instance 0, this will be the time the call really gets answered by either an IVR or a Device. For instances > 0, will normally be the same as the To_Bridge
To_BridgeTime
Interaction
The ISO 8601 date at which the conversation was bridged to the To party in the conversation
To_EndTime
Interaction
The epoch time at which the conversation ended. For the last instance, this will be the time the call really hangs up. For all other instances, will be the time the call is bridged to the next party
To_CallType
Call
The Call Type of this channel. See Call Type definitions at end of this page
To_FirstName
Call
The first name of the From party if known
To_LastName
Call
The last name of the From party if known
To_EmailAddress
Call
The address associated with the From party if known
To_CallQueueLastDisposition
Call
The disposition of the last call queue that the From leg of this call was routed to: TIMEOUT, ANSWERED, ABANDONED, HANGUP
To_CallQueueLastWaitTime
Call
The duration of time in seconds that this call spent waiting to be connected to an agent in the last call queue
To_CallQueueTotalWaitTime
Call
The duration of time in seconds that this call spent waiting to be connected to an agent in the all call queues
To_CallQueueLastQueue
Call
The Queue Id of the last call queue that was used on this channel
To_UsedOnHold
Call
The duration in seconds relating to how much time this party placed the other parties on hold
To_JSONCustomVars
Call
A JSON list of property/values corresponding to any Custom Variables that have been set in policies
Time_Ringing
Interaction
Time_Hunting
Interaction
Time_Talking
Interaction
$(System_Transfer.[field])
Complex
NO
Special
YES
Provides a set of records detailing the transfer history for the call. The transfer history is provided in the context of the leg of the call that the record is being accessed. The transfer history provides one record for each `other` leg that the call was connected to during its lifetime. Each record contains the following fields:
LegCount: The leg identity, i.e. 1 for the first connection, 2, for the second, etc
Uuid: The unique identifier of the other leg of the call
Number: The phone number (an E164 number) or extension associated with the other leg
GroupId: The group Id value, if the owner of the leg belonged to a group
Group: The Group Name value, if the owner of the leg belonged to a group
GroupExtension: The Group Extension value, if the owner of the leg belonged to a group
FirstName: The first name of the user the leg was connected to, if available
LastName: The last name of the user the leg was connected to, if available
LastName: The last name of the user the leg was connected to, if available
EmailAddress: The email address of the user the leg was connected to, if available
UserId: The User Id of the user the leg was connected to, if available
DevId: The Device Id of the user the leg was connected to, if available
CallCategory: The Category of the channel. See Call Category definitions below
TransferStartEpoch:The epoch value detailing when this call was connected to the other channel
TransferStopEpoch: The epoch value detailing when this call was dis-connected from the other channel, typically because call hung up or a new transfer occurred
ChannelStartEpoch: The epoch time that the other channel was initiated
TalkTime: Amount of time in seconds spent connected to this transfer record
Recording: A URL link to a recording (if a recording was made on that leg of the call). If no recording was made, the field returns "No Recording was made"
Given this is a complex macro, these fields can be accessed using the standard complex macro notation. An an example, to access the Uuid of the 2nd record, use $(System_Transfer.Uuid[2])
T
$(TotalCallTalkSeconds)
Simple
NO
Call Statistics
YES
The number of seconds that the call spent in talk mode, i.e. the period a call was connected between two 'real' users.
U
$(UserId)
Simple
NO
Call Properties
YES
The unique User ID for the user that owns this channel.
$(UUID)
Simple
YES
Call Properties
YES
Unique reference to the channel on the platform. The UUID can be used to find the full CDR information on the platform for future diagnostics.
V
$(VoiceMailUserId)
Simple
NO
Call Properties
YES
If the channel is connected to a voice mail service to record a voicemail, then this macro will expand to the User Id that owns that particular voice mail box.
W
$(Wbooks_[resultset].[field])
Complex
YES
Data Source
YES
A WorkBooks result set is a complex macro that is created in a Wbooks Store or Wbooks Query sub-item. The [resultset] must be replaced with the result set name that was specified and [field] with the field name to be expanded.
Z
$(Zen_[resultset].[field])
Complex
YES
Data Source
YES
A ZenDesk result set is a complex macro that is created in a Sugar Store or Sugar Query sub-item. The [resultset] must be replaced with the result set name that was specified and [field] with the field name to be expanded.
SMS Channel Macros
The following macros can be used to obtain data from an SMS message that has been passed into a Non Call Policy
Macro
Notes
$(CallerNumber)
Originating number of the SMS message in local format
$(E164CallerNumber)
Originating number of the SMS message in E164 format
$(CalledNumber)
Original called number of the SMS message in local format
$(E164CalledNumber)
Original called number of the SMS message in E164 format
$(ConnectedNumber)
The number that the SMS message was actually delivered to after being processed by the Non Call Policy
$(E164ConnectedNumber)
The E164 number that the SMS message was actually delivered to after being processed by the Non Call Policy
$(OwnerEmail)
The email address for the owner of the SMS, i.e. the user who owns the MSISDN number in the configuration portal
$(OwnerLastName)
The last name of the owner of the SMS, i.e. the user who owns the MSISDN number in the configuration portal
$(OwnerFirstName)
The first name of the owner of the SMS, i.e. the user who owns the MSISDN number in the configuration portal
$(SMSBody)
The body of the SMS text message
$(Direction)
The direction of the message; one of received or sent. Note that $(Direction) deprecates $(SMSDirection)
$(SentEpoch)
The Epoch time in seconds when the message was sent. Note that $(SentEpoch) deprecates $(SMSSentEpoch)
$(SentDateUTC)
The date in UTC format when the message was sent. Note that $(SentDateUTC) deprecates $(SMSSentDateUTC)
MMS Channel Macros
The following macros can be used to obtain data from an MMS message that has been passed into a Non Call Policy
Macro
Notes
$(CallerNumber)
Originating number of the MMS message in local format
$(E164CallerNumber)
Originating number of the MMS message in E164 format
$(CalledNumber)
Original called number of the MMS message in local format
$(E164CalledNumber)
Original called number of the MMS message in E164 format
$(ConnectedNumber)
The number that the MMS message was actually delivered to after being processed by the Non Call Policy
$(E164ConnectedNumber)
The E164 number that the MMS message was actually delivered to after being processed by the Non Call Policy
$(OwnerEmail)
The email address for the owner of the MMS, i.e. the user who owns the MSISDN number in the configuration portal
$(OwnerLastName)
The last name of the owner of the MMS, i.e. the user who owns the MSISDN number in the configuration portal
$(OwnerFirstName)
The first name of the owner of the MMS, i.e. the user who owns the MSISDN number in the configuration portal
$(Direction)
The direction of the message; one of received or sent
$(SentEpoch)
The Epoch time in seconds when the message was sent
$(SentDateUTC)
The date in UTC format when the message was sent
USSD Channel Macros
The following macros can be used to obtain data from a USSD message that has been passed into a Non Call Policy
Macro
Notes
$(USSDFrom)
Originating number of the USSD message in local format
$(USSDDirection)
'sent' for MO, or 'received' for MT. Note only MO is supported right now
$(USSDBody)
Content of the USSD message (ie what the user typed into their phone keypad)
$(USSDOwnerFirst)
The first name of the owner of the USSD message, i.e. the user who owns the MSISDN number in the configuration portal
$(USSDOwnerLast)
The last name of the owner of the USSD message, i.e. the user who owns the MSISDN number in the configuration portal
$(USSDSentEpoch)
The Epoch time in seconds when the message was sent
$(USSDSentDate)
The date in local format when the message was sent
$(USSDSentDateUTC)
The date in UTC format when the message was sent
$(USSDOwnerEmail)
The email address of the owner of the USSD message, i.e. the user who owns the MSISDN number in the configuration portal
Call Categories
Call Type Code
Summary
Description
SIP Device Related Record Codes (legs attached to SIP devices)
SOC
SIP Device Originated Channel
Channel originated physically inbound to switch from a registered SIP subscriber device.
SOCR
SIP Device Originated Channel Reversed
Channel originated physically outbound to a registered SIP subscriber device, but originated logically as an inbound call. Typically used in CTI scenarios.
STC
SIP Device Terminated Channel
Channel originated as an outbound channel to a registered SIP device.
Mobile Related Record Codes (legs attached to mobile devices or carriers)
MOC
Mobile Device Originated Channel
Channel originated from a mobile subscriber device and has a corresponding outbound carrier connection that has been established.
MOCs
Mobile Device Originated Channel (Switch terminated)
Channel originated from a mobile subscriber device and has been answered on the switch, however no outbound carrier connection has been established. For example, a user dials a service extension such as an Echo line or call has been pre-answered to play an announcement.
MOCLD
Mobile Device Late Divert
Channel has been originated indirectly from a mobile device as the result of a late divert. A Late Divert occurs when the mobile is actively rung, but diverts after a period of no-answer or if busy.
MORC
Mobile Device Originated Roaming Channel
Channel originated from a mobile subscriber device which is roaming, and calls have passed via switch.
MORCx
Mobile Device Originated Roaming Channel (non Camel)
Channel originated from a mobile subscriber device which is roaming. Channel is attached to a non-camel network and has not traversed the switch.
MOCVM
Mobile Device Originated Channel to VoiceMail
Channel originated by a mobile subscriber device to listen to voicemail.
MOCR
Mobile Device Originated Channel Reversed
Channel originated as a mobile subscriber device, but originated logically as an inbound call. Typically used in CTI scenarios.
MVOC
Mobile Device Trombone Originated Channel
Channel originated as the inbound trombone leg to a mobile subscriber. The originator may or may not be a mobile subscriber. To all intents and purposes this is the same as COC.
MTC
Mobile Device Terminated Channel from Switch
Channel terminated to a registered Mobile Device but originated from a device on the switch as opposed to a direct dial to the mobile from an external source.
MTTC
Mobile Device Terminated Channel
Channel terminated to a registered Mobile Device, i.e. Mobile Device has been dialed from an external number.
MTRC
Mobile Device Terminated Roaming Channel
Channel terminated to a registered Mobile Device, which is currently roaming.
CTCm
Carrier Terminated (mobile)
Channel terminated as an outbound channel to a PSTN Carrier. Channel was originated from a Non-Roaming Mobile device.
CTCmr
Carrier Terminated (mobile/roaming)
Channel terminated as an outbound channel to a PSTN Carrier. Channel was originated from a Roaming Mobile device.
STCm
SIP Device Terminated (mobile)
Channel terminated to a SIP device. Channel was originated from a mobile device.
STCmr
SIP Device Terminated (mobile/roaming)
Channel terminated to a SIP device. Channel was originated from a Roaming mobile device.
General Carrier Related Record Codes (legs attached to general PSTN)
COC
Carrier Originated Channel
Channel originated inbound from an external carrier; typically PSTN.
COCR
Carrier Originated Channel Reversed
Channel originated physically outbound to an external carrier, but originated logically as an inbound call. Typically used in CTI scenarios.
CTC
Carrier Terminated Channel
Channel terminated as an outbound channel to a Carrier; typically PSTN.
CTCmx
Carrier Terminated (mobile/non camel)
Channel terminated as an outbound channel to a Carrier; typically PSTN. Channel was originated from a mobile device which is on a non-CAMEL network.
CTCNET
Carrier Terminated OnNet (mobile/non camel)
Channel terminated as an outbound channel but remains OnNet in the Network.
CTCNETm
Carrier Terminated (mobile)
Channel terminated as an outbound channel but remains OnNet in the Network. Channel was originated from a Mobile device.
CTCNETmr
Carrier Terminated (mobile)
Channel terminated as an outbound channel but remains OnNet in the Network. Channel was originated from a Mobile Roaming device.
SIP Trunk Related Record Codes (legs attached to SIP Trunks)
TOC
SIP Trunk Originated Channel
Channel was originated inbound from a SIP Trunk.
TOCR
SIP Trunk Originated Channel Reversed
Channel originated physically outbound to a SIP Trunk, but originated logically as an inbound call. Typically used in CTI scenarios.
TTC
SIP Trunk Terminated Channel
Channel originated as an outbound channel to a SIP Trunk.
Complex Macro Reference
When using a Data Connector such as Salesforce or HTTP, query results are placed into a named Result Set. A result set is like a named bucket which holds these blobs of data for use later on in the call. As many result sets can be created as are needed, so long as they are given different names. To access the data in a result set, the Complex Macro language is used.
The result set will typically contain one or more fields and one or more records, depending on the type of query that was run. To make it easier to understand how a result set is represented, the fields can be thought of as columns in a table and the records as rows in the table.
For example, if Salesforce was queried for a list of contacts that matched some criteria, Company Name, First Name, Last Name and Mobile might be chosen for return, and a result set called SForce_Current created. This data might look as follows:
Row Number
CompanyName
FirstName
LastName
Mobile
1
Acme
Bill
Smith
07777123456
2
Acme
Joe
Green
08888123456
3
ABC Supplies
Jeremy
Brown
06666123456
4
ABC Supplies
Katie
Jones
05555123456
In the example above, there are 4 rows (records) and 3 columns (fields). Once these have been stored in a result set, the complex macro language can be used to access any of the items in this data grid. This data will remain in the results set until the call is hung up, or another query is run which overwrites the data. To keep multiple result sets, name the results set with a different name.
For the remainder of this documentation, the SForce_Current result set will be used as an example. When referencing it as a macro, the notation $(SForce_Current) is used.
Getting A Specific Field Value In A Specific Record With A Row Identifier
If the result set contains multiple records (rows), to get a specific field from a specific row, use the notation $(SForce_Current.FirstName[1]). In this example, the [1], tells the macro to get the FirstName value from row 1, which in the example above would return Bill. So, to get row 4, use $(SForce_Current.FirstName[4]) to get the value Katie. If specifying a row value for a row that is not present, then the result will be empty.
Getting The Field Value For All Rows
The field values can be concatenated for all rows together by using the notation $(SForce_Current.FirstName). Note that unlike the previous scenario, the Row Identifier is now missing. In this example, the result will be "Bill,Joe,Jeremy,Katie". For some field types (particularly numbers), this concatenation mechanism allows for the use of comma separated results in certain dial-plan policy sub-items.
If the same query was performed on the Mobile field, e.g. $(SForce_Current.Mobile), then this macro would expand to "07777123456,08888123456,06666123456,05555123456". This form can be used in the Connect Number sub-item to dial multiple numbers; simply add the macro the Number to dial property.
Getting A Random Field Value In A Specific Record
To select a named field from any of the records at random, use the RANDOM quantifier by using the following notation $(SForce_Current.MobilePhone[RANDOM]). In this example, the result could be either 07777123456 or 08888123456 or 06666123456 or 05555123456.
Counting The Number Of Results
There is also a special field called @Count. For example $(SForce_Current.@Count). This will give the count of all records in the Results Set. This could be useful in Rules, where a different action might need performing if there was more than one matching result.
Handling Multiple Fields With The Same Names
In certain situations, it is possible to query two tables in the same query which return fields with the same name. For example, with Salesforce referenced fields can be requested by typing in the field list. If querying a Contact table, to find the First Name of the contact and also the First Name of the owner of that Contact, the following notation can be used in the field list FirstName, Owner.FirstName
The problem now is that there are two first name fields, so there needs to be a means to differentiate between them. The answer is simple. The first field is referenced as normal, e.g. $(SForce_Current.FirstName) or $(SForce_Current.FirstName[1])
To access the second field, use $(SForce_Current.FirstName _1) or $(SForce_Current.FirstName _1[1])
For the third field, add an _2, and so on.
Was this article helpful?
Thank you for your feedback! Our team will get back to you
