@servexai/sdk

v1.0.31

Published

18 days ago

Servex AI SDK - Embed AI chat widgets on any website with React, Vue, WordPress, and vanilla JavaScript support

Downloads

3,154

0High
0Medium
0Low

elcentinos

servex ai chat widget chatbot customer-support react vue wordpress webflow framer sdk typescript

🚀 ServexUI

Embed AI-powered chat widgets on any website with just a few lines of code. Built for developers and businesses who want to integrate intelligent customer support seamlessly.

✨ Features

Universal Compatibility: Works with vanilla JavaScript, React, Vue.js, WordPress, and more
API Key Authentication: Secure access using your Servex AI API keys
Customizable UI: Position, theme, and styling options
Auto-popup: Configurable delay before showing the chat widget
Event System: Listen to chat events and integrate with your analytics
TypeScript Support: Full TypeScript definitions included
Lightweight: Minimal bundle size with tree-shaking support

📦 Installation

CDN (Recommended for quick setup)

<script
  src="https://cdn.jsdelivr.net/npm/@servexai/sdk@latest/dist/index.js"
  data-servex-api-key="your-api-key-here"
  data-servex-agent-id="your-agent-id" <!-- Required for auto-initialization -->
  data-servex-customer-name="John Doe"
  data-servex-customer-id="12345"
  data-servex-position="bottom-right"
  data-servex-auto-show-delay="3000"
></script>

NPM/Yarn

npm install @servexai/sdk
# or
yarn add @servexai/sdk

🚀 Quick Start

Vanilla JavaScript

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/@servexai/sdk@latest/dist/index.js"></script>
  </head>
  <body>
    <script>
      // Initialize the chat widget
      const chatWidget = window.ServexUI.init({
        apiKey: 'your-api-key-here',
        agentId: 'your-agent-id', // Required
        customerName: 'John Doe',
        customerId: '12345',
        position: 'bottom-right',
        autoShowDelay: 3000,
      });

      // Listen for events
      chatWidget.on('ready', () => {
        console.log('Chat widget is ready!');
      });

      chatWidget.on('message', (message) => {
        console.log('New message:', message);
      });

      // Control the widget
      chatWidget.show();
      chatWidget.hide();
      chatWidget.toggle();
    </script>
  </body>
</html>

React

import React from 'react';
import { ServexUIProvider, ServexUIChat, useServexUI } from '@servexai/sdk/react';

function App() {
  return (
    <ServexUIProvider
      config={{
        apiKey: 'your-api-key-here',
        agentId: 'your-agent-id', // Required
        customerName: 'John Doe',
        customerId: '12345',
      }}
    >
      <div className="app">
        {/* Your app content */}
        <ServexUIChat
          config={{
            position: 'bottom-right',
            autoShowDelay: 3000,
          }}
        />
      </div>
    </ServexUIProvider>
  );
}

// Or use the hook directly
function MyComponent() {
  const plugics = useServexUI({
    apiKey: 'your-api-key-here',
    agentId: 'your-agent-id', // Required
  });

  const handleSendMessage = async () => {
    if (plugics) {
      const response = await plugics.sendMessage('Hello!');
      console.log('AI Response:', response);
    }
  };

  return <button onClick={handleSendMessage}>Send Message</button>;
}

WordPress

Download and install the plugics-chat.php plugin
Go to Settings > ServexUI Chat in your WordPress admin
Enter your API key and configure options
The chat widget will automatically appear on your site

Or use the shortcode in any post/page:

[plugics_chat agent_id="your-agent-id"]

⚙️ Configuration Options

| Option | Type | Default | Description | | --------------- | -------------------------------------------------------------- | --------------------- | -------------------------------------------------------- | | apiKey | string | Required | Your API key from Servex AI | | agentId | string | Required | Agent ID to chat with | | projectId | string | undefined | Project ID for the agent | | customerName | string | undefined | Name of the customer | | customerId | string | undefined | Unique identifier for the customer | | baseUrl | string | 'https://servex.so' | Base URL for the chat service | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Position of the chat widget | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Theme for the chat widget | | autoShowDelay | number | 3000 | Delay in milliseconds before auto-showing (0 = disabled) | | customStyles | Record<string, any> | {} | Custom CSS styles to apply |

Note: The SDK now uses the /api/v1/dev/ prefix for all API endpoints for better organization and consistency. For real-time streaming responses, use the /api/v1/dev/chat/message/stream endpoint.

