Intelligent Handshake®

Session Disposition

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. Request your Private API Key.
  2. Integrate Intelligent Handshake® Action API Endpoint into the outcome of the user session.

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 follows 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 Required Parameter Signal Value Description Example
Session Start Timestamp
session_start_timestamp		 DateTime Yes - 400 (SessionStartTimestamp) Timestamp indicating when the session began. 20240614T045120Z
Session Duration
session_duration		 Unsigned Integer Yes - 401 (SessionDuration) Length of the session in milliseconds. 11000
Session Disposition Code
session_disposition_code		 Unsigned Integer Yes - 402 (SessionDispositionCode) Final outcome code for the session. 1
Session ID
session_id		 String No - 403 (SessionID) Application-defined identifier for the session. ABC123
Session Variant
session_variant		 String Yes - 404 (SessionVariant) Variant, experience branch, or experiment arm associated with the session. default
Session Recording URL
session_recording_url		 String No - 405 (SessionRecordingURL) Optional link to a recording or playback asset for the session. https://example.com/recordings/123
Session Remote IP
session_remote_ip		 String No - 415 (SessionRemoteIP) Originating remote IP address observed for the session. 127.0.0.1
Session User Agent
session_user_agent		 String No UA 417 (SessionUserAgent) User agent string associated with the session request. Mozilla/5.0
Session Referrer
session_referrer		 String No FRR 418 (SessionReferrer) Referring URL that led into the session. https://google.com
Session Landing URL
session_landing_url		 String No URL 419 (SessionLandingURL) Initial landing page URL for the session. https://example.com/landing
Session Landing Page Title
session_landing_page_title		 String No - 420 (SessionLandingPageTitle) 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 Required Parameter Signal Value Description Example
Session Tracking Campaign ID
session_tracking_campaign_id		 String No TCI 406 (SessionTrackingCampaignID) Identifier for the campaign associated with the session. SPRING24
Session Tracking Campaign Name
session_tracking_campaign_name		 String No TCN 407 (SessionTrackingCampaigName) Friendly campaign name. Spring 2024 Retargeting
Session Tracking Source
session_tracking_source		 String No TSC 408 (SessionTrackingSource) Traffic source for the session. google
Session Tracking Medium
session_tracking_medium		 String No TMD 409 (SessionTrackingMedium) Marketing medium or channel. cpc
Session Tracking Content
session_tracking_content		 String No TCN 410 (SessionTrackingContent) Creative variation, message, or content tag. hero-a
Session Tracking Term
session_tracking_term		 String No TTM 411 (SessionTrackingTerm) Search term or keyword associated with the session. identity+resolution
Session Tracking Source Platform
session_tracking_source_platform		 String No TSP 412 (SessionTrackingSourcePlatform) Upstream platform that originated the campaign traffic. Google Ads
Session Tracking Creative Format
session_tracking_creative_format		 String No TCF 413 (SessionTrackingCreativeFormat) Creative format used by the marketing asset. image
Session Tracking Marketing Tactic
session_tracking_marketing_tactic		 String No TMT 414 (SessionTrackingMarketingTactic) 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 Required Parameter Signal Value Description Example
User Full Name
user_full_name		 String No - 46 (PersonName) User full name. Dr. Penny Ada Cache, PhD
User Name Prefix
user_name_prefix		 String No - 115 (PersonNamePrefix) User name Prefix. Dr
User First Name
user_first_name		 String No - 116 (PersonFirstName) User first name. Penny
User Middle Name
user_middle_name		 String No - 117 (PersonMiddleName) User middle name. Ada
User Last Name
user_last_name		 String No - 118 (PersonLastName) User last name. Cache
User Name Suffix
user_name_suffix		 String No - 119 (PersonNameSuffix) User name suffix. PhD
User Address Line1
user_address_line1		 String No - 103 (AddressLine1) Primary street address line. 314 Byte Lane Apt 42
User Address Line2
user_address_line2		 String No - 104 (AddressLine2) Secondary address line.
User Address Line3
user_address_line3		 String No - 105 (AddressLine3) Additional address information.
User City
user_city		 String No CI 106 (City) User city. San Diego
User State
user_state		 String No ST 107 (State) User state or region. CA
User Postal Code
user_postal_code		 String No - 108 (PostalCode) User postal code. 92101
User Postal Subcode
user_postal_subcode		 String No - 109 (PostalSubCode) Postal extension or subcode. 1234
User Carrier Route
user_carrier_route		 String No - 112 (CarrierRoute) Carrier route code. C001
User DPC
user_dpc		 String No - 113 (DPC) Delivery point code. 123
User Country
user_country		 String No CO 111 (Country) User country code or country name. US
User Phone
user_phone		 String Yes - 43 (ANI) User phone number provided with the action. 16195550108
User Email
user_email		 String No - 47 (PersonEmail) User email address. penny.cache@vectorlane.dev
Company Name
company_name		 String No - 114 (CompanyName) 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 Required Parameter Signal Value Description Example
Commerce Order Quantity
commerce_order_quantity		 Decimal No - 200 (CommerceOrderQuantity) Total order quantity. 1.00
Commerce Order Discount
commerce_order_discount		 Decimal No - 201 (CommerceOrderDiscount) Total discount amount applied to the order. 5.00
Commerce Order Shipping
commerce_order_shipping		 Decimal No - 202 (CommerceOrderShipping) Total shipping amount. 7.95
Commerce Order Tax
commerce_order_tax		 Decimal No - 203 (CommerceOrderTax) Total tax amount. 3.21
Commerce Order Fees
commerce_order_fees		 Decimal No - 204 (CommerceOrderFees) Additional fees associated with the order. 1.50
Commerce Order Total
commerce_order_total		 Decimal Yes - 205 (CommerceOrderTotal) Total order value reported for the session outcome. 24.66
Commerce Items SKU
commerce_items_sku		 String No - 206 (CommerceItemsSKU) Pipe-delimited list of item SKUs included in the order. SKU-001|SKU-002
Commerce Items Name
commerce_items_name		 String No - 207 (CommerceItemsName) Pipe-delimited list of item names. Starter Kit|Refill
Commerce Items Quantity
commerce_items_quantity		 String No - 208 (CommerceItemsQuantity) Pipe-delimited list of item quantities. 1|2
Commerce Items Unit Price
commerce_items_unit_price		 String No - 209 (CommerceItemsUnitPrice) Pipe-delimited list of item unit prices. 9.99|4.99
Commerce Items Discount
commerce_items_discount		 String No - 210 (CommerceItemsDiscount) Pipe-delimited list of item discount amounts. 0.00|1.00
Commerce Items Taxes
commerce_items_taxes		 String No - 211 (CommerceItemsTaxes) Pipe-delimited list of item tax amounts. 0.80|0.40
Commerce Items Total
commerce_items_total		 String No - 212 (CommerceItemsTotal) Pipe-delimited list of item totals. 10.79|8.38
Commerce Upsell Depth
commerce_upsell_depth		 Unsigned Integer No - 213 (CommerceUpsellDepth) Number of upsell steps encountered in the session. 2
Commerce Upsell SKUs
commerce_upsell_skus		 String No - 214 (CommerceUpsellSKUs) Pipe-delimited list of upsell SKUs shown or accepted. UPSELL-1|UPSELL-2

