Web JavaScript API

This section details the various API methods you can call to the ASAPP Chat SDK.

Before making any API calls, make sure you’ve integrated the ASAPP SDK script on your page.

Once you’ve integrated the SDK with your site, you can use the JavaScript API to toggle settings in the Chat SDK, trigger events, or send information to ASAPP.

The Chat SDK Web JavaScript API allows you to perform a variety of actions. The most common are: initializing the SDK with the ‘load’method, setting customer authorizations with ‘setCustomer’, or toggling the display of the iFrame with the ‘show’ or ‘hide’ methods.

Read on for details on each of these methods:

• action: ‘on’ or ‘off'

• 'getState'

• 'hide'

• 'load'

• 'refresh'

• 'send'

• 'set'

• 'setCustomer'

• 'setIntent'

• 'show'

• 'showChatInstead’

unload

​

action: ‘on’ or ‘off’

This API subscribes or unsubscribes to events that occur within the Chat SDK. A developer can apply custom behavior, track metrics, and more by subscribing to one of the Chat SDK custom events. To utilize the Action API, pass either the on (subscribes) or off (unsubscribes) keywords to the ASAPP method. The next argument is the name of the event binding.

The final argument is the callback handler you wish to attach. The following code snippet is an example of the Action API subscribing and unsubscribing to the agent:assigned and message:received events:

function agentAssignedHandler (event) {
    onAgentAssigned(event.detail.issueId, event.detail.externalSenderId);
}
function messageHandler (event) {
    const { isFirstMessage, externalSenderId } = event.detail;
    if (isFirstMessage && externalSenderId) {
        OnAgentInteractive(event.detail.issueId, event.detail.customerId);
    } else if (isFirstMessage === false && isFromRep) {
        ASAPP('off', 'message:received', messageHandler);
    }
}
ASAPP('load', {
    onLoadComplete: () => {
        ASAPP('on', 'agent:assigned', agentAssignedHandler);
        ASAPP('on', 'message:received', messageHandler);
    }
});

​

Event Object

Each event receives a CustomEvent object as the first argument to your event handler. This is a standard event object with all typical interfaces. The object has an event.type with the name of the event and an event.detail key which contains the following custom properties:

issueId (Number)

The ASAPP identifier for an individual issue. This ID may change as a user completes and starts new queries to the ASAPP system.

customerId (Number)

The ASAPP identifier for a customer. This ID is consistent for authenticated users but may be different for anonymous ones. Anonymous users will have a consistent ID for the duration of their session.

externalSenderId (String)

The external identifier you provide to ASAPP that represents an agent identifier. This property will be undefined if the user is not connected with an agent.

​

Chat Events

Chat events trigger when a user opens or closes the Chat SDK window. These events do not have any additional event details.

chat:show

• Cancellable: true

This event triggers when a user opens the Chat SDK. It may fire multiple times per session if a user repeatedly closes and opens the chat.

chat:hide

• Cancellable: true

This event triggers when a user closes the Chat SDK. It may fire multiple times per session if a user repeatedly opens and closes the chat.

​

Issue Events

Issue events occur when a change in state of an Issue occurs within the ASAPP system. These events do not have any additional event details.

issue:new

• Cancellable: false

This event triggers when a user has opened a new issue. It fires when they first open the Chat SDK or if they complete an issue and start another one.

issue:end

• Cancellable: false

This event triggers when a user or agent has ended an issue. It fires when the user has completed an automated support request or when a user/agent ends an active chat.

​

Agent Events

Agent events occur when particular actions occur with an agent within ASAPP’s system. These events do not have any additional event details.

agent:assigned

• Cancellable: false

This event triggers when a user is connected to an agent for the first time. It fires once the user has left an automated support flow and has been connected to a live support agent.

​

Message Events

Message events occur when the user receives a message from either SRS or an agent. These events have the following additional event details:

senderType (String) 

Returns either srs or agent.

isLiveChat (Boolean) 

Returns true when a user is connected with an agent. Returns false when a user is within an automated flow.

isFirstMessage (Boolean) 

Returns true only when a message is the first message received from an agent or SRS. Otherwise returns false.

message:received

• Cancellable: false

This event triggers whenever the Chat SDK receives a message event to the chat log. It will fire when a user receives a message from SRS or an agent.

​

‘getState’

This API returns the current state of Chat SDK session. It accepts a callback which receives the current state object.

ASAPP('getState', function(state) {
    console.log(state);
});

​

State Object

The state object contains the following keys which give you insight into the user’s actions:

hasContext (Object) 

Returns the current context known by the SDK.

hasCustomerId (Boolean) 

Returns true when the SDK has been provided with a CustomerId setting.

isFullscreen (Boolean) 

Returns true when the SDK will render in fullscreen for mobile web devices.

isLiveChat (Boolean) 