🎯 API Reference

SDK Methods

interface ServexUIInstance {
  // UI Control
  show(): void;
  hide(): void;
  toggle(): void;
  destroy(): void;

  // Chat
  sendMessage(message: string): Promise<ChatResponse>;
  chatWithAgent(agentId: string, message: string, conversationId?: string): Promise<ChatResponse>;

  // Data Methods
  getConversations(): Promise<Conversation[]>;
  getConversation(conversationId: string): Promise<Conversation & { messages: ChatMessage[] }>;
  getAgent(agentId: string): Promise<Agent>;
  setParams(params: ChatParams): void;

  // Events
  on(event: string, callback: Function): void;
  off(event: string, callback: Function): void;
}

New Methods

`chatWithAgent(agentId, message, conversationId?)`

Chat directly with a specific agent without using the UI widget.

const response = await chatWidget.chatWithAgent('agent_123', 'Hello!', 'conv_456');
console.log(response.response); // AI response text
console.log(response.conversationId); // Conversation ID used

Parameters:

agentId (string): The ID of the agent to chat with
message (string): The message to send to the agent
conversationId (string, optional): Existing conversation ID to continue, or undefined for new conversation

Returns: Promise<ChatResponse> - Contains response, conversation ID, and metadata

`getConversations()`

Get all conversations for the current user/customer.

const conversations = await chatWidget.getConversations();
console.log(conversations);
// [{ id: 'conv_1', agent_id: 'agent_1', customer_name: 'John', ... }]

`getConversation(conversationId)`

Get a specific conversation with all messages.

const conversation = await chatWidget.getConversation('conv_123');
console.log(conversation.messages);
// Array of chat messages

`getAgent(agentId)`

Get information about a specific agent.

const agent = await chatWidget.getAgent('agent_123');
console.log(agent.name, agent.status);
// "Customer Support Agent", "running"

`setParams(params)`

Update chat parameters dynamically.

chatWidget.setParams({
  customerName: 'Jane Doe',
  customerId: 'user_456',
  agentId: 'agent_789',
});

Events

| Event | Description | Data | | ---------------- | ------------------------------- | ----------------------- | | ready | Widget is initialized and ready | { agentName: string } | | show | Widget becomes visible | undefined | | hide | Widget becomes hidden | undefined | | message | New message received | ChatMessage | | error | An error occurred | ServexUIError | | params_updated | Parameters were updated | ChatParams | | destroy | Widget is destroyed | undefined |

Types

interface ServexConfig {
  apiKey: string; // Required - Your API key from Servex AI
  agentId: string; // Required - Agent ID to chat with
  projectId?: string; // Optional - Project ID for the agent
  customerName?: string; // Optional - Name of the customer
  customerId?: string; // Optional - Unique identifier for the customer
  baseUrl?: string; // Optional - Base URL (default: 'https://servex.so')
  theme?: 'light' | 'dark' | 'auto'; // Optional - Theme
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; // Optional - Position
  autoShowDelay?: number; // Optional - Auto-show delay in milliseconds
  customStyles?: Record<string, any>; // Optional - Custom CSS styles
}

interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: Date;
}

interface ChatResponse {
  response: string;
  conversationId: string;
  table?: any;
  cards?: any[];
}

🔧 Framework Integrations

Vue.js

<template>
  <ServexUIChat :config="chatConfig" @ready="onChatReady" @message="onMessage" />
</template>

<script>
import { ServexUIChat } from '@servexai/sdk/vue';

export default {
  components: { ServexUIChat },
  data() {
    return {
      chatConfig: {
        apiKey: 'your-api-key',
        agentId: 'your-agent',
        customerName: 'Vue User',
      },
    };
  },
  methods: {
    onChatReady() {
      console.log('Vue chat ready!');
    },
    onMessage(message) {
      console.log('New message:', message);
    },
  },
};
</script>

Or use the composable:

import { useServexUI } from '@servexai/sdk/vue';

export default {
  setup() {
    const { widget, init, sendMessage } = useServexUI();

    const startChat = () => {
      init({
        apiKey: 'your-api-key',
        agentId: 'your-agent'
      });
    };

    return { startChat, sendMessage };
  }
};


### Webflow

Add this script to your Webflow site's **Site Settings > Custom Code**:

