Skip to main content
The ASAPP SDK (Web) allows you to quickly integrate GenerativeAgent chat into your website. The SDK provides a customizable chat interface that can seamlessly transfer conversations to your existing human agents when needed.
The ASAPP SDK works alongside your existing chat systems (like Salesforce Chat or Zendesk) rather than replacing them. When GenerativeAgent cannot handle a conversation, it transfers to your human agents using your original SDK.
Picture of what the ASAPP SDK (Web) looks like

​
How it works

The ASAPP SDK creates a seamless chat experience that works alongside your existing customer service infrastructure:
  1. Website loads SDK: Your website loads the ASAPP SDK script, which initializes the chat interface
  2. User talks to GA via SDK: Customers interact with GenerativeAgent through the SDK’s chat interface
  3. GA resolves conversation or transfers to agent: GenerativeAgent either resolves the customer’s issue or determines when human assistance is needed
  4. Transfer triggers existing chat system: When a transfer is needed, the SDK calls your custom function to load your existing chat system SDK and unload the ASAPP SDK
  5. Customer talks to human agent: The customer continues the conversation with a human agent using your existing chat system’s interface

​
Before you begin

Before implementing the ASAPP SDK, you need:

​
Getting started

Follow these steps to integrate the ASAPP SDK into your website:
1

Get your App ID

Contact your ASAPP account team to enable the web SDK and provide:
  • Include URLs: Pages where the chat widget should appear
  • Exclude URLs: Pages where the chat widget should be hidden (e.g., checkout, admin pages)
You’ll receive a unique App ID that identifies your SDK configuration.
The App ID is different from your API credentials and is specifically for the web SDK.
2

Add the script tag

Include the ASAPP SDK script in your website’s HTML:
<script src="https://app.asapp.com/ga-web-chat-sdk/chat-sdk.js"></script>
<script>
    (function (win, doc, hostname, namespace) {
      win[namespace] =
        win[namespace] ||
        function () {
          (win[namespace]._ = win[namespace]._ || []).push(arguments);
        };
      win[namespace].Host = hostname;
    })(window, document, 'https://' + window.location.host, 'ASAPP');
</script>
Add this script tag to all pages where you want the chat widget to appear.
3

Load the SDK

Initialize the SDK with your App ID and environment:
<script>
  ASAPP('load', {
    appId: 'your-sdk-app-id',
    environment: 'sandbox' // or 'production'
  });
</script>
4

Try out GenerativeAgent

The chat widget should now appear on your website with the default styling. You can start interacting with GenerativeAgent right away to verify the integration is working.
Try asking a simple question to confirm the chat widget is responding and GenerativeAgent is active.
5

Transfers and customization

This basic implementation allows you start interacting with GenerativeAgent but before you go live, you will need to implement transfers to be able to hand off conversations to your human agents:

Transfer handling

Implement seamless handoff to your human agents when GenerativeAgent cannot handle the conversation

Customize the look and feel

Customize the chat interface to match your brands look and feel

Input variables and tasks

Provide context to GenerativeAgent with taskName and inputVariables

​
Styling and customization

