Intelligent Handshake®

Session Disposition

Overview

The Session Disposition endpoint records the final outcome of a user session or interaction with your application, experience, or service.

A disposition closes the feedback loop for an interaction that began with events such as an Intelligent Call or Intelligent Page session.

By posting a session disposition, your application informs the Intelligent Handshake platform how the session ultimately resolved so performance, attribution, and optimization systems can learn from the result.

Getting Started

  1. Choose a transfer method
    • API (Recommended for real-time feedback)
    • Email (Simple, low-volume use cases)
  2. Select the Session Disposition fields relevant to your application
    • Session outcome (e.g., Convert, Abandon, Customer Service)
    • Session metadata (duration, timestamps, identifiers)
    • Optional context (campaign, agent, channel, etc.)
  3. Define transfer frequency
    • Real-time (recommended for continuous optimization)
    • Near real-time (every few minutes)
    • Batch (hourly, daily, or scheduled uploads)

For API (Real-Time Feedback)

  1. Request your Private API Key if one has not yet been assigned.
  2. Post Session Disposition to the Action API Endpoint at the end of each interaction.

For Email

  1. Register the sending email address with Intelligent Handshake®.
  2. Send a sample file for validation.
  3. Activate automated transfer.

When to Post a Session Disposition

A Session Disposition should be posted when a session has reached a meaningful outcome, such as:

  • A purchase was completed
  • A reservation was booked
  • A call was completed
  • A session ended without conversion
  • A session was abandoned
  • A support interaction was resolved
  • A user task ended

Think of this action as the final state of the session.

How it Fits in the Interaction Model

Applications typically follow this pattern:

  1. Session Begins
    • Intelligent Call
    • Intelligent Page
  2. User Interaction Occurs
    • Browsing
    • Conversation
    • Transaction attempt
  3. Session Disposition Posted
    • Outcome of the session recorded

Session Start → User Interaction → Session Disposition

This structure enables:

  • campaign attribution
  • AI model feedback
  • performance analytics
  • journey optimization

Key Fields

Action Type (Encoded in ActionKey)

Defines the category of interaction.

  • PhoneCall
  • WebVisit
  • Disposition
  • MobileMessage
  • AppVisit
  • KioskVisit
  • POS
  • eCommerce

Session ID

Application-assigned identifier representing the user session.

This should remain consistent across all events within the same interaction.

Session Start Timestamp

Timestamp indicating when the session began.

Example:

20240614T045120Z

Session Duration

Length of the session in milliseconds.

Example:

65000 (65 seconds)

Session Disposition Code

Represents the final outcome of the session.

Example values may include:

  • Session Failure (1)
  • Bounce (2)
  • Visit Abandon (3)
  • Search Abandon (4)
  • Category Abandon (5)
  • Product Abandon (6)
  • Cart Abandon (7)
  • Checkout Abandon (8)
  • Subscribe (9)
  • Convert (10)
  • Customer Service (11)
  • Dead Air (12)
  • Wrong Number (13)
  • Spam (14)

Session Variant

Optional identifier used when running experience experiments or variants.

Example:

  • LandingPage-A
  • CheckoutFlow-B
  • AgentScript-3

All Session Disposition Fields

The Session Disposition payload records the final outcome of a session. The sections below organize the full field dictionary into logical groups so developers can quickly find the fields relevant to authentication, session context, attribution, user identity, commerce, and response handling.

Session Fields Tracking & Attribution User Identity Commerce Signals API Response Application Context Integration Echo

Session Fields

These fields describe the session being closed. Use them to identify the session, define its timing, capture its final disposition, and preserve technical context such as referrer, landing URL, IP address, and user agent.

Field Type Parameter Signal Value Type Description Example
Session Start Timestamp
session_start_timestamp
Required		 DateTime - 400 Timestamp indicating when the session began. 20240614T045120Z
Session Duration
session_duration
Required		 Unsigned Integer - 401 Length of the session in milliseconds. 11000
Session Disposition Code
session_disposition_code
Required		 Unsigned Integer - 402 Final outcome code for the session. 1
Session ID
session_id		 String - 403 Application-defined identifier for the session. ABC123
Session Variant
session_variant
Required		 String - 404 Variant, experience branch, or experiment arm associated with the session. default
Session Recording URL
session_recording_url		 String - 405 Optional link to a recording or playback asset for the session. https://example.com/recordings/123
Session Remote IP
session_remote_ip		 String - 415 Originating remote IP address observed for the session. 8.8.8.8
Session User Agent
session_user_agent		 String UA 417 User agent string associated with the session request. Mozilla/5.0
Session Referrer
session_referrer		 String FRR 418 Referring URL that led into the session. https://google.com
Session Landing URL
session_landing_url		 String URL 419 Initial landing page URL for the session. https://example.com/landing
Session Landing Page Title
session_landing_page_title		 String - 420 Document title of the landing page associated with the session. Landing Page

