AI Assistants

Overview

AI Assistants are the core of Happ. Each assistant is a configurable AI agent that handles conversations across connected channels. You can create multiple assistants for different purposes — support, sales, booking, and more.

For the full API reference, see api.happ.tools/reference.

Creating an Assistant

Via Dashboard

1. Navigate to Assistants in the sidebar
2. Click Create Assistant
3. Fill in the name and select a voice (for voice calls)
4. Click Save
5. Configure additional settings in the assistant detail view

Via API

POST /api/assistants
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "name": "Customer Support Bot",
  "promptText": "You are a helpful customer support assistant...",
  "firstMessage": "Hello! How can I help you today?",
  "llmProvider": "openai",
  "llmModel": "gpt-4o",
  "language": "en"
}

Configuration

Name

A descriptive name for your assistant (e.g., "Customer Support", "Sales Bot", "Booking Assistant"). Visible in the dashboard for organizing multiple assistants.

First Message

The greeting sent when a new conversation starts. This is the first thing your customer sees.

Prompt (System Instructions)

The prompt defines your assistant's personality, knowledge, rules, and behavior. This is the most important configuration.

Tips for effective prompts:

• Be specific — Clearly state who the assistant is and what it should do
• Define boundaries — What the assistant should and shouldn't discuss
• Include key info — Business hours, policies, contact details
• Set tone — Formal, casual, friendly, professional
• Guide handoffs — When to transfer to a human via turnOffAiMode

Example:

You are a friendly support assistant for TechStore.
Help customers with product questions, order tracking, and returns.

Rules:
- Be polite and professional
- If you don't know, direct them to support@techstore.com
- Never discuss competitor products
- If the customer requests a human, use turnOffAiMode

Business info:
- Hours: Mon-Fri 9:00-18:00 (Kyiv time)
- Returns: 14-day return policy
- Shipping: Free on orders over 1000 UAH

Language

Set the primary language (default: en). Affects how the AI generates responses.

AI Model Configuration

LLM Provider & Model

Choose which AI powers your assistant:

Each provider requires an API key. Add it via Integrations > Add Integration > select the provider.

Recommendations:

• Most use cases: GPT-4o or Claude Sonnet 3.5 — best quality/cost balance
• Simple Q&A: GPT-4o Mini or Gemini 1.5 Flash — faster and cheaper
• Complex reasoning: GPT-4 Turbo or Claude Opus 3.5 — highest quality

Voice Settings

For voice call scenarios, configure these additional settings:

Voice Selection

Built-in voices (30 options): Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus, Zephyr, Autonoe, Umbriel, Erinome, Laomedeia, Schedar, Achird, Sadachbia, Callirrhoe, Iapetus, Despina, Rasalgethi, Alnilam, Pulcherrima, Vindemiatrix, Sulafat, Sadaltager, Zubenelgenubi, Gacrux, Achernar, Algenib, Algieba, Enceladus

ElevenLabs voices (premium quality): Requires an ElevenLabs integration with API key.

Audio Format

Response Speed & Timing

Eagerness options:

• Eager — Responds as soon as the caller pauses. Best for quick Q&A
• Normal — Balanced timing (default). Good for most scenarios
• Patient — Waits longer for the caller to finish. Best for complex questions

Assistant Organization

Folders

Create folders to group related assistants (e.g., "Support", "Sales", "Internal"). Drag and drop to organize.

Default Assistant

Mark one assistant as default for your company. New integrations use this assistant automatically unless configured otherwise.

Managing Assistants

Listing

GET /api/assistants
X-Access-Token: happ_your_token_here

Updating

PATCH /api/assistants/{assistantId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "name": "Updated Name",
  "promptText": "Updated prompt..."
}

Deleting

DELETE /api/assistants/{assistantId}
X-Access-Token: happ_your_token_here

Best Practices

1. Start simple — Begin with a basic prompt and refine based on real conversations
2. Add knowledge — Upload documents to improve accuracy (learn more)
3. Use tools — Connect APIs for real actions (learn more)
4. Set up handoff — Configure when the AI should transfer to a human (learn more)
5. Monitor chats — Review conversations to identify areas for improvement
6. Iterate — Adjust prompts, knowledge, and tools based on conversation patterns