🛠️Client SDK

Client-side SDK functions for controlling the Wonderchat widget

The Wonderchat Client SDK provides JavaScript functions that allow you to programmatically control the chat widget on your website. These functions are available through the wonderchat object on the window object after the Wonderchat widget script is loaded.

Prerequisites

Before using these SDK functions, ensure that the Wonderchat widget script is properly embedded on your website. The functions will only be available after the widget has fully loaded.

Available Functions

wonderchat.changeChatbotId()

Changes the current chatbot displayed in the widget. This is useful when you want to dynamically switch between different chatbots based on user actions or page context.

Syntax:

wonderchat.changeChatbotId(chatbotId);

Parameters:

• chatbotId (string, required): The ID of the chatbot you want to switch to

Example:

// Switch to a different chatbot
wonderchat.changeChatbotId("your-new-chatbot-id");

// Example: Switch chatbot based on user selection
function switchToSupportBot() {
  wonderchat.changeChatbotId("support-bot-123");
}

function switchToSalesBot() {
  wonderchat.changeChatbotId("sales-bot-456");
}

wonderchat.toggleChat()

Controls the open/closed state of the chat widget. Can be used to programmatically open or close the chat, or toggle between states.

Syntax:

wonderchat.toggleChat(show);

Parameters:

• show (boolean, optional):

  • true: Opens the chat widget

  • false: Closes the chat widget

  • If omitted: Toggles the current state

Examples:

// Toggle the chat widget state
wonderchat.toggleChat();

// Explicitly open the chat widget
wonderchat.toggleChat(true);

// Explicitly close the chat widget
wonderchat.toggleChat(false);

// Example: Open chat when user clicks a help button
document.getElementById("help-button").addEventListener("click", () => {
  wonderchat.toggleChat(true);
});

wonderchat.identify()

Identifies the user for the current chat session. This helps in tracking conversations and providing personalized support.

Syntax:

wonderchat.identify(params);

Parameters:

• params (object, required): An object containing user identification data

  • email (string, optional): The user's email address

  • phoneNumber (string, optional): The user's phone number

  • name (string, optional): The user's name

  • custom (object, optional): An object containing any arbitrary custom identifiers

Examples:

// Identify a user by email
wonderchat.identify({ email: "[email protected]" });

// Identify a user with multiple fields
wonderchat.identify({
  email: "[email protected]",
  name: "John Doe",
  phoneNumber: "[phone]"
});

// Identify a user with custom fields
wonderchat.identify({
  email: "[email protected]",
  name: "John Doe",
  custom: {
    userId: "12345",
    accountType: "premium",
    company: "Acme Corp",
    department: "Engineering"
  }
});

// Example: Identify user after login
function onUserLogin(userData) {
  // Your login logic here

  // Identify the user in Wonderchat
  wonderchat.identify({
    email: userData.email,
    name: userData.name,
    phoneNumber: userData.phone,
    custom: {
      userId: userData.id,
      accountType: userData.subscription
    }
  });
}

// Example: Identify user from a form submission
document.getElementById("contact-form").addEventListener("submit", (e) => {
  e.preventDefault();
  const formData = new FormData(e.target);
  
  wonderchat.identify({
    email: formData.get("email"),
    name: formData.get("name"),
    phoneNumber: formData.get("phone"),
    custom: {
      source: "contact-form",
      interests: formData.get("interests")
    }
  });
});

wonderchat.clearHistory()

Clears the current chat history and starts a new chat session. This function removes all previous messages from the conversation and initializes a fresh chat session with the chatbot.

Syntax:

wonderchat.clearHistory();

Parameters:

• None

Examples:

// Clear chat history and start a new session
wonderchat.clearHistory();

// Example: Clear history when user clicks a "New Chat" button
document.getElementById("new-chat-button").addEventListener("click", () => {
  wonderchat.clearHistory();
});

// Example: Clear history after completing a transaction
function onTransactionComplete() {
  // Your transaction logic here

  // Start a fresh chat session
  wonderchat.clearHistory();
  wonderchat.toggleChat(true); // Optionally open the chat
}

wonderchat.prefillQuestion()