Tracking & Attribution

These fields connect the session outcome back to acquisition and campaign activity. Use them when you want to attribute a session disposition to a campaign, source, medium, creative, or marketing tactic.

Field Type Parameter Signal Value Type Description Example
Session Tracking Campaign ID
session_tracking_campaign_id		 String TCI 406 Identifier for the campaign associated with the session. SPRING24
Session Tracking Campaign Name
session_tracking_campaign_name		 String TCN 407 Friendly campaign name. Spring 2024 Retargeting
Session Tracking Source
session_tracking_source		 String TSC 408 Traffic source for the session. google
Session Tracking Medium
session_tracking_medium		 String TMD 409 Marketing medium or channel. cpc
Session Tracking Content
session_tracking_content		 String TCN 410 Creative variation, message, or content tag. hero-a
Session Tracking Term
session_tracking_term		 String TTM 411 Search term or keyword associated with the session. identity+resolution
Session Tracking Source Platform
session_tracking_source_platform		 String TSP 412 Upstream platform that originated the campaign traffic. Google Ads
Session Tracking Creative Format
session_tracking_creative_format		 String TCF 413 Creative format used by the marketing asset. image
Session Tracking Marketing Tactic
session_tracking_marketing_tactic		 String TMT 414 Marketing tactic associated with the session. retargeting

User Identity

These fields capture person and company context associated with the session. Use them to enrich attribution, support identity resolution, or pass known profile details gathered during the session.

Field Type Parameter Signal Value Type Description Example
User Full Name
user_full_name		 String - 46 User full name if unparsed or use the following parsed fields. Dr. Penny Ada Cache, PhD
User Name Prefix
user_name_prefix		 String - 115 User name Prefix. Dr
User First Name
user_first_name		 String - 116 User first name. Penny
User Middle Name
user_middle_name		 String - 117 User middle name. Ada
User Last Name
user_last_name		 String - 118 User last name. Cache
User Name Suffix
user_name_suffix		 String - 119 User name suffix. PhD
User Address Line1
user_address_line1		 String - 103 Primary street address line. 314 Byte Lane Apt 42
User Address Line2
user_address_line2		 String - 104 Secondary address line.
User Address Line3
user_address_line3		 String - 105 Additional address information.
User City
user_city		 String CI 106 User city. San Diego
User State
user_state		 String ST 107 User state or region. CA
User Postal Code
user_postal_code		 String - 108 User postal code. 92101
User Postal Subcode
user_postal_subcode		 String - 109 Postal extension or subcode. 1234
User Carrier Route
user_carrier_route		 String - 112 Carrier route code. C001
User DPC
user_dpc		 String - 113 Delivery point code. 123
User Country
user_country		 String CO 111 User country code or country name. US
User Phone
user_phone
Required		 String - 43 User phone number provided with the action. 16195550108
User Email
user_email		 String - 47 User email address. penny.cache@vectorlane.dev
Company Name
company_name		 String - 114 Company associated with the user or session. Nora Schema Agency

Commerce

These fields describe the commercial outcome of the session. Use them when the session ends in a transaction, order, upsell, or cart event and you want to report order value, item detail, and conversion economics.

Field Type Parameter Signal Value Type Description Example
Commerce Order Quantity
commerce_order_quantity		 Decimal - 200 Total order quantity. 1.00
Commerce Order Discount
commerce_order_discount		 Decimal - 201 Total discount amount applied to the order. 5.00
Commerce Order Shipping
commerce_order_shipping		 Decimal - 202 Total shipping amount. 7.95
Commerce Order Tax
commerce_order_tax		 Decimal - 203 Total tax amount. 3.21
Commerce Order Fees
commerce_order_fees		 Decimal - 204 Additional fees associated with the order. 1.50
Commerce Order Total
commerce_order_total
Required		 Decimal - 205 Total order value reported for the session outcome. 24.66
Commerce Items SKU
commerce_items_sku		 String - 206 Pipe-delimited list of item SKUs included in the order. SKU-001|SKU-002
Commerce Items Name
commerce_items_name		 String - 207 Pipe-delimited list of item names. Starter Kit|Refill
Commerce Items Quantity
commerce_items_quantity		 String - 208 Pipe-delimited list of item quantities. 1|2
Commerce Items Unit Price
commerce_items_unit_price		 String - 209 Pipe-delimited list of item unit prices. 9.99|4.99
Commerce Items Discount
commerce_items_discount		 String - 210 Pipe-delimited list of item discount amounts. 0.00|1.00
Commerce Items Taxes
commerce_items_taxes		 String - 211 Pipe-delimited list of item tax amounts. 0.80|0.40
Commerce Items Total
commerce_items_total		 String - 212 Pipe-delimited list of item totals. 10.79|8.38
Commerce Upsell Depth
commerce_upsell_depth		 Unsigned Integer - 213 Number of upsell steps encountered in the session. 2
Commerce Upsell SKUs
commerce_upsell_skus		 String - 214 Pipe-delimited list of upsell SKUs shown or accepted. UPSELL-1|UPSELL-2

