Web Widget Platform

Widget Types

Fonada supports two primary widget configurations. The widget type is controlled using the channel parameter when creating an agent.

Getting Started

Setting up the Fonada Web Widget requires only a few steps. The platform automatically manages session handling, message rendering, AI responses, and browser storage.

1. Authenticate using the Fonada API.
2. Create a widget agent.
3. Save agent_id and agent_key.
4. Customize widget appearance and behavior.
5. Embed the widget script into your website.
6. Start receiving live AI conversations.

Authentication

All JWT-authenticated operations require an access token obtained from the authentication endpoint.

Endpoint: POST /auth/v1/token?grant_type=password

curl -X POST "https://app.fonada.ai/auth/v1/token?grant_type=password" \
-H "apikey: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"email": "you@email.com", "password": "yourpassword"}'

Widget Setup

Fonada supports both Text Widgets and Voice Widgets. Configure the agent payload based on your chosen channel.

Text Widget Example

{
  "channel": "chatbot",
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "system_prompt": "You are a helpful assistant."
}

Voice Widget Example

{
  "channel": "web_widget",
  "tts_provider": "fonadalabs",
  "stt_provider": "fonadalabs",
  "voice": "Mayra"
}

Widget Customization

The widget can be fully customized to match your business branding and user experience requirements.

• Custom button colors
• Header styling
• Message bubble colors
• Dark and light themes
• Widget positioning
• Custom CTA icons
• Custom logos
• Font customization

Recommended Design Guidelines

• Use brand colors consistently
• Maintain WCAG-compliant contrast ratios
• Place the widget in the bottom-right corner
• Avoid overlapping forms and navigation menus
• Use optimized PNG or SVG logos

Widget Embedding

Embedding the widget requires only a single script tag placed before the closing </body> tag.

<script src="https://app.fonada.ai/functions/v1/widget?agent_id=agent_uuid_789&agent_key=sk_live_widget_xyz123"></script>

Once embedded, the widget automatically initializes conversations, renders messages, handles sessions, and processes AI responses.

Programmatic Controls

The widget exposes JavaScript APIs that allow developers to control widget behavior programmatically:

• Open and close widget dynamically
• Send messages from JavaScript
• Clear conversation sessions
• Attach custom user information
• Listen for AI message events

Interactive Features

Quick Reply Buttons

Quick reply buttons improve engagement by allowing users to start predefined workflows instantly.

Welcome Messages

Welcome messages are displayed when the widget opens for the first time. Keep welcome text short, conversational, and action-oriented.

Session & Chat Management

• Sessions auto-create on first message
• Sessions auto-expire after inactivity
• Conversation history stored in localStorage
• Cross-tab synchronization supported
• Headless API chat supported

Analytics & Reporting

Fonada provides detailed widget analytics to visualize user engagement and business performance.

Widget Management

Advanced users can upload fully customized widget.js implementations using the widget upload manager.

• Upload custom widget files
• Manage widget version history
• Track upload timestamps
• Maintain multiple widget versions

Error Handling & Debugging

Best Practices

• Load script before closing body tag
• Optimize logo images under 100 KB
• Use responsive layouts for mobile
• Use GPT-4o-mini for lightweight use cases
• Track conversation analytics regularly
• Test on multiple browsers and devices

Framework Integration Examples

API Reference Summary

Conclusion

The Fonada Web Widget Platform provides a complete enterprise-grade solution for deploying AI-powered conversational experiences on websites. With advanced customization, analytics, session handling, and framework integrations, businesses can rapidly build scalable customer engagement systems while maintaining high performance, flexibility, and user experience standards.