ASAPP provides real-time access to events, enabling customers to power internal use cases.

Typical use cases that benefit from real-time ASAPP events include:

  • Tracking the end-user journey through ASAPP
  • Supporting workforce management needs
  • Integrating with customer-maintained CRM systems

ASAPP’s real-time events provide raw data. Complex processing, such as aggregation or deduplication, is handled by batch analytics and reporting.

ASAPP presently supports three real-time event feeds:

  1. Activity: Agent status change events, for tracking schedule adherence
  2. Journey: Events denoting milestones in a conversation, for tracking the customer journey
  3. Queue State: Updates on queues for tracking size and estimated wait times

In order to utilize these available real-time events, a customer will need to configure an API endpoint service under the customer’s control. The balance of this document provides information about the high-level tasks a customer will need to accomplish in order to receive real-time events from ASAPP, as well as further information on the events available from ASAPP.

​
Architecture Discussion

Upon a customer’s request, ASAPP can provide several types of real-time event data.

Note that ASAPP can separately enhance standard real-time events to accommodate specific customer requirements. Such enhancements would usually be specified and implemented as part of ASAPP’s regular product development process.

The diagram above provides a high-level view of how a customer-maintained service that receives real-time ASAPP events might be designed; a service that runs on ASAPP-controlled infrastructure will push real-time event data to one or more HTTP endpoints maintained by the customer. For each individual event, the ASAPP service makes one POST request to the endpoint.

Event data will be transmitted using mTLS-based authentication (See the separate document Securing Endpoints with Mutual TLS for details).

Customer Requirements

  • The customer must implement a POST API endpoint to handle the event messages.
  • The customer and ASAPP must develop the mTLS authentication integration to secure the API endpoint
  • All ASAPP real-time “raw” events will post to the same endpoint; the customer is expected to filter the received events to their needs based on name and event type.
  • Each ASAPP real-time “processed” reporting feed can be configured to post to one arbitrary endpoint, at the customer’s specified preference (i.e., each feed can post to a separate URI, or each can post to the same URI, or any combination required by the customer’s use case.)

It should be noted that real-time events do not implement the de-duplication and grouping of ASAPP’s batch reporting feeds; rather these real-time events provide building blocks for the customer to aggregate and build on. When making use of ASAPP’s real-time events, the customer will be responsible for grouping, de-duplication, and aggregation of related events as required by the customer’s particular use case. The events include metadata fields to facilitate such tasks.

Endpoint Sizing

The endpoint configured by the customer should provisioned with sufficient scale to receive events at the rate generated by the customer’s ASAPP implementation. As a rule of thumb, customers can expect:

  • A voice call will generate on the order of 100 events per issue
  • A text chat will generate on the order of 10 events per issue

So, for example, if the customer’s application services 1000 issues per minute, that customer should expect their endpoint to receive 10,000 — 100,000 messages per minute, or on the order of 1,000 messages per second.

Endpoint Configuration

ASAPP can configure its service with the following parameters:

  • url: The destination URL of the customer API endpoint that is set up to handle POST http requests.
  • timeout_ms: The number of milliseconds to wait for a HTTP 200 “OK” response before timing out.
  • retries: The number of times to retry to send a message after a failed delivery.

If the number of retries is exceeded and the customer’s API is unable to handle any particular message, that message will be dropped. Real-time information lost in this way will typically be available in historical reporting feeds.

​
Real-time Overview

ASAPP’s standard real-time events include data representing human interactions and general issue lifecycle information from the ASAPP feeds named com.asapp.event.activity, com.asapp.event.journey, and com.asapp.event.queue.

In the future, when additional event sources are added, the event source will be reflected in the name of the stream.

​
Payload Schema

Each of ASAPP’s feeds will deliver a single event’s data in a payload comprised of a two-level JSON object. The delivered payload includes:

  1. Routing metadata at the top level common to all events. A small set of fields that should always be present for all events, used for routing, filtering, and deduplication.
  2. Metadata common to all events. These fields should usually be present for all events to provide meta-information on the event. Some fields may be omitted if they do not apply to the specific feed.
  3. Data specific to the event feed. Some fields may be omitted but the same total set can be expected for each event of the same origin
  4. Details specific to the event type. These will vary based on event type

