Tools & Actions

Overview

Tools allow your AI assistant to go beyond text responses. With tools, the assistant can call external APIs, update CRM records, create bookings, look up data, and trigger custom workflows — all within the conversation.

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

How Tools Work

You define a tool with a name, description, parameters, and a webhook URL
During a conversation, the AI determines it needs to use a tool
The assistant calls your webhook with the collected parameters
Your webhook returns a result
The AI uses the result to continue the conversation

The tool calling loop is recursive — the AI can call multiple tools in sequence, using results from one tool to inform the next call.

Creating a Tool

Go to your assistant's Tools tab
Click Add Tool
Configure:

Basic Settings

Field	Description
Name	Descriptive function name (e.g., `create_booking`, `check_order_status`)
Description	What the tool does — the AI reads this to decide when to use it
Type	When the tool runs (see Tool Types below)

Tool Types

Type	When It Runs	Use Case
Webhook Action	During conversation, when the AI decides to use it	Data lookups, bookings, CRM updates
Webhook Init	Automatically at the start of every conversation	Load customer profile, fetch context
Webhook Post-Call	After a voice call ends	Save call summary, update CRM
Client Tool	Handled by the client application (no URL needed)	UI actions, navigation

Webhook Configuration

Field	Description
URL	Your webhook endpoint (e.g., `https://api.yoursite.com/happ/booking`)
HTTP Method	GET, POST, PUT, DELETE, or PATCH
Secret	Shared secret for HMAC-SHA256 request signing

Parameters

Define what data the AI should collect from the conversation:

Field	Description
Name	Parameter name (e.g., `customer_name`, `date`)
Type	`string`, `number`, `boolean`, `array`, or `object`
Description	What this parameter is — helps the AI collect the right info
Required	Whether the parameter must be provided
Value Type	`llm_prompt` (AI decides), `constant` (fixed value), or `dynamic_variable`

Execution Mode

Mode	Behavior
Immediate	Pause conversation until the tool returns a result
Post-Tool Speech	Continue speaking while the tool runs in the background
Async	Fire and forget — don't wait for a result

Sound Effects (Voice Calls)

For voice calls, play a sound while the tool executes:

Sound	Description
`elevator1` – `elevator4`	Elevator bell sounds
`typing`	Typing sound effect

Via API

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

{
  "assistantId": "your-assistant-uuid",
  "name": "create_booking",
  "description": "Book an appointment for the customer",
  "type": "webhook_action",
  "apiCallUrl": "https://api.yoursite.com/bookings",
  "httpMethod": "post",
  "executionMode": "immediate",
  "params": [
    {
      "name": "customer_name",
      "type": "string",
      "description": "The customer's full name",
      "isRequired": true
    },
    {
      "name": "date",
      "type": "string",
      "description": "Appointment date in YYYY-MM-DD format",
      "isRequired": true
    },
    {
      "name": "time",
      "type": "string",
      "description": "Appointment time in HH:MM format",
      "isRequired": true
    }
  ]
}

Webhook Request & Response

When the AI triggers a tool, Happ sends an HTTP request to your webhook:

{
  "customer_name": "John Smith",
  "date": "2025-03-15",
  "time": "14:00",
  "chatId": "chat-uuid"
}

Your webhook should return a JSON response:

{
  "result": "Booking confirmed. Confirmation number: #12345."
}

The AI uses your response text to continue the conversation.

Webhook Security

Requests are signed with HMAC-SHA256 using your webhook secret. Verify the X-Webhook-Signature header on your server before processing.

Built-in Tools

Two tools are always available (you don't need to create them):

turnOffAiMode

The AI can call this tool to transfer the conversation to a human operator. When called:

isUnderAiControl is set to false on the chat
The chat appears in the dashboard as needing human attention
If Telegram Push Notifications are configured, your team gets an instant alert
AI automatically re-enables after ~10 minutes of inactivity (only when the AI itself triggered the handoff via this tool; manually disabled chats do not auto-resume)

searchKnowledge

Available when the assistant has vector knowledge entries. Searches the knowledge base with a semantic query and returns the top 3 results.

Common Use Cases

Order Status

Name: check_order_status
Description: Look up the status of a customer's order
Method: GET
Parameters:
  - order_number (string, required): The order tracking number

Appointment Booking

Name: create_appointment
Description: Book an appointment for the customer
Method: POST
Parameters:
  - date (string, required): Preferred date
  - time (string, required): Preferred time
  - service (string, required): Type of service
  - name (string, required): Customer name
  - phone (string, required): Customer phone

CRM Update

Name: save_contact
Description: Save customer contact information
Method: POST
Parameters:
  - name (string, required): Customer name
  - email (string, optional): Email address
  - phone (string, optional): Phone number
  - notes (string, optional): Additional context

Best Practices

Write clear descriptions — The AI uses the description to decide when to call the tool. Be specific
Validate on your server — Always validate parameters before processing
Return helpful text — The AI uses your response in its reply. Include confirmation numbers, status info, etc.
Handle errors gracefully — Return clear error messages so the AI can communicate issues
Keep it fast — Webhook responses should return within a few seconds. Use async mode for longer operations
Always use a webhook secret — Verify HMAC signatures on every request

On this page