Customize the chat interface to match your brand using the styling configuration. As you will be loading your existing chat SDK on transfers, you will likely need to match the styling of your existing chat SDK to the GenerativeAgent chat interface. 
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  styling: {
    primaryColor: '#FF5733',
    accentColor: '#33FF57',
    textColor: '#FFFFFF',
    brandImageUrl: 'https://your-domain.com/logo.png',
    brandText: 'Your Company',
    header: {
      backgroundColor: '#F0F0F0',
      textColor: '#000000',
    },
    message: {
      user: {
        backgroundColor: '#F0F0F0',
        textColor: '#333333',
      }
    }
  }
});
​
styling.primaryColor
string
Primary brand color for buttons and highlights. Accepts hex colors (e.g., ‘#FF5733’).
​
styling.accentColor
string
Accent color for secondary elements. Accepts hex colors.
​
styling.textColor
string
Default text color for the chat interface. Accepts hex colors.
​
styling.brandImageUrl
string
URL to your company logo image. Recommended size: 40x40 pixels.
​
styling.brandText
string
Your company name to display in the chat header.
​
styling.header.backgroundColor
string
Background color for the chat header. Accepts hex colors.
​
styling.header.textColor
string
Text color for the chat header. Accepts hex colors.
​
styling.message.user.backgroundColor
string
Background color for user messages. Accepts hex colors.
​
styling.message.user.textColor
string
Text color for user messages. Accepts hex colors.

​
Input variables and task configuration

You can provide context to GenerativeAgent when it starts a new conversation by specifying the starting task name and input variables: 
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  taskName: 'customer_support',
  inputVariables: {
    'current_plan': 'SILVER',
    'customer_since': '2024-01-01',
    'user_id': '12345'
  }
});
​
taskName
string
The specific task name to trigger when the conversation starts. This determines which GenerativeAgent configuration to use.
​
inputVariables
object
Key-value pairs of context variables to provide to GenerativeAgent. These help personalize the conversation.

​
Handle transfers

When GenerativeAgent cannot handle a conversation, it triggers a transfer using the onTransfer callback. There are two types of transfers:
  • Agent transfers (transferToAgent): When GenerativeAgent determines a human agent is needed, it transfers to your existing chat SDK (Salesforce, Zendesk, etc.) which should immediately engage a human agent.
  • System transfers (transferToSystem): When GenerativeAgent completes its task and needs to hand control back to your external system, it uses System Transfer Functions to pass relevant conversation data.
Your code should handle both transfer types appropriately in the onTransfer callback.
Depending on your platform, you may need to create dedicate conversation entry point for these transfers to be able to directly engage the human agent.Sending users through another option menu or intent classification before engaging the human agent is a frustrating experience for your customers and should be avoided.
Example onTransfer callback
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  onTransfer: (context) => {
    // Handle the transfer to your human agents
    console.log('Transfer triggered:', context);
    
    // Access transfer information
    const transferType = context.transferType; // 'transferToAgent' or 'transferToSystem'
    const transcript = context.transcript;
    
    if (transferType === 'transferToSystem') {
      // Only available for system transfers
      const transferVariables = context.transferVariables;
      const referenceVariables = context.referenceVariables;
    }
    
    // Example context objects:
    // Agent transfer:
    // {
    //   transferType: "transferToAgent",
    //   transcript: [
    //     { text: "I need help", sender: "CUSTOMER", timestamp: "2024-01-15T10:30:00Z" }
    //   ]
    // }
    // 
    // System transfer:
    // {
    //   transferType: "transferToSystem",
    //   transcript: [...],
    //   transferVariables: { priority: "high" },
    //   referenceVariables: { customerId: "12345" }
    // }
    
    // Unload the ASAPP SDK before loading your existing chat system
    ASAPP('unload');
    
    // Load your existing chat SDK (Salesforce, Zendesk, etc.)
    // Pass the conversation context to your human agents
    // This varies depending on your platform
  }
});
​
context.transferType
string
Type of transfer: transferToAgent for human agent escalation or transferToSystem for system-level transfer.
​
context.transcript
array
Array of message objects representing the conversation transcript up to the transfer point. Each message has the same structure as the message parameter in onMessage.
​
context.transferVariables
object
Data that should be passed to the next system handling the conversation. Only available for system transfers (transferToSystem).
​
context.referenceVariables
object
Context information about the customer and conversation that should be preserved. Only available for system transfers (transferToSystem).

​
Unload the SDK

When transferring to human agents, you must unload the ASAPP SDK to remove the chat interface and clean up resources: 
ASAPP('unload');
Always call ASAPP('unload') in your transfer function to ensure the ASAPP chat interface is properly removed before loading your existing chat system.

​
Conversation events

The SDK exposes functions for key conversation events that you can use to integrate with your existing systems:

​
onNewChat