Null fields will be omitted — the customer’s API is expected to interpret missing keys as null.

Versioning

Minor-versions upgrades to the events are expected to be backwards-compatible; major-version updates typically include an interface-breaking change that may require the customer to update their API in order to take advantage of new features.

​
Activity Feed

The agent activity feed provides a series of events for agent login and status changes. ASAPP processes the event data minimally before pushing it into the activity feed to:

  • Convert internal flags to meaningful human-readable strings
  • Filter the feed to include only data fields of potential interest to the customer

ASAPP’s activity feed does not implement complex event processing (e.g., aggregation based on time windows, groups of events, de-duplication, or system state tracking). Any required aggregation or deduplication should be executed by the customer after receiving activity events.

​
Sample Event JSON

{
  "api_version": "v1.3.0",
  "name": "com.asapp.event.activity",
  "meta_data": {
    "create_time": "2022-06-21T20:10:24.411Z",
    "event_time": "2022-06-21T20:10:24.411Z",
    "session_id": "string",
    "issue_id": "string",
    "company_subdivision": "string",
    "company_id": "string",
    "company_segments": [
      "string"
    ],
    "client_id": "string",
    "client_type": "SMS"
  },
  "data": {
    "rep_id": "string",
    "desk_mode": "UNKNOWN",
    "rep_name": "string",
    "agent_given_name": "string",
    "agent_family_name": "string",
    "agent_display_name": "string",
    "external_rep_id": "string",
    "max_slots": 0,
    "queue_ids": [
      "string"
    ],
    "queue_names": [
      "string"
    ]
  },
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event_type": "UNKNOWN",
  "details": {
    "status_updated_ts": "2022-06-21T20:10:24.411Z",
    "status_description": "string",
    "routing_status_updated_ts": "2022-06-21T20:10:24.411Z",
    "routing_status": "UNKNOWN",
    "assignment_load_updated_ts": "2022-06-21T20:10:24.411Z",
    "assigned_customer_ct": 0,
    "previous_routing_status_updated_ts": "2022-06-21T20:10:24.411Z",
    "previous_routing_status": "UNKNOWN",
    "previous_routing_status_duration_sec": 0,
    "previous_routing_status_start_ts": "2022-06-21T20:10:24.411Z",
    "utilization_5_min_updated_ts": "2022-06-21T20:10:24.411Z",
    "utilization_5_min_window_start_ts": "2022-06-21T20:10:24.411Z",
    "utilization_5_min_window_end_ts": "2022-06-21T20:10:24.411Z",
    "utilization_5_min_any_status": {
      "linear_sec": 0,
      "linear_utilized_sec": 0,
      "cumulative_sec": 0,
      "cumulative_utilized_sec": 0
    },
    "utilization_5_min_active": {
      "linear_sec": 0,
      "linear_utilized_sec": 0,
      "cumulative_sec": 0,
      "cumulative_utilized_sec": 0
    },
    "utilization_5_min_away": {
      "linear_sec": 0,
      "linear_utilized_sec": 0,
      "cumulative_sec": 0,
      "cumulative_utilized_sec": 0
    },
    "utilization_5_min_offline": {
      "linear_sec": 0,
      "linear_utilized_sec": 0,
      "cumulative_sec": 0,
      "cumulative_utilized_sec": 0
    },
    "utilization_5_min_wrapping_up": {
      "linear_sec": 0,
      "linear_utilized_sec": 0,
      "cumulative_sec": 0,
      "cumulative_utilized_sec": 0
    }
  }
}

​
Field Explanations