Signals

These fields define the primary user identity signal and destination identity signal associated with the session disposition. The user identity signal identifies the individual and provides the context required for personalization. The destination identity signal identifies the target experience, audience, or endpoint to which the session is directed.

Field Type Parameter Signal Value Type Description Example
User Signal Type
user_signal_type
Required		 Unsigned Integer - 121 Enumerated signal type that defines the identity namespace of the user signal value (for example, Email Address, Phone Number, Person ID, Cookie ID, or Device ID). 43
User Signal Value
user_signal_value
CSV Only		 String - - The identifier value associated with the user signal type. This value is used to recognize, resolve, or personalize the experience for the individual. CSV only. API integrations should populate the signal value field corresponding to the specified Destination Signal Type. 16195551212
Destination Signal Type
destination_signal_type
Required		 Unsigned Integer - 122 Enumerated signal type that defines the identity namespace of the destination signal value (for example, DNIS, Domain, URL, Application ID, or Destination ID). 44
Destination Signal Value
destination_signal_value
CSV Only		 String - - The identifier value associated with the destination signal type. This value is used to identify the experience, endpoint, audience, or resource targeted by the session. CSV only. API integrations should populate the signal value field corresponding to the specified Destination Signal Type. 1800444444

API Response

These fields capture the API contract and outcome of the posted request. Use them for request tracing, response auditing, and downstream observability across integrations.

Field Type Parameter Signal Value Type Description Example
API Model
api_model
Required		 String - 93 Versioned model name for the API contract. DIR_USER_V1
API Segment
api_segment
Required		 String - 49 Logical segment of the API associated with the request. session_disposition
API TrackingID
api_trackingid		 String - 300 Tracking identifier used to trace the request across systems. trk_123456
API Result Code
api_result_code
Required		 String - 301 Result code returned by the API layer. 200
API Result Message
api_result_message
Required		 String - 302 Human-readable message returned by the API layer. Accepted

Integration Context

These fields preserve context from the originating integration. Use them to map the session disposition back to application users, agents, local status codes, and application-level notes.

Field Type Parameter Signal Value Type Description Example
Network Link ID
network_link_id		 String - 59 Identifier linking the session to a network relationship or source. NL-1001
Integration Platform ID
integration_platform_id		 String - 303 Identifier for the originating application platform. shopify
Integration User ID
integration_user_id		 String - 304 Application user identifier associated with the session. user_1001
Integration Action Type
integration_action_type		 String - 305 Identifier for an upstream or related network action. NA-1001
Integration Agent ID
integration_agent_id		 String - 306 Identifies the specific agent or automated system that handled the interaction:
  • Live agent ID (e.g., agent_1001)
  • IVR call script version or edition (e.g., IVR_v3.2_retention)
  • AI agent version or edition (e.g., ai-agent-v2.1-upsell)
Enables granular performance attribution across human agents, IVR flows, and AI models. 		agent_1001
Integration Result Code
integration_result_code
Required		 String - 307 Application-level result code associated with the session outcome. OK
Integration Result Message
integration_result_message
Required		 String - 308 Application-level result description. Checkout completed
Integration Notes
integration_notes		 String - 309 Optional notes or implementation-specific commentary from the application. Customer upgraded to bundle

Integration Echo

These fields provide traceability to related upstream and downstream activities across external systems. They may be used to associate a session with network actions, postbacks, mirrored events, replay operations, or other multi-hop processing workflows.

These fields are informational only and are not used by platform logic, routing, processing, billing, or reporting. Their purpose is to preserve external references and correlation identifiers for auditing, troubleshooting, and integration scenarios.

Field Type Parameter Signal Value Type Description Example
Echo ID
echo_id		 Unsigned Integer - 310 Identifier for the echoed or replayed event record. 9001
Echo Link
echo_link		 Unsigned Integer - 311 Linked identifier connecting the action to its echo chain. 10001
Echo Segment
echo_segment		 String - 312 Logical echo segment name. conversion
Echo Context
echo_context		 String - 313 Context or channel through which the echo occurred. postback
Echo Count
echo_count		 Unsigned Integer - 314 Number of echo events observed for the action. 1
Echo Quantity
echo_quantity		 Double - 315 Echo quantity associated with the action. 1.0000
Echo Amount
echo_amount		 String - 316 Amount or value associated with the echoed event. 24.66
Echo JSON
echo_json		 JSON - 317 Raw JSON payload associated with the echoed event. {"event":"checkout_complete"}

Why Session Dispositions Matter

Posting session outcomes enables:

  • conversion attribution
  • experience optimization
  • AI training signals
  • campaign performance measurement
  • user journey analytics

Without session dispositions, the platform can observe activity but cannot learn the outcome of the interaction.

See Also