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-Call Policies. 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.