# Account Management Sign in, manage the operator profile, and invite your client's team to one workspace > Full REST + WebSocket API reference: https://api.happ.tools/reference Set up the login your client's team uses to run their assistants, and add teammates so multiple operators share one inbox. ## Register and sign in [#register-and-sign-in] 1. Go to [my.happ.tools](https://my.happ.tools) → **Sign Up**. 2. Pick a method (table below) and complete verification. 3. Sign back in anytime at [my.happ.tools](https://my.happ.tools) with the same method. Forgot the password? **Forgot Password** → enter email → follow the reset link. | Method | How it verifies | | ---------------- | -------------------------------------------------------------- | | Email & Password | Verification link sent to inbox | | Phone | Code via SMS or Telegram | | Google | OAuth — account created from Google profile | | Telegram | Telegram authorization — account created from Telegram profile | Sessions use JWT; tokens refresh automatically. ## Profile and team [#profile-and-team] Profile settings (user menu, top-right): **Name**, **Email**, **Language**, **Notifications**. Invite teammates: **Settings → Team → Invite Member** → enter email. They get a join link. Members can manage chats, assistants, integrations, and analytics. Belong to multiple companies? Click the company name in the sidebar to switch — all data is isolated per company. See [Companies & Workspaces](/docs/companies). **API:** [api.happ.tools/reference](https://api.happ.tools/reference) Generate an access token in account settings and send it as `X-Access-Token: happ_your_token_here`. ## Next [#next] * [Companies & Workspaces](/docs/companies) — isolate each client in its own workspace * [Billing & Plans](/docs/billing) — pick a tariff per company --- # For AI Agents Use Happ from Claude Code, Cursor, ChatGPT, and other AI tools — MCP server, llms.txt, OpenAPI > Full REST + WebSocket API reference: https://api.happ.tools/reference Everything on this site is machine-readable. Point your AI tool at it instead of reading manually. ## MCP server [#mcp-server] The [`@happ-ai/platform-mcp`](https://www.npmjs.com/package/@happ-ai/platform-mcp) server exposes the Happ platform as tools: manage companies, assistants, channels, chats, knowledge, and more — straight from your AI assistant. ### Claude Code [#claude-code] ```bash claude mcp add happ -- npx -y @happ-ai/platform-mcp ``` ### Cursor / Windsurf / any MCP client [#cursor--windsurf--any-mcp-client] ```json { "mcpServers": { "happ": { "command": "npx", "args": ["-y", "@happ-ai/platform-mcp"] } } } ``` ### OpenAI Agents SDK [#openai-agents-sdk] ```python from agents.mcp import MCPServerStdio happ = MCPServerStdio(params={ "command": "npx", "args": ["-y", "@happ-ai/platform-mcp"], }) ``` Then log in with the `happ_login` tool, or provide an access token from [my.happ.tools](https://my.happ.tools). ## Docs as Markdown [#docs-as-markdown] | What | URL | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Index of all pages | [/llms.txt](https://docs.happ.tools/llms.txt) | | All docs in one file | [/llms-full.txt](https://docs.happ.tools/llms-full.txt) | | Any page as Markdown | prefix path with `/llms.mdx`, append `.md` — e.g. [/llms.mdx/en/docs/quickstart.md](https://docs.happ.tools/llms.mdx/en/docs/quickstart.md) | Every docs page also has **Copy Markdown**, **Open in Claude**, and **Open in ChatGPT** buttons. ## API for code generation [#api-for-code-generation] | What | URL | | -------------------- | -------------------------------------------------------------------------- | | OpenAPI 3.0 spec | [api.happ.tools/api/swagger-json](https://api.happ.tools/api/swagger-json) | | API reference (docs) | [/en/api](/api) | | Interactive client | [api.happ.tools/reference](https://api.happ.tools/reference) | Feed the OpenAPI spec to your tool and ask it to generate the integration: ```text Read https://api.happ.tools/api/swagger-json and write a client that creates an assistant, uploads knowledge, and connects a Telegram bot. Authenticate with the X-Access-Token header. ``` --- # AI Control & Human Handoff Control when the AI answers and when a human operator takes over the chat > Full REST + WebSocket API reference: https://api.happ.tools/reference Every chat has an **AI control** toggle so your client's team can let the assistant run on autopilot or step in manually whenever they need to. The screenshot shows a conversation right after the AI invoked `turnOffAiMode`: the **AI** switch in the chat header is off, a banner reminds the operator they're replying manually, and the last message comes from a teammate. ## Toggle AI mode [#toggle-ai-mode] 1. Open any chat in **Chats** (dashboard or mobile app) and click the **AI toggle** — it switches immediately. 2. Or via API: `PATCH /api/chats/{chatId}` with `{ "isUnderAiControl": false }` (header `X-Access-Token: happ_your_token_here`). | State | Behavior | | -------------------------------------- | ------------------------------------------------------------ | | **AI On** (`isUnderAiControl: true`) | Assistant automatically responds to new messages | | **AI Off** (`isUnderAiControl: false`) | Assistant pauses; messages wait in the dashboard for a human | When AI is off, `aiDisableReason` records why: | Reason | Description | | -------- | --------------------------------------------- | | `manual` | A human disabled AI from the dashboard or API | | `auto` | The AI triggered `turnOffAiMode` to hand off | ## Human handoff [#human-handoff] The built-in `turnOffAiMode` tool is always available. When the AI decides it can't help, it calls the tool, `isUnderAiControl` is set to `false`, the chat surfaces in the dashboard as needing attention, and a `CHAT_MODE_CHANGED` WebSocket event notifies all clients. Wire up [Telegram Push Notifications](/docs/integrations/notifications) so the team's group is pinged on every handoff. Guide it from the assistant prompt: ``` If the customer asks to speak to a human, or if you cannot resolve their issue after 2 attempts, use the turnOffAiMode tool to transfer the conversation to a human operator. Tell the customer that a team member will respond shortly. ``` ## Auto-resume and context window [#auto-resume-and-context-window] * After an **auto** handoff, AI re-enables after \~**10 minutes of inactivity**. A sweep finds messages older than 10 minutes, moves them to a context archive (assigns a `contextId`), and if `aiDisableReason` was `auto`, re-enables AI with a fresh context. **Manual** disables never auto-resume — a human must re-enable. * The same 10-minute window bounds context: the AI only sees the last \~10 minutes of messages. Older ones stay in the DB but aren't sent to the model, so returning customers are treated as a fresh conversation. ## Transfer between assistants [#transfer-between-assistants] `PATCH /api/chats/{chatId}` with `{ "assistantId": "new-assistant-uuid" }`. The new assistant continues from the latest message; all history is preserved. ## Message debouncing [#message-debouncing] Rapid bursts are batched: **4-second debounce** after each message, **7-second maximum** before processing. Only the last message in a burst triggers a response, so the assistant sees the full thought. ## WebSocket events [#websocket-events] ```json { "type": "CHAT_MODE_CHANGED", "payload": { "chatId": "uuid", "isUnderAiControl": false, "aiDisableReason": "auto" } } ``` Connect to `wss://api.happ.tools/ws` for real-time updates. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Tools & webhook actions](/docs/tools) — how `turnOffAiMode` fits with other tools * [Channels](/docs/channels) — where handoffs happen across messengers * [Assistants](/docs/assistants) — configure who answers before handoff --- # Analytics & Metrics Track assistant performance, conversation volume, and token spend at a glance > Full REST + WebSocket API reference: https://api.happ.tools/reference See how your client's AI is performing — conversation volume, channel mix, and token spend — from the Analytics dashboard in the [Happ dashboard](https://my.happ.tools). ## What you monitor here [#what-you-monitor-here] * **Dashboard KPIs** — Total Conversations, Active Conversations, Messages Sent, Channel Distribution, Token Usage (current billing period). * **Per channel** — conversations and message volume over time across Telegram, Instagram, WhatsApp, Facebook, Viber. * **Token & usage** — usage against plan limit, per-message input/output tokens and model used (in the [Conversation View](/docs/chats#conversation-view)), and which integrations are active. Billing detail in [Billing & Plans > Token Usage](/docs/billing#token-usage). * **Voice** ([voice assistant](/docs/voice)) — call volume and duration, recordings and transcriptions, keyword analysis (higher plans). ## Optimization tips [#optimization-tips] | Action | Why | | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | Review conversations in the [Chat Dashboard](/docs/chats) | Spot where the assistant struggles | | Watch token usage | Switch to GPT-4o Mini / Gemini Flash or trim prompts before hitting the limit | | Focus high-volume channels | Invest where customers actually are | | Fill knowledge gaps via [Knowledge Base](/docs/knowledge) | Cover questions the AI can't answer | | Review tool call patterns | Ensure tools trigger correctly | **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Chats](/docs/chats) — the conversations behind these metrics * [Knowledge](/docs/knowledge) — close the gaps analytics surfaces * [Billing & Plans](/docs/billing) — token usage and limits --- # API Reference REST + WebSocket API for assistants, chats, knowledge, tools, phones, and webhooks > Full REST + WebSocket API reference: https://api.happ.tools/reference Happ exposes a REST + WebSocket API for managing assistants, sending messages, controlling AI mode, and integrating Happ into your workflows. The full, testable reference lives in Scalar — it is the source of truth for every endpoint, schema, and example. **[api.happ.tools/reference](https://api.happ.tools/reference)** ## Resource groups [#resource-groups] * **Assistants** — `GET/POST /api/assistants`, `PATCH /api/assistants/{id}` * **Chats** — list/create chats, send and list messages, toggle AI control (`PATCH /api/chats/{id}` `isUnderAiControl`) * **Knowledge Base** — `/api/assistant-knowledge` * **Tools** — `/api/assistant-tools` * **Phones** — `/api/phones`, link to an assistant ## Authentication [#authentication] All requests require an **Access Token** generated in account settings at [my.happ.tools](https://my.happ.tools). Send it in the header: ``` X-Access-Token: happ_your_token_here ``` Base URL (production): `https://api.happ.tools`. ## WebSocket [#websocket] Connect over Socket.IO at `wss://api.happ.tools/ws`: authenticate with your token, join your company room, then receive `MESSAGE_CREATED`, `CHAT_MODE_CHANGED`, and `CHAT_CREATED` events. See [Chats > Real-Time Updates](/docs/chats#real-time-updates). ## Use with AI [#use-with-ai] Integrating with an AI assistant (Claude, Cursor, Copilot)? Hand it our machine-readable sources instead of copy-pasting docs: * **OpenAPI spec** — `https://api.happ.tools/api/swagger-json` (every endpoint, schema, and auth rule) * **Docs index** — `https://docs.happ.tools/llms.txt` Starter prompt: ```text You are integrating with the Happ Platform API. Spec: https://api.happ.tools/api/swagger-json Docs: https://docs.happ.tools/llms.txt Auth: send the header X-Access-Token: happ_... Task: ``` ## Next [#next] * [Chats](/docs/chats) — the inbox these endpoints drive * [Webhooks](/docs/integrations/webhooks) — push events to your server --- # AI Assistants Configure the AI agent that answers your client's customers across every channel > Full REST + WebSocket API reference: https://api.happ.tools/reference Spin up an AI agent that handles your client's customer conversations across Telegram, Instagram, WhatsApp, and voice calls — run as many as you need for different purposes. ## Configure an assistant [#configure-an-assistant] 1. **Name** — internal label, visible only to your team. 2. **Language** — primary response language; the AI still reads incoming messages in any language. 3. **Voice** — phone calls only. ElevenLabs voices need an [ElevenLabs integration](/docs/voice/providers#elevenlabs-premium-voices). 4. **LLM model** — OpenAI / Anthropic / Gemini / Groq. Defaults to GPT-4o Mini; switch to GPT-4o or Claude Sonnet 4.5 for harder tasks. 5. **First message** + **Prompt** — the opening greeting, then system instructions for role, tone, and rules. Be specific, set boundaries, and tell it to hand off to humans via `turnOffAiMode` when needed. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Knowledge base](/docs/knowledge) — feed it your PDFs, FAQs, or website * [Tools & webhook actions](/docs/tools) — let it call your APIs (CRM, booking, returns) * [AI control](/docs/ai-control) — when and how it hands off to a human --- # Billing & Plans Pick a tariff per client by conversation volume, set the cycle, and track token usage > Full REST + WebSocket API reference: https://api.happ.tools/reference Match each client's plan to the conversation volume they handle, pick a billing cycle for the discount, and top up tokens as usage grows. The billing page lives under the account menu (top-right): active tariff chip in the header, period selector, all plans side-by-side, and payment history at the bottom. ## Pick a plan and cycle [#pick-a-plan-and-cycle] 1. Open **Account menu → Billing**. 2. Choose the billing cycle in the header — it recalculates every card's monthly price live (strike-through + `−%` badge). 3. Click the tariff card you want. 4. Confirm the new price in the header — payment is processed instantly. Upgrades take effect immediately; downgrades at the end of the current period. Cancel from the header — access continues until period end, no early-termination fee. | Plan | Price / month | Includes | Best for | | ------------ | ------------- | --------------------------------------------------------------- | ---------------------------- | | **Starter** | $29 | 1 assistant, 2 channels, light usage | Pilots, proof-of-concept | | **Pro** | $79 | 5 assistants, all messengers + voice, unlimited knowledge base | Growing businesses (default) | | **Business** | $199 | Unlimited assistants, deep analytics, dedicated account manager | Multi-department deployments | | Cycle | Discount | When it makes sense | | ------------- | -------- | -------------------------------------------- | | **Monthly** | — | You're still evaluating | | **Quarterly** | −10% | Stable usage, predictable headcount | | **Yearly** | −20% | Long-term commitment, lowest per-month price | | Status | Meaning | | ------------- | ------------------------------------ | | **Active** | Subscription is live and functional | | **Pending** | Payment being processed | | **Inactive** | Paused (e.g., payment failed) | | **Cancelled** | Terminated — access until period end | ## Token usage [#token-usage] Tokens are AI usage credits, deducted per chat session at **0.2 credits per interaction** (tracked separately from raw LLM tokens). Consumption scales with conversation length, AI model (GPT-4 / Claude Opus cost more), knowledge-base vector search, and tool-call rounds. Track it in **Billing → Tokens**: current balance, usage over time, and a per-message breakdown (input/output tokens, model used). Running low? Upgrade the plan, switch to efficient models (GPT-4o Mini, Gemini Flash), shorten prompts, or trim the knowledge base. ## Payments [#payments] Every charge lands in the **Payment history** table: date, status (succeeded, pending, rejected, refunded), amount, and one-click invoice download for accounting. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Analytics & Metrics](/docs/analytics) — monitor token usage and conversation volumes * [Assistants → AI Model Configuration](/docs/assistants#ai-model-configuration) — choose models by cost/quality * [Companies & Workspaces](/docs/companies) — billing is per company --- # Channels Connect your client's messengers — Telegram, Instagram, WhatsApp, Facebook, Viber — to one AI assistant > Full REST + WebSocket API reference: https://api.happ.tools/reference Your client's customers message wherever they like — Telegram, Instagram, WhatsApp, Facebook, Viber. Connect each as a **channel** and one assistant answers them all in a single inbox. ## Connect a channel [#connect-a-channel] 1. **Integrations** → pick the messenger → **Connect**. 2. Authenticate in the modal (method differs per channel — see table below). 3. Assign the AI assistant that should handle it. Multiple accounts of one type are fine — assign a different assistant to each ([three-tier model](/docs/integrations#three-tier-integration-model)). Switch the assistant or disable a channel anytime from its card in **Integrations**; disabling cleans up its chats. ## Supported messengers [#supported-messengers] | Channel | Auth method | Setup | | --------------------------------------------- | --------------- | ------ | | [Telegram](/docs/channels/telegram) | Phone + MTProto | Easy | | [Instagram](/docs/channels/instagram) | Meta OAuth 2.0 | Medium | | [WhatsApp](/docs/channels/whatsapp) | WaSender API | Medium | | [Facebook Messenger](/docs/channels/facebook) | Meta OAuth 2.0 | Medium | | [Viber](/docs/channels/viber) | E-Chat platform | Medium | ## Capabilities [#capabilities] | Feature | Telegram | Instagram | WhatsApp | Facebook | Viber | | -------------- | -------- | --------- | -------- | -------- | ------- | | Text / images | Yes | Yes | Yes | Yes | Yes | | Voice messages | Yes | Yes | Yes | Yes | Limited | | Group chats | Yes | No | No | No | No | | Stickers | Yes | No | No | No | Yes | Inbound message → Happ saves it → the assigned assistant replies (4s debounce) → the reply goes back out the same channel. The dashboard updates live over WebSocket and fires your [webhook](/docs/integrations/webhooks) if configured. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Assistants](/docs/assistants) — configure who answers * [AI control](/docs/ai-control) — when AI hands off to a human * [Voice](/docs/voice) — add phone calls --- # Chats One inbox for every channel — let operators watch the AI and take over when needed > Full REST + WebSocket API reference: https://api.happ.tools/reference Every conversation across Telegram, Instagram, WhatsApp, Facebook, Viber, and voice calls lands in one inbox where the operator can watch the AI work and step in at any time. ## What the operator does here [#what-the-operator-does-here] * **AI on/off per chat** — flip the toggle to take over; the AI stops replying until you turn it back on. * **Reply by hand** — the composer sends out through the same channel the customer is on. * **Read the full history** — every message, role, timestamp, and token cost is preserved past the AI's context window. * **Filter by channel or AI status** — to stay sane once the inbox has hundreds of open conversations. * **Live updates** — `MESSAGE_CREATED`, `CHAT_MODE_CHANGED`, and `CHAT_CREATED` stream over WebSocket and reorder the list instantly. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [AI control](/docs/ai-control) — when the AI hands off automatically * [Channels](/docs/channels) — connect messengers so chats appear here * [Analytics](/docs/analytics) — aggregate metrics across these conversations --- # Companies & Workspaces Give each client their own isolated workspace for assistants, chats, and billing > Full REST + WebSocket API reference: https://api.happ.tools/reference Run one client per company so their assistants, integrations, chats, knowledge bases, and billing stay fully separate from everyone else's. ## Create a company [#create-a-company] 1. After signing in, click **Create Company** (it's also the first step after registration). 2. Enter the company name. 3. Select the preferred language. 4. Click **Create**. Create as many companies as you have clients. Switch between them with the company selector in the sidebar. ## Settings [#settings] Open **Settings** in the sidebar: | Section | Controls | | --------------- | ---------------------------------------------------------------------------------------------------- | | General | Company Name, Language, Timezone (used for analytics + scheduling) | | Team Management | View members, invite by email, remove members — see [Account → Team](/docs/account#profile-and-team) | | Data & Privacy | Export company data, delete company (irreversible — removes all data) | ## Data isolation [#data-isolation] Everything is scoped to its company and invisible to others: assistants, integrations (Telegram, Instagram, etc.), chats, knowledge bases, per-assistant tools, phone numbers, and [billing](/docs/billing). Each company carries its own plan and usage limits. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Account Management](/docs/account) — invite operators to a workspace * [Billing & Plans](/docs/billing) — per-company plans and limits * [Channels](/docs/channels) — connect each company's messengers --- # FAQ Common questions about AI assistants, channels, billing, voice calls, and integrations on Happ > Full REST + WebSocket API reference: https://api.happ.tools/reference ## General [#general] ### What is Happ? [#what-is-happ] Happ is an AI assistant platform that automates customer communication across messaging channels (Telegram, Instagram, WhatsApp, Facebook, Viber) and voice calls. Your AI assistant responds to customers automatically using the knowledge and instructions you provide. ### Do I need technical skills to use Happ? [#do-i-need-technical-skills-to-use-happ] No. Happ is designed for non-technical users. You can set up an AI assistant, connect channels, and manage conversations entirely through the web dashboard at [my.happ.tools](https://my.happ.tools) — no coding required. The API is available for developers who want to build custom integrations. ### Which AI models can I use? [#which-ai-models-can-i-use] Happ supports multiple providers and models: * **OpenAI** — GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-4, GPT-3.5 Turbo * **Claude (Anthropic)** — Sonnet 4.5, Sonnet 3.7, Sonnet 3.5, Opus 3.5, Opus 3, Sonnet 3, Haiku 3 * **Gemini (Google)** — 2.0 Flash, 1.5 Pro, 1.5 Flash, 1.5 Flash 8B * **Groq** — GPT-OSS 120B (ultra-fast inference) See [Assistants > AI Model Configuration](/docs/assistants#ai-model-configuration) for the full list. ### Can I use multiple AI assistants? [#can-i-use-multiple-ai-assistants] Yes. You can create multiple assistants, each with its own prompt, knowledge base, tools, and AI model. Assign different assistants to different channels or use cases. ## Channels [#channels] ### Which messengers are supported? [#which-messengers-are-supported] Telegram, Instagram, WhatsApp, Facebook Messenger, and Viber. See the [Channels Overview](/docs/channels) for details on each. ### Can one assistant work on multiple channels? [#can-one-assistant-work-on-multiple-channels] Yes. A single assistant can handle conversations on all connected channels simultaneously. Each channel creates separate conversations per customer. ### What happens if I disconnect a channel? [#what-happens-if-i-disconnect-a-channel] Active conversations stop receiving AI responses. Historical conversation data is preserved. You can reconnect the channel at any time. ### Do customers know they're talking to an AI? [#do-customers-know-theyre-talking-to-an-ai] That's up to you. Configure the assistant's prompt to identify itself as AI or present itself as a regular support agent. ## AI & Conversations [#ai--conversations] ### How do I improve my assistant's responses? [#how-do-i-improve-my-assistants-responses] 1. **Refine the prompt** — Add specific instructions, tone guidelines, and examples 2. **Add knowledge** — Upload documents, FAQs, and website content to the [Knowledge Base](/docs/knowledge) 3. **Use a better model** — GPT-4o and Claude Sonnet 4.5 produce higher quality responses 4. **Review conversations** — Check the [Chat Dashboard](/docs/chats) to identify patterns where the assistant struggles ### Can the assistant perform actions (not just chat)? [#can-the-assistant-perform-actions-not-just-chat] Yes. Configure [tools](/docs/tools) to let the assistant call external APIs — make bookings, update CRM records, check availability, look up data, and more. ### What happens when the assistant can't answer? [#what-happens-when-the-assistant-cant-answer] The assistant responds based on its prompt instructions (e.g., "I don't have that information, let me connect you with a team member"). You can configure the `turnOffAiMode` [built-in tool](/docs/tools#built-in-tools) to automatically disable AI and alert your team via [Telegram Push Notifications](/docs/integrations/notifications). ### Can a manager take over a conversation? [#can-a-manager-take-over-a-conversation] Yes. Toggle AI off for any conversation — manually from the dashboard/mobile app, via the `/bot` command in Telegram, or automatically via the `turnOffAiMode` tool. When AI is off, you can respond manually. Set up [Telegram Push Notifications](/docs/integrations/notifications) to alert your team when handoff occurs. See [AI Control & Human Handoff](/docs/ai-control) for full details. ### How fast does the AI respond? [#how-fast-does-the-ai-respond] Typically within a few seconds. Happ uses a 4-second debouncing system — if a customer sends multiple messages in rapid succession, the assistant waits and processes them together. You can tune response behavior with the **eagerness** setting on voice assistants (Eager, Normal, Patient). ### What is the context window? [#what-is-the-context-window] The AI assistant sees only recent messages (approximately the last 10 minutes). Older messages are archived but preserved in the database. This keeps responses focused and token usage efficient. See [AI Control > Context Window](/docs/ai-control#conversation-context-window). ### Does AI automatically turn back on after handoff? [#does-ai-automatically-turn-back-on-after-handoff] Yes. If AI mode is turned off and there's no activity for approximately 10 minutes, AI automatically resumes. This prevents conversations from being left in manual mode indefinitely. ## Voice [#voice] ### How does the voice assistant work? [#how-does-the-voice-assistant-work] The voice assistant answers phone calls using AI. It converts speech to text (STT), generates a response using your configured AI model, and converts it back to speech (TTS) — all in real-time. It can also execute tools during calls. See [Voice Assistant](/docs/voice). ### Which telephony providers are supported? [#which-telephony-providers-are-supported] Binotel, Ringostat, Phonet, and Unitalk. Any SIP-compatible provider can potentially be used. See [Telephony Providers](/docs/voice/providers). ### Can I choose the voice? [#can-i-choose-the-voice] Yes. Choose from 30 built-in voices or connect [ElevenLabs](/docs/voice/providers#elevenlabs-premium-voices) for premium natural-sounding voices with multiple languages and accents. ## Billing [#billing] ### What plans are available? [#what-plans-are-available] Happ offers separate plans for text and voice: **Text plans** (messenger assistants): Creative ($200/mo), Pro ($500/mo), Pro Plus ($1,000/mo) **Voice plans** (phone call assistants): Mini ($100/mo), Base ($250/mo), Pro ($500/mo) See [Billing & Plans](/docs/billing) for full details. ### How are tokens counted? [#how-are-tokens-counted] Tokens are consumed when the AI processes and generates text. Longer conversations, more capable models, knowledge base searches, and tool calls all consume tokens. Monitor usage in **Settings** > **Billing**. ### What happens when I run out of tokens? [#what-happens-when-i-run-out-of-tokens] Your assistants may stop responding until tokens are replenished (at your next billing cycle or by upgrading your plan). ### Can I change my plan? [#can-i-change-my-plan] Yes. Upgrade at any time for immediate access. Downgrades or cancellations take effect at the end of your billing period. ## Data & Security [#data--security] ### Is my data secure? [#is-my-data-secure] Yes. Happ uses industry-standard security practices: * JWT-based authentication with access tokens * HTTPS encryption for all data in transit * Data isolation between companies * HMAC-SHA256 webhook request signing ### Can I delete my data? [#can-i-delete-my-data] Yes. You can delete individual conversations, knowledge entries, or your entire company workspace. Data deletion is permanent. ### Where is data stored? [#where-is-data-stored] Conversation data is stored in PostgreSQL databases. Files are stored in secure cloud storage. Vector embeddings for the knowledge base are stored in Qdrant. ## Support [#support] ### How do I get help? [#how-do-i-get-help] * Check this documentation for guides and answers * Visit the [API Reference](https://api.happ.tools/reference) for endpoint details * Contact support through the platform dashboard at [my.happ.tools](https://my.happ.tools) --- # Welcome to Happ Multi-channel AI assistant platform — chat and voice assistants for businesses > Full REST + WebSocket API reference: https://api.happ.tools/reference ## Products [#products] Pick an area to view its documentation and start integrating. Create AI assistants — model, prompt, behavior, and voice. Connect Telegram, Instagram, WhatsApp, Facebook, Viber, and the web widget. AI voice agents on real phone numbers with 30+ voices. Give assistants your documents, sites, and FAQs via RAG. Real actions from conversations — bookings, lookups, CRM updates. Conversations, response quality, token spend, channel performance. ## For developers [#for-developers] REST + WebSocket API with an OpenAPI spec and interactive playground. Use these docs from Claude Code, Cursor, or ChatGPT — MCP and llms.txt. Unified inbox with AI toggle and human handoff. --- # Integrations Wire a client's AI providers, CRM, webhooks, and notifications into Happ from one catalog > Full REST + WebSocket API reference: https://api.happ.tools/reference Everything a client connects to Happ — AI providers, CRM, webhooks, notifications, telephony — lives in one **Integrations** catalog. Connect it, assign an assistant, done. ## Connect [#connect] 1. **Integrations** in the sidebar → **Add Integration**. 2. Pick the integration type. 3. Enter credentials in the modal (API keys, tokens, URLs). 4. Assign an assistant (channel-type integrations only) → **Connect**. Click an active integration to **Edit**; delete one to disconnect it and stop all data flow (channel integrations also clean up their chats). List them via `GET /api/company-integrations` with header `X-Access-Token`. ## Three-tier integration model [#three-tier-integration-model] 1. **Integration** — master type definition (e.g. "Telegram", "Binotel"). 2. **Company Integration** — your client's connection with its credentials. 3. **Assistant Integration** — which assistant handles that connection. So you can connect multiple accounts of one type and assign a different assistant to each. ## AI providers [#ai-providers] API key per provider, added via **Add Integration**. See [Assistants > AI Model Configuration](/docs/assistants#ai-model-configuration). | Provider | Popular models | | ------------------ | ------------------------------------------------------ | | OpenAI | GPT-4o, GPT-4o Mini, GPT-4 Turbo, GPT-4, GPT-3.5 Turbo | | Claude (Anthropic) | Sonnet 4.5, Sonnet 3.7, Opus 3.5, Haiku 3 | | Gemini (Google) | 2.0 Flash, 1.5 Pro, 1.5 Flash, 1.5 Flash 8B | | Groq | GPT-OSS 120B (ultra-fast inference) | ## CRM systems [#crm-systems] Sync conversations, contacts, and orders. KeyCRM, NetHunt, Odoo, SalesDrive, Bookon, SmartCRM, Altegio. See [CRM](/docs/integrations/crm) for per-system credential fields. ## Webhooks [#webhooks] Receive real-time chat and call events on your own endpoint. See [Webhooks](/docs/integrations/webhooks). ## Notifications [#notifications] Alert the team when a conversation needs a human — Telegram push or Google Spreadsheets. See [Notifications](/docs/integrations/notifications). ## Other [#other] * **Telephony** — Binotel, Ringostat, Phonet, Unitalk for the voice assistant. See [Telephony Providers](/docs/voice/providers). * **Voice** — ElevenLabs premium text-to-speech. * **Vector DB** — Qdrant powers the [Knowledge Base](/docs/knowledge) (OpenAI `text-embedding-3-large` embeddings + Qdrant retrieval). Keep API keys private, use separate keys for Happ, and rotate them periodically. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — connect messengers * [CRM](/docs/integrations/crm) — sync your sales pipeline * [Webhooks](/docs/integrations/webhooks) — build custom integrations --- # Knowledge base Ground the assistant's answers in your client's business instead of the model's guesses > Full REST + WebSocket API reference: https://api.happ.tools/reference Attach files and URLs so the assistant answers from your client's real content — we extract, chunk, embed, and retrieve only what's relevant per question. ## Add sources [#add-sources] 1. Open the **Knowledge** tab inside an assistant. 2. **Files** — PDF, DOCX, TXT, CSV, Markdown. PDF / DOCX up to 50 MB, TXT up to 10 MB. 3. **URLs** — crawled on add, re-fetched on a schedule. 4. **Plain text** — paste an FAQ, policy, or opening hours. ## How it's used [#how-its-used] * Every reply runs vector search over the knowledge base; only the top chunks enter the LLM context (top-3, dynamic score threshold). * Short items (hours, policies) can be marked non-vector — inlined into the system prompt so the AI always sees them. * Embeddings use `text-embedding-3-large`, stored in Qdrant. The assistant calls the built-in `searchKnowledge` tool on demand. * System-managed entries (e.g. allergens, compliance text) are read-only and kept in sync centrally. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Tools & webhook actions](/docs/tools) — give it real actions, not just info * [AI control](/docs/ai-control) — when the AI hands off to a human * [Channels](/docs/channels) — wire it to Telegram, Instagram, WhatsApp, voice --- # Mobile App Manage your AI assistants and chats on the go with the Happ mobile app > Full REST + WebSocket API reference: https://api.happ.tools/reference ## Overview [#overview] The Happ mobile app lets you manage your AI assistants, monitor conversations, and respond to customers from your phone. Available for both iOS and Android. ## Getting the App [#getting-the-app] * **iOS**: Download from the App Store * **Android**: Download from Google Play ## Signing In [#signing-in] Use the same credentials as your web dashboard at [my.happ.tools](https://my.happ.tools): * Email & password * Google account * Telegram authentication ## Features [#features] ### Chat Dashboard [#chat-dashboard] View and manage all conversations from your phone: * See all active chats across channels (Telegram, Instagram, WhatsApp, Facebook, Viber) * Real-time message updates via WebSocket * Channel-specific color-coded badges for quick identification * Toggle AI control on/off for specific conversations ### Conversation View [#conversation-view] Open any chat to see the full conversation: * Complete message history * Send manual replies when AI is off * View media and attachments ### AI Control [#ai-control] Quickly take over conversations from your phone: * Toggle AI on/off per conversation (see [AI Control](/docs/ai-control)) * AI auto-resumes after \~10 minutes of inactivity if turned off * Send manual messages when AI is disabled ### Assistant Management [#assistant-management] Create and configure AI assistants: * View all assistants * Edit assistant settings (name, prompt, model) * Assign assistants to integrations ### Integration Management [#integration-management] Monitor your connected channels: * View active integrations and their status * Check connection status ### Company Switching [#company-switching] If you manage multiple companies: * Switch between companies from the settings tab * Each company's data is separate and isolated ### Phone Numbers [#phone-numbers] Manage voice assistant phone numbers: * View connected phone numbers * Monitor call activity ## Push Notifications [#push-notifications] The app sends push notifications for: * New incoming messages * AI handoff events (when the assistant disables AI mode) * Important system alerts Configure notification preferences in **Settings** > **Notifications**. ## Tips [#tips] * **Enable notifications** — Stay on top of customer conversations when you're away from the dashboard * **Quick AI toggle** — Use the AI control toggle to quickly take over a conversation from your phone * **Combine with Telegram alerts** — Set up [Telegram Push Notifications](/docs/integrations/notifications) for additional alerting to your team group --- # Quickstart Set up a client from zero to a live AI assistant across chat + voice > Full REST + WebSocket API reference: https://api.happ.tools/reference Your client wants their customers handled automatically — across messengers and over the phone. Here's the end-to-end path. ## The path [#the-path] 1. Create the client's company (workspace, language) → [Companies](/docs/companies) 2. Build an assistant — pick model, write the prompt and first message → [Assistants](/docs/assistants) 3. Give it knowledge — menu, policies, FAQ, files, URLs → [Knowledge](/docs/knowledge) 4. Add tools and webhooks for real actions — bookings, lookups, CRM → [Tools](/docs/tools) 5. Connect chat channels — Telegram, Instagram, WhatsApp, Facebook, Viber → [Channels](/docs/channels) 6. Add voice — telephony provider plus phone numbers → [Voice](/docs/voice) 7. Go live and monitor — watch the [Chats](/docs/chats) inbox, read [Analytics](/docs/analytics), toggle [AI control](/docs/ai-control) for handoff ## Chat vs voice [#chat-vs-voice] One assistant serves both surfaces — same model, prompt, knowledge, and tools. **Channels** are messengers (text + voice messages); **Voice** is a telephony provider with assigned phone numbers for live calls. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Integrations](/docs/integrations) — the three-tier model behind every connection * [Account](/docs/account) — team members, roles, settings --- # Tools & webhook actions Let the assistant act on your client's systems — book, look up, hand off — not just talk > Full REST + WebSocket API reference: https://api.happ.tools/reference Tools turn the assistant into something that *does* things: each is a function the AI can call mid-conversation — your webhook, or one Happ ships with. ## Add a tool [#add-a-tool] 1. Open the **Tools** tab inside an assistant. 2. **Webhook** — HTTP request to your API. Define name, description, params schema, URL, method, and a shared secret. Examples: `create_reservation` (POST), `lookup_customer` (GET). 3. **Built-in** — no setup. `knowledge_search` runs vector search over the attached knowledge base; `turn_off_ai_mode` hands the conversation to a human operator with full context. 4. Write descriptions that explain *when* to call, not just what the tool does — the AI sees name, description, and param schema in its prompt. 5. Hit **Check** on any tool to fire a test call and inspect the response. The AI fills required params from context (asking the customer first if info is missing) and tool calls are recursive — results feed the next turn, so it can chain multiple tools in one reply. ## Example webhook call [#example-webhook-call] POST to your endpoint with collected params plus `chatId`: ```json { "table_id": "T-12", "time": "2026-05-18T19:30:00Z", "guests": 4, "phone": "+380501234567", "chatId": "chat-uuid" } ``` Return short JSON the AI can paraphrase: ```json { "result": "Booking confirmed. Confirmation number #12345." } ``` Requests are signed with HMAC-SHA256 — verify the `X-Webhook-Signature` header before processing. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Knowledge base](/docs/knowledge) — let it look up information before acting * [AI control](/docs/ai-control) — how `turn_off_ai_mode` hands off, and when AI re-enables * [Channels](/docs/channels) — where tool calls happen: Telegram, Instagram, WhatsApp, voice --- # Voice Assistant Answer the client's phone line with an AI voice agent — bookings, lookups, handoff > Full REST + WebSocket API reference: https://api.happ.tools/reference Connect a SIP phone number and an AI voice agent answers the client's calls — greeting, natural conversation, tools, and human handoff. ## Connect voice [#connect-voice] 1. [Set up a phone number](/docs/voice/setup) with SIP credentials (login, password, telephony URL). 2. Connect a [telephony provider](/docs/voice/providers) integration (Binotel, Ringostat, Phonet, Unitalk). 3. Assign an assistant configured for voice; optionally add [ElevenLabs](/docs/voice/providers#elevenlabs-premium-voices) for premium voices. 4. Call the number to test. The agent can run [webhook tools](/docs/tools) mid-call (bookings, lookups, CRM), trigger `webhook_postcall` follow-ups, and transfer to a human via the built-in `turnOffAiMode` tool. Calls are recorded and transcribed when the provider supports it. ## Settings [#settings] | Setting | Behavior | | ---------------------- | ------------------------------------------ | | Eagerness: Eager | Responds quickly, best for simple Q\&A | | Eagerness: Normal | Balanced timing (default) | | Eagerness: Patient | Waits longer, best for complex questions | | Voice | 30 built-in voices, or ElevenLabs premium | | Codec: A-law (default) | Standard international telephony, 8000 Hz | | Codec: μ-law | Standard North American telephony, 8000 Hz | **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Set up a phone number](/docs/voice/setup) — SIP credentials * [Telephony providers](/docs/voice/providers) — Binotel, Ringostat, Phonet, Unitalk, ElevenLabs * [Configure tools](/docs/tools) — actions during calls --- # Facebook Messenger Connect a client's Facebook Page so its AI assistant handles Messenger chats > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting Facebook Messenger lets your client's AI assistant answer everyone who messages their Facebook Page — Happ authorizes through the **Meta OAuth 2.0** flow. ## Connect [#connect] 1. Ensure the client has a **Facebook Page** and admin access to it. 2. **Integrations** > **Add Integration** > **Facebook Messenger**. 3. Authorize on Meta via OAuth 2.0 and grant messaging permissions. 4. Select the Facebook Page. 5. Assign an AI assistant and activate. Meta access tokens refresh automatically. Text, images, attachments, and voice are supported; conversations appear in the [Chat Dashboard](/docs/chats). **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers * [AI control](/docs/ai-control) — toggling AI per conversation --- # Instagram Connect a client's Instagram business account so its AI assistant handles DMs > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting Instagram lets your client's AI assistant answer Direct Messages on their business account — Happ authorizes through the **Meta OAuth 2.0** flow. ## Connect [#connect] 1. Ensure the client has an **Instagram Business/Creator** account linked to a **Facebook Page** (required by Meta). 2. **Integrations** > **Add Integration** > **Instagram**. 3. Authorize on Meta via OAuth 2.0 and grant read/send-message permissions. 4. Select the Instagram account. 5. Assign an AI assistant and activate. Meta access tokens refresh automatically — no manual re-auth. Images arrive as `[User sent a photo]` in AI context; voice is supported. Instagram has no group conversations and limited sticker/story support. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers * [AI control](/docs/ai-control) — toggling AI per conversation --- # Telegram Connect a client's Telegram account so one AI assistant handles its DMs and groups > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting Telegram lets your client's AI assistant answer Telegram DMs and group mentions on a real user account — Happ links via **MTProto** (GramJS) with a persistent session, not a webhook bot. ## Connect [#connect] 1. **Integrations** > **Add Integration** > **Telegram**. 2. Enter the phone number of the Telegram account. 3. Authenticate — verification code or QR scan (`TELEGRAM_QR_CODE_UPDATED` → scan → `TELEGRAM_QR_AUTH_COMPLETED`). 4. If 2FA is on, enter the password when prompted (`TELEGRAM_QR_AUTH_NEEDS_2FA`). 5. Assign an AI assistant and **Connect**. ## Fields [#fields] | Field | Value | | ------------ | ---------------------------------------------------------- | | Phone | Number tied to the Telegram account | | Auth | Verification code, or QR scan from Telegram desktop/mobile | | 2FA password | Required only if the account has 2FA enabled | Non-text messages (photos, voice, files, stickers) reach the assistant as placeholders like `[User sent a photo]`. Separately, [Telegram Push Notifications](/docs/integrations/notifications) can alert your team on handoff. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers --- # Viber Connect a client's Viber bot via E-Chat so its AI assistant handles messages > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting Viber lets your client's AI assistant answer customers messaging their Viber bot — Happ relays through the **E-Chat** platform. ## Connect [#connect] 1. Create an [E-Chat](https://e-chat.co) account and link the client's Viber business account to it. 2. **Integrations** > **Add Integration** > **Viber (E-Chat)**. 3. Enter the E-Chat API credentials. 4. Assign an AI assistant and activate. ## Fields [#fields] | Field | Value | | ------------------ | ------------------------------------------- | | E-Chat credentials | API credentials from the E-Chat dashboard | | Viber account | Viber business account configured in E-Chat | Text, images, and stickers are supported; voice support is limited and there are no group chats. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers * [AI control](/docs/ai-control) — toggling AI per conversation --- # WhatsApp Connect a client's WhatsApp number via WaSender so its AI assistant handles messages > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting WhatsApp lets your client's AI assistant answer customer messages on their WhatsApp number — Happ relays through the **WaSender** platform. ## Connect [#connect] 1. Create a [WaSender](https://wasender.io) account and link the client's WhatsApp number to it. 2. **Integrations** > **Add Integration** > **WhatsApp (WaSender)**. 3. Enter the WaSender API credentials. 4. Assign an AI assistant and activate. ## Fields [#fields] | Field | Value | | -------------------- | ----------------------------------------------- | | WaSender credentials | API key/credentials from the WaSender dashboard | | WhatsApp number | Dedicated number connected in WaSender | Images arrive as `[User sent a photo]` in AI context; voice is supported. No group chats through the integration, and WhatsApp messaging rate limits apply. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers * [AI control](/docs/ai-control) — toggling AI per conversation --- # Web Widget Embed an AI chat widget on a client's website, connected from the Integrations catalog > Full REST + WebSocket API reference: https://api.happ.tools/reference Connecting the Web Widget puts an AI chat bubble on your client's site so visitors talk to the assistant without leaving the page — created and managed from the **Integrations** catalog via a modal, like every other channel. ## Connect [#connect] 1. **Integrations** > find **Web widget** > **Connect**. 2. In the modal, fill in: * **Name** — a label to recognize this widget. * **Description** (optional) — where it runs. * **Allowed origins** — domains permitted to load the widget, added as chips (e.g. `verona.io`). Use `*` for any origin. 3. Save to create the widget. 4. Reopen it from **My integrations** > **Edit** (or **Copy embed**) to grab the **Embed snippet**, and paste it before `` on every page where the widget should appear. ## Fields [#fields] | Field | Value | | --------------- | ------------------------------------------------------------------- | | Name | Label for the widget | | Description | Optional note about where it runs | | Allowed origins | Domains allowed to load it; `*` for any. Other origins are rejected | **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Channels](/docs/channels) — all messengers * [Assistants](/docs/assistants) — configure who answers --- # CRM Connect a client's CRM so conversations and contacts stay in sync from one catalog > Full REST + WebSocket API reference: https://api.happ.tools/reference Connect a client's CRM and customer conversations, contacts, and orders stay in sync with their sales pipeline — all from the single **Integrations** catalog, no separate CRM page or field-mapping screen. ## Connect [#connect] 1. Open **Integrations** and find the CRM under **Add a CRM**. 2. Click **Connect** — a modal asks only for that CRM's credentials. 3. Enter them and click **Connect**. The CRM moves to **My integrations** as a read-only card showing its **Account Information** (e.g. API endpoint, connect date). Use the card's kebab menu to **Edit** credentials or **Disconnect**. ## Credential fields [#credential-fields] The modal collects authentication only — fields depend on the CRM. | CRM | Fields the modal asks for | What it's for | | ---------- | ------------------------------------------ | -------------------------------------------- | | KeyCRM | API key | Ukrainian CRM for sales and orders | | NetHunt | Email + API key | Gmail-based CRM for contacts and deals | | Odoo | Instance URL + Database + Login + Password | Open-source ERP/CRM | | SalesDrive | API key + Domain (subdomain only) | Sales management platform | | Bookon | API key | Booking and scheduling | | SmartCRM | API key | CRM for small and medium businesses | | Altegio | API key | CRM for service businesses (salons, clinics) | ## Setup guides [#setup-guides] Step-by-step guides — where to find the keys in each CRM, what the settings do, common errors, and how to disconnect. * [KeyCRM](/docs/integrations/crm/keycrm) * [NetHunt](/docs/integrations/crm/nethunt) * [Odoo](/docs/integrations/crm/odoo) * [SalesDrive](/docs/integrations/crm/salesdrive) **Sitniks** — the integration is in development. [Leave your email](https://happ.tools/integrations/crm/sitniks) and we'll let you know the moment it goes live. ## How sync works [#how-sync-works] CRM integrations pair with assistant [tools](/docs/tools). Webhook-based tools call the CRM's API to look up or create contacts, log interactions, and trigger actions (bookings, deal-stage updates, workflows) mid-conversation. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Tools](/docs/tools) — call the CRM during conversations * [Knowledge](/docs/knowledge) — give the assistant CRM context * [Integrations](/docs/integrations) — the full catalog --- # Notifications Alert a client's team in Telegram or log events to Google Sheets when AI hands off > Full REST + WebSocket API reference: https://api.happ.tools/reference Alert the team the moment a conversation needs a human — push to Telegram or log events to Google Spreadsheets. Both connect from the **Integrations** catalog; there's no separate notifications settings page. ## Telegram push [#telegram-push] Recommended for handoff alerts (see [AI Control & Human Handoff](/docs/ai-control)). 1. **Integrations** → **Connect** on **Telegram push notifications**. 2. The modal shows a **6-digit one-time code** — copy it. 3. Click **Open bot** — opens the Happ Telegram bot with the code prefilled. 4. Send `/start`. The bot verifies the code, the integration activates, and the modal closes itself. No bot token or channel ID — the bot is operated by Happ, and the code links it to your company. The code is single-use; if the modal closes early, reopen the flow for a fresh one. When the AI calls the `turnOffAiMode` tool ([Built-in Tools](/docs/tools#built-in-tools)), AI mode is disabled and the team is instantly alerted in Telegram; a manager picks up in the [dashboard](https://my.happ.tools) or [mobile app](/docs/mobile-app). ## Google Spreadsheets [#google-spreadsheets] Log events to a sheet for tracking, lead capture, call records, and custom reporting. 1. **Integrations** → **Connect** on **Google Spreadsheets**. 2. Enter your **Google account email** in the modal and confirm. 3. Authorize access to that account when prompted. Email only — no toggles or thresholds. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [AI control](/docs/ai-control) — when AI hands off * [Webhooks](/docs/integrations/webhooks) — custom event delivery * [Integrations](/docs/integrations) — the full catalog --- # Webhooks Receive a client's chat and call events on your own endpoint, signed and verifiable > Full REST + WebSocket API reference: https://api.happ.tools/reference Receive real-time chat and call events on your own server — Happ POSTs JSON when something happens, so you can drive Slack alerts, CRM lookups, analytics, or custom workflows. ## Connect [#connect] 1. Open the **Integrations** catalog and click **Connect** on **Chat webhook** or **Call webhook**. 2. In the modal, enter your **Webhook URL** — the HTTPS endpoint that receives events. 3. Optionally set a **Webhook secret** for request verification. 4. Click **Connect**. There's no separate webhooks page, no event-subscription toggles, and no in-app deliveries log — the modal is just URL + optional secret. ## Events sent [#events-sent] | Webhook | Fires on | | ------- | ---------------------------------------------------------------------------------------------- | | Chat | New message from customer, message sent by assistant, conversation started, AI control toggled | | Call | Call started, call ended (duration + metadata), call recording available | ## Verifying requests [#verifying-requests] Each request carries an **HMAC-SHA256 signature** computed from your webhook secret. On your server: extract the signature from the headers, compute HMAC-SHA256 of the raw body with your secret, and process the request only if they match. Same mechanism as assistant [tools](/docs/tools#webhook-security). Use HTTPS only, respond `200` fast (process async), and handle duplicate deliveries idempotently. ## Webhooks vs tool webhooks [#webhooks-vs-tool-webhooks] | | Integration webhooks | Tool webhooks | | --------- | ----------------------------- | ---------------------------------- | | Trigger | Automatic on events | Called by AI during conversation | | Direction | Happ → your server | Happ → your server → response → AI | | Response | HTTP 200 ack | JSON used by the assistant | | Use case | Monitoring, logging, alerting | Dynamic lookups, actions | For webhooks the AI calls mid-conversation, see [Tools](/docs/tools). **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Tools](/docs/tools) — AI-called webhooks * [Notifications](/docs/integrations/notifications) — built-in alerting * [Integrations](/docs/integrations) — the full catalog --- # Telephony Providers SIP providers that supply the client's phone number for voice agents > Full REST + WebSocket API reference: https://api.happ.tools/reference Pick one supported telephony provider for the client's SIP number, then bind it in Happ. ## Connect a provider [#connect-a-provider] 1. Create an account with the provider and get SIP credentials (login, password, server URL) for the phone number. 2. Add the phone in Happ: **Phones** > **Add Phone** (see [Phone & SIP Setup](/docs/voice/setup)). 3. Add the integration: **Integrations** > **Add Integration** > pick the provider, enter credentials, activate. ## Supported providers [#supported-providers] | Provider | What it is | Notes | | -------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | | [Binotel](/docs/voice/providers/binotel) | Ukrainian VoIP for business phone systems | API Key + API Secret — issued by Binotel support on request | | [Ringostat](/docs/voice/providers/ringostat) | Call tracking + analytics with telephony | Auth Key — generated on the Ringostat API page | | [Phonet](/docs/voice/providers/phonet) | Cloud telephony for businesses | Domain + API Key — from the CRM-integration section | | [Unitalk](/docs/voice/providers/unitalk) | Telephony for contact centers | API Key — created on the UniTalk API page | ## ElevenLabs (premium voices) [#elevenlabs-premium-voices] Not a telephony provider — supplies high-quality text-to-speech. **Integrations** > **Add Integration** > **ElevenLabs**, enter your API key from [elevenlabs.io](https://elevenlabs.io). ElevenLabs voices (multiple languages, accents, voice cloning) then appear in the assistant's voice settings. Without it, the agent uses one of the 30 built-in voices. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Next [#next] * [Phone & SIP Setup](/docs/voice/setup) — connect the number * [Voice Assistant](/docs/voice) — overview and settings --- # Phone & SIP Setup Bind the client's SIP number to an assistant for inbound voice calls > Full REST + WebSocket API reference: https://api.happ.tools/reference Add a SIP phone number, bind it to an assistant, and the AI voice agent answers inbound calls. ## Connect a phone [#connect-a-phone] 1. Get SIP credentials from a [supported provider](/docs/voice/providers): phone number, SIP login, SIP password, telephony URL. 2. **Phones** > **Add Phone**, fill the fields below, **Save**. 3. Bind it: select an **Assistant** in the phone settings (one phone → one assistant), **Save**. 4. Add the telephony provider integration: **Integrations** > **Add Integration** > pick the provider, enter credentials, activate. 5. Configure the assistant's voice settings, then call the number to test the greeting and a tool. ## Phone fields [#phone-fields] | Field | Value | | ------------ | ------------------------------------- | | Phone Number | SIP phone number (e.g. +380501234567) | | SIP Login | Authentication username | | SIP Password | Authentication password | | Provider URL | SIP server address | | Codec | A-law (default) or μ-law | | Comment | Optional label | ## Voice settings (on assistant) [#voice-settings-on-assistant] | Setting | Value | | ------------------ | ------------------------------------------- | | Voice | 30 built-in voices or ElevenLabs | | Audio format | Input/output format (default PCM 8000) | | Eagerness | Eager, Normal, or Patient | | Turn after silence | Seconds before assistant speaks (default 7) | | Soft timeout | Max wait for user response; -1 = unlimited | See [Assistants > Voice Settings](/docs/assistants#voice-settings). ## API [#api] ```bash POST /api/phones X-Access-Token: happ_your_token_here Content-Type: application/json { "phoneNumber": "+380501234567", "sipLogin": "your-sip-login", "password": "your-sip-password", "telephonyUrl": "sip.provider.com", "codec": "alaw", "comment": "Main office line" } ``` Bind to an assistant with `PATCH /api/phones/{phoneId}` (`{ "assistantId": "..." }`). List `GET /api/phones`, update `PATCH`, remove `DELETE /api/phones/{phoneId}`. **API:** [api.happ.tools/reference](https://api.happ.tools/reference) ## Troubleshooting [#troubleshooting] | Problem | Solution | | -------------- | --------------------------------------------------- | | No audio | Verify SIP credentials and provider URL | | Choppy audio | Check network; try the other codec (alaw vs ulaw) | | Slow responses | Set eagerness to Eager | | No connection | Verify the telephony provider integration is active | | Wrong voice | Check the voice setting in assistant configuration | ## Next [#next] * [Telephony providers](/docs/voice/providers) — provider list * [Voice Assistant](/docs/voice) — overview --- # KeyCRM Connect KeyCRM so the assistant finds buyers by phone and creates pipeline cards or orders > Full REST + WebSocket API reference: https://api.happ.tools/reference KeyCRM connects with a single API key. Once it's linked, the assistant looks buyers up by phone number mid-conversation and drops new orders straight into your sales pipeline. ## Before you start [#before-you-start] * **KeyCRM account** on a paid plan — the API is exposed on all paid tiers. * **API key** from KeyCRM settings (see below). * **HAPP workspace** with at least one assistant configured to talk to customers. * **Pipeline and starting status** — decide where new cards should land. ## Get your API key [#get-your-api-key] 1. From the KeyCRM dashboard, open **Settings** in the left sidebar. 2. Go to **General** > **API**. 3. Click **Generate** if there's no key yet, then copy the token. The API key field in KeyCRM settings, with the copy button ## Connect [#connect] 1. In HAPP open **Integrations** and find KeyCRM under **Add a CRM**. 2. Click **Connect** — the modal asks for one field. 3. Paste the **API key** and click **Connect**. KeyCRM moves to **My integrations** as a card showing its **Account Information** — workspace name and the date and time of connection. | Field | Value | | ------- | ------------------------------------------------ | | API Key | The token from KeyCRM > Settings > General > API | ## Settings [#settings] Open the card's gear icon to configure what the assistant is allowed to do. * **Search** — the assistant looks up existing buyers by phone number and returns their data. * **Create** — the assistant creates new records. Pick the **creation mode** (pipeline card or order), the **sales pipeline**, the **card status** the record is moved to, and the **order source**. ## Troubleshooting [#troubleshooting] | Error | Cause | Fix | | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `INVALID_API_KEY` | Key mistyped or copied with spaces | Re-copy the token from KeyCRM > Settings > General > API. Make sure you generated it before copying. | | `TOKEN_REVOKED` (401) | An admin rotated or revoked the key | Generate a fresh key in KeyCRM and reconnect in HAPP. | | `RATE_LIMITED` (429) | KeyCRM's API rate limit hit | Wait 1–2 minutes and retry. If it keeps happening, [contact support](https://happ.tools/contacts) — we can throttle requests on our side. | | Orders aren't reaching KeyCRM | Sync misconfigured | Check three things, in order: pipeline and starting status are selected in **Settings**; the KeyCRM buyer fields used in mapping are active, not archived; the IP whitelist in KeyCRM > Settings > API is empty **or** includes HAPP egress IPs. | Still stuck? [Contact support](https://happ.tools/contacts) with the error text and we'll point at the exact fix. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **KeyCRM**, click **Disconnect** next to the connected workspace, and confirm. After disconnecting: * New chat orders stop being sent to KeyCRM. * Existing orders in KeyCRM stay untouched. * The assistant keeps working in chat — only the KeyCRM sync stops. * The API key is **not** revoked in KeyCRM. Revoke it there separately if you need to. **To reconnect:** open **Integrations** > **KeyCRM**, click **Connect** and paste the API key again. Preserved after reconnecting: pipeline and status selection, field mapping, the assistant-to-workspace binding, and order analytics for the integration. ## Next [#next] * [CRM](/docs/integrations/crm) — all CRM integrations * [Tools](/docs/tools) — call the CRM during conversations * [Integrations](/docs/integrations) — the full catalog --- # NetHunt Connect NetHunt so the assistant finds contacts by phone and creates new ones in the folder you choose > Full REST + WebSocket API reference: https://api.happ.tools/reference NetHunt is a Gmail-based CRM, so it authenticates with the account email plus an API key. Once linked, the assistant finds contacts by phone number and creates new ones in the NetHunt folder you pick. ## Before you start [#before-you-start] * **NetHunt account** on a paid plan — the API is exposed on all paid tiers. * **Account email** and an **API key** (see below). * **HAPP workspace** with at least one assistant configured to talk to customers. * **Folders decided** — which NetHunt folder to search contacts in, and which one to create them in. ## Get your API key [#get-your-api-key] 1. From the NetHunt dashboard, click **Settings** at the bottom of the left sidebar. 2. In the **INTEGRATIONS** group pick **Apps and other integrations**. 3. Scroll to the bottom, click **GENERATE API KEY**, and copy the token. The API key at the bottom of Apps and other integrations in NetHunt ## Connect [#connect] 1. In HAPP open **Integrations** and find NetHunt under **Add a CRM**. 2. Click **Connect** — the modal asks for two fields. 3. Enter them and click **Connect**. | Field | Value | | ------- | --------------------------------------- | | Email | The email of your NetHunt account | | API Key | The token generated in NetHunt settings | NetHunt moves to **My integrations** as a card showing its **Account Information** — workspace name and the date and time of connection. ## Settings [#settings] Open the card's gear icon to configure what the assistant is allowed to do. * **Search** — pick the **folder to search contacts in** and the **search field** holding the phone number. The assistant looks contacts up by phone in that folder. * **Create** — pick the **folder to create contacts in**, then set up **field mapping**: for each assistant parameter, choose the NetHunt field it writes to, its type, and whether it's required. Field mapping is what makes contact creation work. If a required NetHunt field has no mapped parameter, the contact won't be created. ## Troubleshooting [#troubleshooting] | Error | Cause | Fix | | ------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INVALID_API_KEY` | Key mistyped or copied with spaces | Re-copy the token from NetHunt > Settings > Apps and other integrations. | | Authentication fails with a valid key | Email doesn't match the account that owns the key | The email and the API key must belong to the same NetHunt account. | | `TOKEN_REVOKED` (401) | An admin rotated or revoked the key | Generate a fresh key in NetHunt and reconnect in HAPP. | | `RATE_LIMITED` (429) | NetHunt's API rate limit hit | Wait 1–2 minutes and retry. If it keeps happening, [contact support](https://happ.tools/contacts) — we can throttle requests on our side. | | Contacts aren't being created | Folder or mapping misconfigured | Check three things, in order: a create folder is selected in **Settings**; every required NetHunt field has a mapped parameter; the mapped fields are still active in NetHunt, not archived. | Still stuck? [Contact support](https://happ.tools/contacts) with the error text and we'll point at the exact fix. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **NetHunt**, click **Disconnect** next to the connected workspace, and confirm. After disconnecting: * New contacts from chat stop being sent to NetHunt. * Existing contacts in NetHunt stay untouched. * The assistant keeps working in chat — only the NetHunt sync stops. * The API key is **not** revoked in NetHunt. Revoke it there separately if you need to. **To reconnect:** open **Integrations** > **NetHunt**, click **Connect** and enter the email and API key again. Preserved after reconnecting: folder selection, field mapping, the assistant-to-workspace binding, and analytics for the integration. ## Next [#next] * [CRM](/docs/integrations/crm) — all CRM integrations * [Tools](/docs/tools) — call the CRM during conversations * [Integrations](/docs/integrations) — the full catalog --- # Odoo Connect an Odoo server so the assistant finds contacts by phone and creates orders > Full REST + WebSocket API reference: https://api.happ.tools/reference Odoo connects with your server details and a user login — Happ authenticates against your Odoo instance directly, so it works with Odoo Online and self-hosted alike. Once linked, the assistant finds contacts by phone number and creates orders from chat. ## Before you start [#before-you-start] * **Odoo instance** you can reach over the internet — Odoo Online (`mycompany.odoo.com`) or your own server. * **Server URL, database name, and a user login** with permission to read contacts and create orders. * **Password or API key** for that user (see below — an API key is the safer option). * **HAPP workspace** with at least one assistant configured to talk to customers. ## Get an API key [#get-an-api-key] You can connect with the user's regular password, but an API key is safer — it's scoped to one integration and you can revoke it without changing the account password. 1. In your Odoo dashboard, click the **avatar** in the top-right and pick **My Preferences**. 2. Switch to the **Security** tab, press **Add API Key**, then enter your current password to confirm it's you. 3. Give the key a name (for example `Happ`) and **change the duration from "1 Day" to "1 Year"** — otherwise the key expires in 24 hours. Press **Create key** and copy it. Odoo shows the API key once. Copy it before closing the dialog — if you lose it, you have to generate a new one. Odoo shows the generated key once, in a dialog you cannot reopen ## Connect [#connect] 1. In HAPP open **Integrations** and find Odoo under **Add a CRM**. 2. Click **Connect** — the modal asks for four fields. 3. Enter them and click **Connect**. | Field | Value | | ---------- | ------------------------------------------------------------ | | Server URL | Your instance address, e.g. `https://mycompany.odoo.com` | | Database | The database name | | Login | The user's email | | Password | The user's Odoo password, **or** the API key generated above | Odoo moves to **My integrations** as a card showing its **Account Information** — instance name and the date and time of connection. ## Settings [#settings] Open the card's gear icon to configure what the assistant is allowed to do. * **Search** — the assistant looks up contacts by phone number in the Odoo database. * **Create** — the assistant creates orders linked to the contact, with the product name in the notes. ## Troubleshooting [#troubleshooting] | Problem | Cause | Fix | | ------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication fails | Wrong login, password, or database | Odoo needs all four values to match. Confirm the database name — an instance can host several, and the name is not always the same as the subdomain. | | Key stopped working after a day | The API key was created with the default "1 Day" duration | Generate a new key and set the duration to **1 Year**. | | 401 on a key that used to work | An admin revoked it, or the user's password changed | Generate a fresh API key in **My Preferences** > **Security** and reconnect in HAPP. | | Server unreachable | Self-hosted instance not exposed, or blocked by firewall | The URL must be reachable from the internet over HTTPS. Allow HAPP egress IPs if you filter by IP. | | Orders aren't being created | Sync misconfigured or missing permissions | Check that **Create** is enabled in **Settings**, and that the Odoo user has rights to create orders. | Still stuck? [Contact support](https://happ.tools/contacts) with the error text and we'll point at the exact fix. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **Odoo**, click **Disconnect** next to the connected instance, and confirm. After disconnecting: * New chat orders stop being sent to Odoo. * Existing records in Odoo stay untouched. * The assistant keeps working in chat — only the Odoo sync stops. * The API key is **not** revoked in Odoo. Revoke it there separately if you need to. **To reconnect:** open **Integrations** > **Odoo**, click **Connect** and enter the four fields again. Preserved after reconnecting: search and create settings, field mapping, the assistant-to-instance binding, and analytics for the integration. ## Next [#next] * [CRM](/docs/integrations/crm) — all CRM integrations * [Tools](/docs/tools) — call the CRM during conversations * [Integrations](/docs/integrations) — the full catalog --- # SalesDrive Connect SalesDrive so the assistant finds orders by phone, creates new ones, and can read your product catalog > Full REST + WebSocket API reference: https://api.happ.tools/reference SalesDrive connects with an API key plus your store subdomain. Once it's linked, the assistant finds orders by phone number, creates new ones from chat, and — if you enable it — can suggest products from your catalog. ## Before you start [#before-you-start] * **SalesDrive account** on a plan with API access enabled in **Settings** > **API**. Free tiers don't expose the API. * **General API key** from SalesDrive — not the Form-API key, those are different. * **HAPP workspace** with at least one assistant configured to talk to customers. * **Funnel and starting status** — decide where new orders should land. ## Get your API key [#get-your-api-key] 1. In the SalesDrive admin, go to **Settings** > **General settings & integrations**. 2. Navigate to **Own sites & marketplaces** and pick **API**. 3. Click **API keys**, then in the table choose the row **"For website integration (system)"** and copy that key. The SalesDrive API keys table — the row to copy is "For website integration (system)" ## Connect [#connect] 1. In HAPP open **Integrations** and find SalesDrive under **Add a CRM**. 2. Click **Connect** — the modal asks for two fields. 3. Enter them and click **Connect**. | Field | Value | | ------- | -------------------------------------------------------------------- | | API Key | The general API key from SalesDrive > Settings > API | | Domain | The subdomain only — for `happstore.salesdrive.me` enter `happstore` | SalesDrive moves to **My integrations** as a card showing its **Account Information** — store domain and the date and time of connection. ## Settings [#settings] Open the card's gear icon to configure what the assistant is allowed to do. * **Search** — the assistant looks up orders by phone number and returns the contact data. * **Create** — the assistant creates new orders with the customer's name, phone and comment. * **Catalog** — the assistant gets access to your product catalog and can suggest products. This needs a **YML Catalog public key**: in SalesDrive go to **Settings** > **Integrations** > **YML Export** and copy the public key. ## Troubleshooting [#troubleshooting] | Error | Cause | Fix | | --------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INVALID_API_KEY` | Wrong key, or copied with spaces | Re-copy the key. Use the **general** API key from SalesDrive > Settings > API — not the Form-API key. | | `WRONG_DOMAIN` | Full domain entered instead of the subdomain | Enter the subdomain only. For `happstore.salesdrive.me` the value is `happstore`. | | `TOKEN_REVOKED` (401) | An admin rotated or revoked the key | Generate a fresh key in SalesDrive > Settings > API and reconnect in HAPP. | | `RATE_LIMITED` (429) | SalesDrive's API rate limit hit | Wait 1–2 minutes and retry. If it keeps happening, [contact support](https://happ.tools/contacts) — we can throttle requests on our side. | | Orders aren't reaching SalesDrive | Sync misconfigured | Check three things, in order: funnel and starting status are selected in **Settings**; the SalesDrive client fields used in mapping are active, not archived; the IP whitelist in SalesDrive > Settings > API is empty **or** includes HAPP egress IPs. | Still stuck? [Contact support](https://happ.tools/contacts) with the error text and we'll point at the exact fix. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **SalesDrive**, click **Disconnect** next to the connected store, and confirm. After disconnecting: * New chat orders stop being sent to SalesDrive. * Existing orders in SalesDrive stay untouched. * The assistant keeps working in chat — only the SalesDrive sync stops. * The API key is **not** revoked in SalesDrive. Revoke it there separately if you need to. **To reconnect:** open **Integrations** > **SalesDrive**, click **Connect** and enter your domain and API key again. Preserved after reconnecting: funnel and starting-status selection, field mapping, the assistant-to-store binding, and order analytics for the integration. ## Next [#next] * [CRM](/docs/integrations/crm) — all CRM integrations * [Tools](/docs/tools) — call the CRM during conversations * [Integrations](/docs/integrations) — the full catalog --- # Binotel Connect Binotel so calls flow into Happ with transcription, AI scoring and analytics > Full REST + WebSocket API reference: https://api.happ.tools/reference Binotel is the one provider that doesn't hand out API credentials from its admin panel — you request them by email. You give Binotel support a webhook URL generated by Happ, they point their webhook at it and send back a Key and Secret. Usually within a day. ## Before you start [#before-you-start] * **Active Binotel account** with provisioned numbers and admin rights — Binotel only acts on requests from account owners. * **Access to your work mailbox** — the same address you normally use with Binotel. They send credentials only to the account owner. * **Webhook URL from Happ** — create the Binotel integration first, and Happ generates it for you (step 1 below). * **Happ account on a plan that includes voice analytics.** One account covers any number of phone lines. ## Get your credentials [#get-your-credentials] 1. In Happ open **Integrations** > **Add Integration** > **Binotel**. Happ generates a unique **webhook URL** for your account and shows empty fields for Key and Secret. Copy the webhook URL. 2. Email **[support@binotel.ua](mailto:support@binotel.ua)**: ask them to point the call webhook at that URL and to send you the **API Key** and **API Secret**. 3. When the credentials arrive, come back and paste them into the same dialog. Steps 1 and 3 are the same screen — you open it, copy the URL, and return to it once Binotel replies. The integration goes live the moment the keys are saved. ## Connect [#connect] | Field | Value | | ---------- | ------------------------------------ | | API Key | The key Binotel support sends you | | API Secret | The secret Binotel support sends you | Add the client's phone number separately under **Phones** — see [Phone & SIP Setup](/docs/voice/setup). ## How you'll know it's connected [#how-youll-know-its-connected] The integration card shows a green **Connected** pill, and calls start reaching Happ straight away — with transcription, AI scoring and Voice AI available on them. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **Binotel**, click **…** next to the integration card and choose **Remove**. Optionally email [support@binotel.ua](mailto:support@binotel.ua) asking them to deactivate the webhook on their side. After disconnecting: * New Binotel calls stop reaching Happ. * All past calls, transcripts and AI scores stay in Happ. * The webhook on the Binotel side may still be active — request deactivation by email if you want it off. * The API Key and Secret stay valid in Binotel. Ask support to revoke them if needed. **To reconnect:** open **Integrations** > **Binotel** > **Connect**, paste the saved Key and Secret (or request new ones from support), then attach the integration to the assistant again. Preserved after reconnecting: integration settings (call direction, who answers, scoring rubric), the assistant binding and its prompt, and all past transcripts, scores and dashboards. If the webhook was deactivated, ask Binotel to turn it back on. ## Next [#next] * [Telephony Providers](/docs/voice/providers) — all supported providers * [Phone & SIP Setup](/docs/voice/setup) — connect the number * [Voice Assistant](/docs/voice) — overview and settings --- # Phonet Connect Phonet so calls flow into Happ with transcription, AI scoring and analytics > Full REST + WebSocket API reference: https://api.happ.tools/reference Phonet exposes its API credentials through the admin panel, in the section meant for connecting a CRM. Three clicks and you have the API server and API key to paste into Happ. ## Before you start [#before-you-start] * **Active Phonet account** with provisioned numbers and admin rights on the account. * **API server and API key** from the Phonet admin (below). * **Happ account on a plan that includes voice analytics.** ## Get your API key [#get-your-api-key] 1. In the Phonet admin open **Налаштування** (Settings) > **Інтеграції** (Integrations). 2. Scroll down to **CRM системи** and click **Налаштувати** on **Друга CRM система**. 3. The **API сервер** and **API ключ** appear in a green box on the right — copy both. The Phonet admin — API server and API key in the green box on the right ## Connect [#connect] 1. In Happ open **Integrations** > **Add Integration** > **Phonet**. 2. Enter both values and connect. | Field | Value | | ------- | -------------------------------------------- | | Domain | The API server, e.g. `mycompany.pbx.vega.ua` | | API Key | The API key from the green box | Add the client's phone number separately under **Phones** — see [Phone & SIP Setup](/docs/voice/setup). ## How you'll know it's connected [#how-youll-know-its-connected] The integration card shows a green **Connected** pill, and calls start reaching Happ straight away — with transcription, AI scoring and Voice AI available on them. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **Phonet**, click **…** next to the integration card and choose **Remove**. After disconnecting: * New Phonet calls stop reaching Happ. * All past calls, transcripts and AI scores stay in Happ. * The API key stays valid in Phonet — the CRM-integration section in their admin is where you revoke or regenerate it. **To reconnect:** open **Integrations** > **Phonet** > **Connect**, paste the domain and API key again, then attach the integration to the assistant. Preserved after reconnecting: integration settings (call direction, who answers, scoring rubric), the assistant binding and its prompt, and all past transcripts, scores and dashboards. ## Next [#next] * [Telephony Providers](/docs/voice/providers) — all supported providers * [Phone & SIP Setup](/docs/voice/setup) — connect the number * [Voice Assistant](/docs/voice) — overview and settings --- # Ringostat Connect Ringostat so calls flow into Happ with transcription, AI scoring and analytics > Full REST + WebSocket API reference: https://api.happ.tools/reference Ringostat generates its Auth-key on demand from the admin panel — one button, and the key is ready to paste into Happ. ## Before you start [#before-you-start] * **Active Ringostat project** with call tracking set up and admin rights on the project. * **Auth-key** from the Ringostat admin (below). * **Happ account on a plan that includes voice analytics.** ## Get your Auth-key [#get-your-auth-key] 1. In the Ringostat admin open **Налаштування** (Settings) > **Інтеграція** (Integration). 2. Pick **Ringostat API**. 3. Click **Генерувати** — the key appears instantly in the **Auth-key** field. Copy it. The Ringostat API page — the Generate button that creates the Auth-key ## Connect [#connect] 1. In Happ open **Integrations** > **Add Integration** > **Ringostat**. 2. Paste the key and connect. | Field | Value | | -------- | ------------------------------------------------ | | Auth Key | The Auth-key generated on the Ringostat API page | Add the client's phone number separately under **Phones** — see [Phone & SIP Setup](/docs/voice/setup). ## How you'll know it's connected [#how-youll-know-its-connected] The integration card shows a green **Connected** pill, and calls start reaching Happ straight away — with transcription, AI scoring and Voice AI available on them. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **Ringostat**, click **…** next to the integration card and choose **Remove**. After disconnecting: * New Ringostat calls stop reaching Happ. * All past calls, transcripts and AI scores stay in Happ. * The Auth-key stays valid in Ringostat. Generating a new one on the Ringostat API page replaces the old key — which also breaks any other tool using it. **To reconnect:** open **Integrations** > **Ringostat** > **Connect**, paste the Auth-key again, then attach the integration to the assistant. Preserved after reconnecting: integration settings (call direction, who answers, scoring rubric), the assistant binding and its prompt, and all past transcripts, scores and dashboards. ## Next [#next] * [Telephony Providers](/docs/voice/providers) — all supported providers * [Phone & SIP Setup](/docs/voice/setup) — connect the number * [Voice Assistant](/docs/voice) — overview and settings --- # UniTalk Connect UniTalk so calls flow into Happ with transcription, AI scoring and analytics > Full REST + WebSocket API reference: https://api.happ.tools/reference UniTalk creates its API key straight from the admin panel — one green button, and the key is ready to paste into Happ. ## Before you start [#before-you-start] * **Active UniTalk account** with provisioned numbers and admin rights on the account. * **API key** from the UniTalk admin (below). * **Happ account on a plan that includes voice analytics.** ## Get your API key [#get-your-api-key] 1. In the UniTalk admin open **API and automation** > **API**. 2. Click the green **Create an API key** button. 3. The key is created instantly — copy it. The UniTalk API page with the generated API key ## Connect [#connect] 1. In Happ open **Integrations** > **Add Integration** > **UniTalk**. 2. Paste the key and connect. | Field | Value | | ------- | --------------------------------------- | | API Key | The key created on the UniTalk API page | Add the client's phone number separately under **Phones** — see [Phone & SIP Setup](/docs/voice/setup). ## How you'll know it's connected [#how-youll-know-its-connected] The integration card shows a green **Connected** pill, and calls start reaching Happ straight away — with transcription, AI scoring and Voice AI available on them. ## Disconnect and reconnect [#disconnect-and-reconnect] **To disconnect:** open **Integrations** > **UniTalk**, click **…** next to the integration card and choose **Remove**. After disconnecting: * New UniTalk calls stop reaching Happ. * All past calls, transcripts and AI scores stay in Happ. * The API key stays valid in UniTalk — use **Remove** on the UniTalk API page to revoke it there. **To reconnect:** open **Integrations** > **UniTalk** > **Connect**, paste the API key again, then attach the integration to the assistant. Preserved after reconnecting: integration settings (call direction, who answers, scoring rubric), the assistant binding and its prompt, and all past transcripts, scores and dashboards. ## Next [#next] * [Telephony Providers](/docs/voice/providers) — all supported providers * [Phone & SIP Setup](/docs/voice/setup) — connect the number * [Voice Assistant](/docs/voice) — overview and settings