FieldDescription
api_versionMajor and minor version of the API, compatible with the base major version
nameSource of this event stream - use for filtering / routing
event_typeEvent type within the stream - use for filtering / routing
event_idUnique ID of an event, used to identify identical duplicate events
meta_data.create_timeUTC creation time of this message
meta_data.event_timeUTC time the event happened within the system - usually some ms before create time
meta_data.session_idCustomer-side identifier to link events together based on customer session. May be null for system-generated events.
meta_data.client_idMay include client type, device, and version, if present in the event headers
data.rep_idInternal ASAPP identifier of an agent
detailsThese fields vary based on the individual event type - only fields relevant to the event type will be present

​
Journey Feed

The customer journey feed tracks important events in the customer’s interaction with ASAPP. ASAPP processes the event data before pushing it into the journey feed to:

  • Collect conversation and session events into a single feed of the customer journey
  • Add metadata properties to the events to assist with contextualizing the events

This feature is available only for Messaging Platform.

ASAPP’s journey feed does not implement aggregation. Any aggregation or deduplication required by the customer’s use case will need to be executed by the customer after receiving journey events.

​
Sample Event JSON

{
    "api_version": "string",
    "name": "com.asapp.event.journey",
    "meta_data": {
      "create_time": "2024-08-06T13:57:43.053Z",
      "event_time": "2024-08-06T13:57:43.053Z",
      "session_id": "string",
      "issue_id": "string",
      "company_subdivision": "string",
      "company_id": "string",
      "company_segments": [
        "string"
      ],
      "client_id": "string",
      "client_type": "UNKNOWN"
    },
    "data": {
      "customer_id": "string",
      "opportunity_origin": "UNKNOWN",
      "opportunity_id": "string",
      "queue_id": "string",
      "session_id": "string",
      "session_type": "string",
      "user_id": "string",
      "user_type": "string",
      "session_update_ts": "2024-08-06T13:57:43.053Z",
      "agent_id": "string",
      "agent_name": "string",
      "agent_given_name": "string",
      "agent_family_name": "string",
      "agent_display_name": "string",
      "queue_name": "string",
      "external_agent_id": "string"
    },
    "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "event_type": "ISSUE_CREATED",
    "details": {
      "issue_start_ts": "2024-08-06T13:57:43.053Z",
      "intent_code": "string",
      "business_intent_code": "string",
      "flow_node_type": "string",
      "flow_node_name": "string",
      "intent_code_path": "string",
      "business_intent_code_path": "string",
      "flow_name_path": "string",
      "business_flow_name_path": "string",
      "issue_ended_ts": "2024-08-06T13:57:43.053Z",
      "survey_responses": [
        {
          "question": "string",
          "question_category": "string",
          "question_type": "string",
          "answer": "string",
          "ordering": 0
        }
      ],
      "survey_submit_ts": "2024-08-06T13:57:43.053Z",
      "last_flow_action_called_ts": "2024-08-06T13:57:43.053Z",
      "last_flow_action_called_node_name": "string",
      "last_flow_action_called_action_id": "string",
      "last_flow_action_called_version": "string",
      "last_flow_action_called_inputs": {
        "additionalProp1": {
          "value": "string",
          "value_type": "VALUE_TYPE_UNKNOWN"
        },
        "additionalProp2": {
          "value": "string",
          "value_type": "VALUE_TYPE_UNKNOWN"
        },
        "additionalProp3": {
          "value": "string",
          "value_type": "VALUE_TYPE_UNKNOWN"
        }
      },
      "detected_ts": "2024-08-06T13:57:43.053Z",
      "escalated_ts": "2024-08-06T13:57:43.053Z",
      "queued_ts": "2024-08-06T13:57:43.053Z",
      "assigned_ts": "2024-08-06T13:57:43.053Z",
      "abandoned_ts": "2024-08-06T13:57:43.053Z",
      "queued_ms": 0,
      "opportunity_ended_ts": "2024-08-06T13:57:43.053Z",
      "ended_type": "string",
      "assigment_ended_ts": "2024-08-06T13:57:43.053Z",
      "handle_ms": 0,
      "is_ghost_customer": true,
      "last_agent_utterance_ts": "2024-08-06T13:57:43.053Z",
      "agent_utterance_ct": 0,
      "agent_first_response_ms": 0,
      "timeout_ts": "2024-08-06T13:57:43.053Z",
      "last_customer_utterance_ts": "2024-08-06T13:57:43.053Z",
      "customer_utterance_ct": 0,
      "is_resolved": true,
      "customer_ended_ts": "2024-08-06T13:57:43.053Z",
      "customer_params_field_01": "string",
      "customer_params_field_02": "string",
      "customer_params_field_03": "string",
      "customer_params_field_04": "string",
      "customer_params_field_05": "string",
      "customer_params_field_06": "string",
      "customer_params_field_07": "string",
      "customer_params_field_08": "string",
      "customer_params_field_09": "string",
      "customer_params_field_10": "string",
      "customer_params_key_name_01": "string",
      "customer_params_key_name_02": "string",
      "customer_params_key_name_03": "string",
      "customer_params_key_name_04": "string",
      "customer_params_key_name_05": "string",
      "customer_params_key_name_06": "string",
      "customer_params_key_name_07": "string",
      "customer_params_key_name_08": "string",
      "customer_params_key_name_09": "string",
      "customer_params_key_name_10": "string"
    }
}