Returns true when the use is connected to an agent.

isLoggingIn (Boolean) 

Returns true if the user has been presented with and clicked on a button to Log In.

isMobile(Boolean) 

Returns true when the SDK is rendering on a mobile or tablet device.

isOpen (Boolean) 

Returns true if the user has the SDK open on the current or had it open on the previous page.

unreadMessages (Integer) 

Returns a count of how many messages the user has received since minimizing the SDK.

​

‘hide’

This API hides the Chat SDK iframe. See Show for revealing the Chat SDK iframe. This method is useful for when you want to close the SDK iframe after certain page interactions or if you’ve provided a custom Badge entry point.

ASAPP('hide');

​

‘load’

This API initializes the ASAPP Chat SDK for display on your pages. The method’s second argument is an object accepting a variety of properties. The Load method has two required properties, APIHostname and AppId.

ASAPP('load', {
    APIHostname: 'API_HOSTNAME',
    AppId: 'APP_ID'
});

Please see the SDK Settings page for a list of all the available properties that can be passed to the Load API.

​

‘refresh’

This API checks to make sure that Triggers work properly when a page URL changes in a SPA (Single-Page Application). You should call this API every time the page URL changes if your website is a SPA.

ASAPP('refresh')

​

‘send’

This API proactively sends the context object defined in your contextProviderHandler function to ASAPP’s API. It is primarily used to send information that is used to show a proactive chat prompt when a specific criteria or set of criteria are met. The Send API is rate limited to one request for every 5 seconds. It accepts a single argument, represented as an object. This should contain the CustomerInfo object, which enables you to send a set of key-value pairs to ASAPP. For example, you could use a key within CustomerInfo to indicate that a customer had abandoned their shopping cart. Do not use the send API for transmitting any information that you would consider sensitive or Personally Identifiable Information (PII). The accepted keys are listed below.

​

Send Properties

These keys are required when calling the send API.

type (String) Required

The type of event you’re sending to ASAPP. Below are the possible values you may set as an event type:

• ‘customer’. See the “Event Type: Customer” section below.

data (Object)

The data you’re attaching to the event. The data object contains key and value pairs that are appropriate to the event type you are sending.

​

Event Type: Customer

This event type sends information about a user’s interaction on your site to ASAPP. This allows you to send promotional messages or route them to particular use cases when they interact with the Chat SDK. The data for a customer event type should be an object containing properties similar to your CustomerInfo object.

ASAPP('send', {
    type: 'customer',
    data: {
        "key1": "value1",
        "key2": "value2"
    }
});

​

‘set’

This API applies various user information to the Chat SDK. Calling this API does not make a network request. The API accepts two arguments. The first is the name of the key you want to update. The second is the value that you wish to assign the key.

ASAPP('set', 'Auth', { Token: '3858f62230ac3c915f300c664312c63f' });
ASAPP('set', 'ExternalSessionId', 'j6oAOxCWZh...');

Please see the Context Provider page for a list of all the properties you can provide to this API.

​

‘setCustomer’

This API provides an access token with your customer’s account after the Chat SDK has already loaded. This method is useful if a customer logs into their account or if you need to refresh your customer’s auth token from time to time. See the SDK Settings section for details on the CustomerId (Required), ContextProvider (Required), and UserLoginHandler properties accepted for SetCustomer’s second argument.

ASAPP('setCustomer', {
    CustomerId: 'a1b2c3x8y9z0',
    ContextProvider: function (callback) {
        var context = {
            Auth: {
                Token: '3858f62230ac3c915f300c664312c63f'
            }
        };
        callback(context);
    }
});

​

‘setIntent’

This API lets you set an intent after Chat SDK has already been loaded and will take effect even if the user is in chat. ASAPP recommends that you use Intent via App Settings during load.

This method takes an object as a parameter, with a required key of Code. Code accepts a string. Your team and your ASAPP Implementation Manager will determine the available values.

ASAPP('setIntent', {Code: 'PAYBILL'});

​

‘show’

This API shows the Chat SDK iframe. See Hide for hiding the Chat SDK iframe. This method is useful for when you want to open the SDK iframe after certain page interactions or if you’ve provided a custom Badge entry point.

ASAPP('show');

​

‘showChatInstead’

This API displays the Chat Instead feature.

This API displays the Chat Instead feature.

In order to enable this feature, please integrate with the showChatInstead API and then contact your Implementation Manager.

Options:

Example Use Case:

<a href="tel:8001234567" onclick="ASAPP('showChatInstead', {'phoneNumber': '(800) 123-4567'})">(800) 123-4567</a>

​

unload

This API removes all the SDK related elements from the DOM (Badge, iframe, and Proactive Messages if any). If the SDK is already open or a user is in live chat, ASAPP will ignore this call. To reload the SDK, you need to call the “Load” API.

ASAPP('unload')