```html
<script src="https://cdn.jsdelivr.net/npm/@servexai/sdk@latest/dist/index.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
  const chatWidget = window.ServexUIWebflow.init({
    apiKey: 'your-api-key-here',
    agentId: 'your-agent-id',
    customerName: 'Webflow User',
    position: 'bottom-right'
  });
});
</script>

Or use data attributes:

<script
  src="https://cdn.jsdelivr.net/npm/@servexai/sdk@latest/dist/index.js"
  data-plugics-api-key="your-api-key"
  data-plugics-agent-id="your-agent"
  data-plugics-position="bottom-right"
></script>

Framer

import { ServexUIFramer } from '@servexai/sdk/framer';

export function ChatWidget() {
  return (
    <ServexUIFramer
      apiKey="your-api-key-here"
      agentId="your-agent-id"
      customerName="Framer User"
      position="bottom-right"
    />
  );
}

Svelte

<script>
  import { ServexUICore } from '@servexai/sdk/core';

  let chatWidget;

  function initChat() {
    chatWidget = new ServexUICore({
      apiKey: 'your-api-key',
      agentId: 'your-agent',
      customerName: 'Svelte User'
    });
  }

  function sendMessage() {
    chatWidget?.sendMessage('Hello!');
  }
</script>

<button on:click={initChat}>Start Chat</button>
<button on:click={sendMessage}>Send Message</button>

} };


### Svelte

```svelte
<script>
  import { onMount } from 'svelte';
  import { ServexUI } from '@servexai/sdk';

  let chatWidget;

  onMount(() => {
    chatWidget = ServexUI.init({
      apiKey: 'your-api-key',
      // ... other config
    });

    return () => {
      if (chatWidget) {
        chatWidget.destroy();
      }
    };
  });
</script>

<main>
  <!-- Your app content -->
</main>

Framer

Create a new Framer component
Add the ServexUI script to your project's custom code
Use the React integration in your component

Webflow

Go to your Webflow project settings
Add the ServexUI script to the custom code section
Use data attributes to configure the widget

🔐 Authentication

ServexUI uses API key authentication for all external requests. API keys are tied to specific projects and include permissions.

Creating API Keys

API keys can be created through the servex dashboard:

Go to Project Settings > API Keys
Click "Create API Key"
Set permissions (read, write, admin)
Copy the generated key (shown only once)

API Key Permissions

read: View conversations, agents, and project data
write: Send messages and create conversations
admin: Full access including agent management

Authentication Headers

All SDK API calls automatically include the Authorization header:

// Automatic header added by SDK
Authorization: Bearer your-api-key-here

Validation Flow

API Key Validation: Key is validated against database
Project Access: Ensures key belongs to accessible project
Permissions Check: Verifies required permissions for operation
Rate Limiting: Optional rate limiting per key
Usage Tracking: Updates last_used_at timestamp

📊 Analytics & Events

Track user interactions and integrate with your analytics platform:

chatWidget.on('message', (message) => {
  // Track in your analytics platform
  analytics.track('Chat Message', {
    messageLength: message.content.length,
    messageType: message.role,
  });
});

chatWidget.on('show', () => {
  analytics.track('Chat Widget Opened');
});

🐛 Troubleshooting

Widget doesn't appear

Check that your API key is valid
Verify the autoShowDelay setting
Check browser console for errors

Messages not sending

Ensure the API key has proper permissions
Check network connectivity
Verify agent ID is correct

Styling issues

Use customStyles to override default styles
Check for CSS conflicts with your site

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📞 Support

📧 Email: [email protected]
💬 Chat: Use the widget on our website!
📖 Docs: https://docs.servex.ai

Built with ❤️ by the Servex AI team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🚀 ServexUI

✨ Features

📦 Installation

CDN (Recommended for quick setup)

NPM/Yarn

🚀 Quick Start

Vanilla JavaScript

React

WordPress

⚙️ Configuration Options

🎯 API Reference

SDK Methods

New Methods

chatWithAgent(agentId, message, conversationId?)

getConversations()

getConversation(conversationId)

getAgent(agentId)

setParams(params)

Events

Types

🔧 Framework Integrations

Vue.js

Framer

Svelte

Framer

Webflow

🔐 Authentication

Creating API Keys

API Key Permissions

Authentication Headers

Validation Flow

📊 Analytics & Events

🐛 Troubleshooting

Widget doesn't appear

Messages not sending

Styling issues

📝 License

🤝 Contributing

📞 Support

`chatWithAgent(agentId, message, conversationId?)`

`getConversations()`

`getConversation(conversationId)`

`getAgent(agentId)`

`setParams(params)`