​
Field Explanations

FieldDescription
api_versionMajor and minor version of the API, compatible with the base major version
nameSource of this event stream - use for filtering / routing
event_typeEvent type within the stream - use for filtering / routing
event_idUnique ID of an event, used to identify identical duplicate events
meta_data.create_timeUTC creation time of this message
meta_data.event_timeUTC time the event happened within the system - usually some ms before create time
meta_data.session_idCustomer-side identifier to link events together based on customer session
meta_data.issue_idASAPP internal tracking of a conversation - used to tie events together in the ASAPP system
meta_data.company_subdivisionFiltering metadata
meta_data.company_segmentsFiltering metadata
meta_data.client_idMay include client type, device, and version
data.customer_idInternal ASAPP identifier of the customer
data.rep_idInternal ASAPP identifier of an agent. Will be null if no rep is assigned
data.group_idInternal ASAPP identifier of a company group or queue. Will be null if not routed to a group of agents
detailsThe details of the event. All details are omitted when empty

​
Event Types

ISSUE_CREATED
ISSUE_ENDED
INTENT_CHANGE
FIRST_INTENT_UPDATED
INTENT_PATH_UPDATED
NODE_VISITED
LINK_RESOLVED
FLOW_SUCCESS
FLOW_SUCCESS_NEGATED
END_SRS_RESPONSE
SURVEY_SUBMITTED
CONVERSATION_ENDED
CUSTOMER_ENDED
ISSUE_SESSION_UPDATED
DETECTED
OPPORTUNITY_ENDED
OPPORTUNITY_ESCALATED
QUEUED
QUEUE_ABANDONED
TIMED_OUT
TEXT_MESSAGE
FIRST_OPPORTUNITY
QUEUED_DURATION
CUSTOMER_RESPONSE_BY_OPPORTUNITY
ISSUE_OPPORTUNITY_QUEUE_INFO_UPDATED
ASSIGNED
ASSIGNMENT_ENDED
AGENT_RESPONSE_BY_OPPORTUNITY
SUPERVISOR_UTTERANCE_BY_OPPORTUNITY
AGENT_FIRST_RESPONDED
ISSUE_ASSIGNMENT_AGENT_INFO_UPDATED
LAST_FLOW_ACTION_CALLED
JOURNEY_CUSTOMER_PARAMETERS

​
Queue State Feed

The queue state feed provides a set of events describing the state of a queue over the course of time. ASAPP processes the event data before pushing it into the queue feed to:

  • Collect queue volume, queue time and queue hours events into a single feed of the queue state
  • Add metadata properties to the events to assist with contextualizing the events

ASAPP’s queue feed does not implement aggregation. Any aggregation or deduplication required by the customer’s use case will need to be executed by the customer after receiving queue events.