Called when GenerativeAgent starts a new chat. 
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  onNewChat: (conversationId, userId) => {
    // Create conversation in your system
    console.log('New chat started:', conversationId, userId);
    // Example: conversationId = "conv_123", userId = "user_456"
  }
});
​
conversationId
string
Unique identifier for the new conversation.
​
userId
string
The customer identifier for the user who started the conversation. Initially, this is randomly generated by the SDK but if the customer authenticates, this will be the customer identifier provided by the authenticationRequest callback.

​
onMessage

Called when either GenerativeAgent or the user sends a message. 
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  onMessage: (message) => {
    // Update your CCaaS system with the new message
    console.log('Message received:', message);
    // Example: message.text = "Hello, how can I help?"
    //         message.sender = "BOT"
    //         message.timestamp = "2024-01-15T10:30:00Z"
  }
});
​
message.text
string
The text content of the message.
​
message.sender
string
Who sent the message: 'CUSTOMER' or 'BOT'.
​
message.timestamp
string
ISO 8601 timestamp of when the message was sent.

​
onEndChat

Called when the user chooses to end the conversation:
This callback is not invoked when GenerativeAgent transfers the conversation.
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  onEndChat: (conversationId, transcript) => {
    // Handle conversation end in your system
    console.log('Chat ended:', conversationId, transcript);
    // Example: conversationId = "conv_123"
    //         transcript[0].text = "Hello"
    //         transcript[0].sender = "CUSTOMER"
    //         transcript[0].timestamp = "2024-01-15T10:30:00Z"
  }
});
​
conversationId
string
Unique identifier for the conversation that ended.
​
transcript
array
Complete array of message objects from the conversation. Each message has the same structure as the message parameter in onMessage.

​
Authentication handling

Some API Connections require user-specific authentication data to access your APIs. When GenerativeAgent needs to call an API that requires client authentication, it will trigger the authenticationRequest callback.
Authentication is only required when your API Connections use client authentication data.If your API Connections only use static authentication (like API keys or basic auth), you won’t need to implement this callback.
Implement the authenticationRequest callback to return the required authentication data:
Example authenticationRequest callback
ASAPP('load', {
  appId: 'your-sdk-app-id',
  environment: 'production',
  authenticationRequest: async () => {
    // Your authentication logic here
    // Return the required structure:
    return {
      customerExternalId: 'your_customer_id',
      auth: {
        // Authentication data structure depends on your API Connection
        token: 'user_specific_token',
        expiresAt: '2025-01-01'
      }
    };
  }
});
​
return.customerExternalId
string
Your internal customer identifier that will be passed to API Connections.
​
return.auth
object
Authentication data object. The structure depends on your API Connection’s authentication method configuration.

​
Complete implementation example

Here’s a complete example showing all configuration options: 
<script src="https://cdn.example.com/generative-agent-sdk.js"></script>
<script>
  ASAPP('load', {
    appId: 'your-sdk-app-id',
    environment: 'production',
    taskName: 'customer_support',
    inputVariables: {
      'current_plan': 'SILVER',
      'customer_since': '2024-01-01',
      'user_id': '12345'
    },
    styling: {
      primaryColor: '#FF5733',
      accentColor: '#33FF57',
      textColor: '#FFFFFF',
      brandImageUrl: 'https://your-domain.com/logo.png',
      brandText: 'Your Company',
      header: {
        backgroundColor: '#F0F0F0',
        textColor: '#000000',
      },
      message: {
        user: {
          backgroundColor: '#F0F0F0',
          textColor: '#333333',
        }
      }
    },
    onNewChat: (conversationId, userId) => {},
    onMessage: (message) => {}, 
    onEndChat: (conversationId, transcript) => {},
    onTransfer: (context) => {},
    authenticationRequest: () => {}
  });
</script>

​
Next steps

With the ASAPP SDK successfully integrated, consider these next steps:

Configuration Overview

Learn how to configure GenerativeAgent’s behaviors, tasks, and communication style

Connect your APIs

Configure your APIs to allow GenerativeAgent to access necessary data and perform actions

Go Live

Prepare your GenerativeAgent integration for production deployment
⌘I