Signals

These fields define the principal user signal and program signal associated with the session disposition. Use them to communicate the strongest identity signal and the application-level event or program state that produced the posted action.

Field Type Required Parameter Signal Value Description Example
User Signal Type
user_signal_type		 Unsigned Integer Yes - - Enumerated type describing the primary user signal. 1
User Signal Value
user_signal_value		 String Yes - - Value of the primary user signal. 16195551212
Program Signal Type
program_signal_type		 Unsigned Integer Yes - - Enumerated type describing the program-side signal. 2001
Program Signal Value
program_signal_value		 String Yes - - Value of the program-side signal. checkout_complete

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 Required Parameter Signal Value Description Example
API Model
api_model		 String Yes - 93 (Model) Versioned model name for the API contract. bituser.v1
API Segment
api_segment		 String Yes - 49 (SegmentCode) Logical segment of the API associated with the request. session_disposition
API TrackingID
api_trackingid		 String Yes - 300 (APITrackingID) Tracking identifier used to trace the request across systems. trk_123456
API Result Code
api_result_code		 String Yes - 301 (APIResultCode) Result code returned by the API layer. 200
API Result Message
api_result_message		 String Yes - 302 (APIResultMessage) 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 Required Parameter Signal Value Description Example
Network Link ID
network_link_id		 String No - 59 (NetworkID) Identifier linking the session to a network relationship or source. NL-1001
Integration Platform ID
integration_platform_id		 String No - 303 (IntegrationID) Identifier for the originating application platform. shopify
Integration User ID
integration_user_id		 String No - 304 (IntegrationUserID) Application user identifier associated with the session. user_1001
Integration Action Type
integration_action_type		 String No - 305 (IntegrationActionType) Identifier for an upstream or related network action. NA-1001
Integration Agent ID
integration_agent_id		 String No - 306 (IntegrationAgentID) Application agent or operator identifier. agent_1001
Integration Result Code
integration_result_code		 String Yes - 307 (IntegrationResultCode) Application-level result code associated with the session outcome. OK
Integration Result Message
integration_result_message		 String Yes - 308 (IntegrationResultMessage) Application-level result description. Checkout completed
Integration Notes
integration_notes		 String No - 309 (IntegrationNotes) Optional notes or implementation-specific commentary from the application. Customer upgraded to bundle

Integration Echo

These fields support linkage to upstream network activity and downstream replay or echo behavior. Use them when the session is connected to a network action, postback, mirrored event, or multi-hop processing flow.

Field Type Required Parameter Signal Value Description Example
Echo ID
echo_id		 Unsigned Integer No - 310 (EchoID) Identifier for the echoed or replayed event record. 9001
Echo Link
echo_link		 Unsigned Integer No - 311 (EchoLink) Linked identifier connecting the action to its echo chain. 10001
Echo Segment
echo_segment		 String No - 312 (EchoSegment) Logical echo segment name. conversion
Echo Context
echo_context		 String No - 313 (EchoContext) Context or channel through which the echo occurred. postback
Echo Count
echo_count		 Unsigned Integer No - 314 (EchoCount) Number of echo events observed for the action. 1
Echo Quantity
echo_quantity		 Double No - 315 (EchoQuantity) Echo quantity associated with the action. 1.0000
Echo Amount
echo_amount		 String No - 316 (EchoAmount) Amount or value associated with the echoed event. 24.66
Echo JSON
echo_json		 JSON No - 317 (EchoJSON) 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