​
Sample Event JSON

{
  "api_version": "v1.3.0",
  "name": "com.asapp.event.queue",
  "meta_data": {
    "create_time": "2022-06-21T20:02:54.418Z",
    "event_time": "2022-06-21T20:02:54.418Z",
    "session_id": "string",
    "issue_id": "string",
    "company_subdivision": "string",
    "company_id": "string",
    "company_segments": [
      "string"
    ],
    "client_id": "string",
    "client_type": "SMS"
  },
  "data": {
    "queue_id": "string",
    "queue_name": "string",
    "business_hours_time_zone_offset_minutes": 0,
    "business_hours_time_zone_name": "string",
    "business_hours_start_minutes": [
      0
    ],
    "business_hours_end_minutes": [
      0
    ],
    "holiday_closed_dates": [
      "2022-06-21T20:02:54.418Z"
    ],
    "queue_capping_enabled": true,
    "queue_capping_estimated_wait_time_seconds": "Unknown Type: float",
    "queue_capping_size": 0,
    "queue_capping_fallback_size": 0
  },
  "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event_type": "UNKNOWN",
  "details": {
    "last_queue_size": 0,
    "last_queue_size_ts": "2022-06-21T20:02:54.418Z",
    "last_queue_size_update_type": "UNKNOWN",
    "estimated_wait_time_updated_ts": "2022-06-21T20:02:54.418Z",
    "estimated_wait_time_seconds": "Unknown Type: float",
    "estimated_wait_time_is_available": true
  }
}

​
Field Explanations

FieldDescription
api_versionMajor and minor version of the API, compatible with the base major version
nameSource of this event stream - use for filtering / routing
meta_data.create_timeUTC creation time of this message
meta_data.event_timeUTC time the event happened within the system - usually some ms before create time
meta_data.session_idCustomer-side identifier to link events together based on customer session. May be null for system-generated events.
meta_data.issue_idASAPP internal tracking of a conversation - used to tie events together in the ASAPP system
meta_data.company_subdivisionFiltering metadata
meta_data.company_idThe short name used to uniquely identify the company associated with this event. This will be constant for any feed integration.
meta_data.company_segmentsFiltering metadata
meta_data.client_idMay include client type, device, and version
meta_data.client_typeThe lower-cardinality, more general classification of the client used for the customer interaction
data.queue_idInternal ASAPP ID for this queue
data.queue_nameThe name of the queue
data.business_hours_time_zone_offset_minutesThe number of minutes offset from UTC for calculating or displaying business hours
data.business_hours_time_zone_nameA time zone name used for display or lookup
data.business_hours_start_minutesA list of offsets (in minutes from Sunday at 0:00) that correspond to the time the queue transitions from closed to open
data.business_hours_end_minutesSame as business_hours_start_minutes but for the transition from open to closed
data.holiday_closed_datesA list of dates currently configured as holidays
data.queue_capping_enabledIndicates if any queue capping is applied when enqueueing issues
data.queue_capping_estimated_wait_time_secondsIf the estimated wait time exceeds this threshold (in seconds), the queue will be capped. Zero is no threshold.
data.queue_capping_sizeIf the queue size is greater than or equal to this threshold, the queue will be capped. Zero is no threshold. This applies independent of estimated wait time.
data.queue_capping_fallback_sizeIf there is no estimated wait time and the queue size is greater than or equal to this threshold, the queue will be capped. Zero is no threshold.
event_idUnique ID of an event, used to identify identical duplicate events
event_typeEvent type within the stream - use for filtering / routing
details.last_queue_sizeThe latest size of the queue
details.last_queue_size_tsTime when the latest queue size update happened
details.last_queue_size_update_typeThe reason for the latest queue size change
details.estimated_wait_time_updated_tsTime when the estimate was last updated
details.estimated_wait_time_secondsThe number of seconds a user at the end of the queue can expect to wait
details.estimated_wait_time_is_availableIndicates if there is enough data to provide an estimate
Retrieving Data via S3Secure Data Retrieval