Programmatically prefills a question in the chatbot's input field for the user to send. This allows you to guide users by suggesting relevant questions based on the page context or user actions.

Syntax:

wonderchat.prefillQuestion(question);

Parameters:

• question (string, required): The text to prefill in the chatbot's input field

Examples:

// Prefill a question
wonderchat.prefillQuestion("How do I reset my password?");

// Example: Prefill question based on clicked FAQ item
document.querySelectorAll(".faq-item").forEach((item) => {
  item.addEventListener("click", () => {
    const question = item.getAttribute("data-question");
    wonderchat.prefillQuestion(question);
    wonderchat.toggleChat(true); // Open chat with prefilled question
  });
});

// Example: Prefill question from a help menu
function showHelpForFeature(feature) {
  const questions = {
    billing: "How can I update my billing information?",
    api: "How do I get started with the API?",
    integrations: "What integrations are available?",
  };

  if (questions[feature]) {
    wonderchat.prefillQuestion(questions[feature]);
    wonderchat.toggleChat(true);
  }
}

// Example: Prefill question from URL parameter
const urlParams = new URLSearchParams(window.location.search);
const question = urlParams.get("question");
if (question) {
  window.chatbotLoaded(() => {
    wonderchat.prefillQuestion(decodeURIComponent(question));
    wonderchat.toggleChat(true);
  });
}

Note: The prefilled question appears in the input field but is not automatically sent. Users need to click send or press Enter to submit the question.

Best Practices

1. Wait for Widget Load: Ensure the Wonderchat widget script is loaded and ready before calling SDK functions. The script must be embedded on your page first, then use the chatbotLoaded callback:

   // Use the chatbotLoaded callback to ensure the widget is ready
   window.chatbotLoaded(() => {
     // SDK functions are now available through the wonderchat object
     wonderchat.identify({ email: "[email protected]" });
     wonderchat.toggleChat(false); // Start with chat closed
   });

**Important**: The Wonderchat widget script must be loaded on your page before you can use `window.chatbotLoaded()` or any SDK functions.

2. **Error Handling**: Wrap SDK calls in try-catch blocks to handle cases where the widget might not be loaded:

   ```javascript
   try {
     wonderchat.changeChatbotId("new-bot-id");
   } catch (error) {
     console.error("Wonderchat widget not loaded:", error);
   }
   ```

3. **User Experience**: Consider the user experience when programmatically controlling the chat:
   - Don't open the chat automatically on page load unless necessary
   - Provide clear UI elements for users to control the chat state
   - Use `identify()` early in the user session for better conversation tracking

## Integration Examples

### Dynamic Chatbot Selection Based on Page

```javascript
// Switch chatbots based on the current page
window.chatbotLoaded(() => {
  const currentPath = window.location.pathname;

  if (currentPath.includes("/support")) {
    wonderchat.changeChatbotId("support-bot-id");
  } else if (currentPath.includes("/sales")) {
    wonderchat.changeChatbotId("sales-bot-id");
  } else {
    wonderchat.changeChatbotId("general-bot-id");
  }
});
```

### User Authentication Integration

```javascript
// Integrate with your authentication system
async function handleUserAuthentication() {
  const user = await getCurrentUser(); // Your auth function

  if (user) {
    // Identify the user in Wonderchat with all available data
    wonderchat.identify({
      email: user.email,
      name: user.displayName,
      phoneNumber: user.phoneNumber,
      custom: {
        userId: user.id,
        accountType: user.accountType,
        registeredAt: user.createdAt
      }
    });

    // Optionally open the chat for logged-in users
    wonderchat.toggleChat(true);
  }
}
```

### Custom Chat Launcher

```javascript
// Create a custom button to control the chat
const customChatButton = document.createElement("button");
customChatButton.textContent = "Need Help?";
customChatButton.onclick = () => wonderchat.toggleChat();
document.body.appendChild(customChatButton);
```

## Troubleshooting

If the SDK functions are not working:

1. Verify the Wonderchat widget script is properly embedded
2. Check the browser console for any errors
3. Ensure you're calling the functions after the widget has loaded
4. Confirm you're using the correct chatbot IDs

For additional support, contact us at [email protected]