Custom Actions

Add client-side action buttons and forms inside the chat. Define actions in your config and handle callbacks to submit data to external backends.

Defining Actions

Configure custom actions in your ChatSpark agent or pass them via the widget data config. Actions appear as buttons or form elements the user can interact with during the conversation:

javascript

// Actions defined in the widget data config
const instance = ChatSpark({
  chatbotId: 'YOUR_ID',
  data: {
    actions: [
      {
        id: 'book_demo',
        type: 'button',
        label: 'Book a demo',
        primary: true
      },
      {
        id: 'contact_sales',
        type: 'form',
        fields: [
          { key: 'name', label: 'Name', required: true },
          { key: 'email', label: 'Email', required: true, type: 'email' }
        ]
      }
    ]
  }
});

Handling Action Callbacks

When a user clicks a button or submits a form, the action-triggered event fires. Use it to run your logic (e.g. redirect, API call):

javascript

window.ChatSpark.on('action-triggered', function(payload) {
  const { actionId, actionType, data } = payload;

  if (actionId === 'book_demo') {
    window.location.href = 'https://calendly.com/your-team/demo';
    return;
  }

  if (actionId === 'contact_sales' && actionType === 'form') {
    // data contains the form field values
    submitToCRM(data);
  }
});

Submitting Data to External Backends

Send form submissions to your own API or CRM. Handle validation and errors on your server:

javascript

window.ChatSpark.on('action-triggered', async function(payload) {
  if (payload.actionId !== 'newsletter_signup') return;

  try {
    const res = await fetch('https://your-api.com/webhooks/newsletter', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: payload.data.email,
        source: 'chat_widget',
        chatbotId: 'YOUR_ID'
      })
    });

    if (!res.ok) throw new Error('Signup failed');
    // Optionally show success message in chat
  } catch (err) {
    console.error('Newsletter signup failed:', err);
  }
});

Keep secrets server-side

Run sensitive logic on your server. Never expose API keys or secrets in client-side widget code. Use server-side endpoints or serverless functions for CRM integrations.

Action Types

Supported action types:

button - Simple clickable button. Use for links or single-step actions.
form - Multi-field form. Use for lead capture, surveys, or feedback.
link - Opens a URL in a new tab when clicked.

Custom Messages

Identity Verification