How to Use Mid Call Tools in Kalimna

Welcome to this comprehensive guide on Mid Call Tools in Kalimna. While the platform already includes basic mid-call functions, Mid Call Tools give you complete flexibility to connect your AI phone agents to any external API or system you use.

Mid Call Tools allow your AI assistant to perform actions during an active call—like saving a lead to your CRM, booking an appointment in your calendar, checking inventory in real-time, looking up customer data, or triggering internal workflows. All of this happens while the caller is still on the line, creating a seamless, efficient customer experience.

For businesses in Qatar, UAE, Saudi Arabia, Kuwait, Bahrain, and Oman running Arabic and English AI phone agents, Mid Call Tools transform your AI from a simple answering service into a fully integrated system that works with your existing business tools—whether it's Salesforce, HubSpot, Google Calendar, or your own custom systems.

Watch the Mid Call Tools Tutorial

Follow along with this step-by-step video to see Mid Call Tools in action:

💡 Tip: Watch the video while following the written steps below.

What Are Mid Call Tools?

Mid Call Tools are custom functions that your AI assistant can execute during a live conversation. They enable the assistant to connect to external APIs to fetch information or trigger actions without human intervention.

Basic Mid-Call Functions vs. Mid Call Tools

Kalimna already provides some built-in mid-call functions in the Assistants tab. However, Mid Call Tools give you full flexibility to:

• Connect to any external API your business uses
• Define custom logic and parameters specific to your workflows
• Integrate with proprietary or custom-built systems
• Handle complex data exchanges during calls

Real-World Examples:

Step 1 – Open the Mid Call Tools Section

To get started, log into your Kalimna dashboard and locate Mid Call Tools in the left-side navigation menu. Click it to open the Mid Call Tools management area.

This is where all your custom tools live. If you're new, the list will be empty—you're about to create your first tool.

Step 2 – Create a New Mid Call Tool

Click the "Create" button to open the tool creation window. This form has several sections where you'll configure how your tool works:

• Name – What the tool is called
• Description – What it does and when to use it
• Endpoint – Where API requests are sent
• Timeout – How long to wait for a response
• Method – Type of HTTP request (GET, POST, etc.)
• Headers – Authentication and format information
• Parameters – Inputs the tool needs

Don't worry if this seems technical—we'll walk through each part step by step.

Step 3 – Name Your Tool Correctly

The tool name is how your AI assistant recognizes and calls the tool during conversations. Naming conventions are critical.

Naming Rules:

• Use lowercase only (no capitals)
• Use underscores for spaces (not hyphens or spaces)
• Be descriptive (the name should explain what the tool does)

Good examples:

• get_weather – retrieves weather data
• create_lead – creates a new lead in CRM
• book_appointment – schedules an appointment
• check_availability – checks calendar availability
• update_customer_email – updates email in database

Bad examples:

• CreateLead (has capitals)
• check-availability (uses hyphens instead of underscores)
• tool1 (not descriptive)

Step 4 – Add a Clear Tool Description

The description explains to the AI what the tool does and when to use it. The more specific and clear you are, the better the assistant understands when to call the tool during a conversation.

What to Include in Your Description:

• What the tool does (the action it performs)
• When to use it (the conditions or trigger points)
• What inputs are needed (parameters required)

Good description examples:

• "Use this tool to create a new lead in the CRM when the caller has provided their full name, phone number, and email address."
• "Check calendar availability for the requested date and time before confirming an appointment with the customer."
• "Retrieve customer account information from the database using their phone number to personalize the conversation."
• "Book an appointment in the calendar system once the customer has confirmed the date, time, and service type."

Step 5 – Configure the Endpoint and Timeout

Endpoint (API URL)

The endpoint is the API address where the request will be sent. This could be:

• Your CRM's API endpoint (e.g., https://api.hubspot.com/contacts/v1/contact)
• Your calendar system's API (e.g., https://api.calendly.com/scheduled_events)
• Your own internal API (e.g., https://yourcompany.com/api/leads)
• Third-party services (weather APIs, shipping APIs, etc.)

You'll find the correct endpoint URL in your API provider's documentation.

Timeout

The timeout controls how long (in seconds) the assistant will wait for a response from the endpoint before giving up.

• Too short (e.g., 2 seconds): The tool might timeout before slow APIs respond, causing failures.
• Too long (e.g., 30 seconds): The caller waits in awkward silence if the API is slow or down.
• Just right (5-10 seconds): Balances reliability with user experience.

Recommended: Start with 8-10 seconds. If your API is consistently fast (under 2 seconds), you can lower it. If it's occasionally slow, increase it slightly.

Step 6 – Choose the HTTP Method (GET, POST, PUT, PATCH, DELETE)

The HTTP method tells the API what kind of action you want to perform. Here's what each method does, explained in simple terms:

GET – Retrieve Data

Use when: You want to fetch/read information without changing anything.

• Check available appointment time slots
• Look up customer information by phone number
• Get current weather data
• Retrieve product details or pricing

POST – Create Something New

Use when: You want to create a new record or entry.

• Create a new lead in your CRM
• Book a new appointment
• Submit a support ticket
• Add a new customer to your database

PUT – Replace Existing Data

Use when: You want to completely replace an existing record.

• Replace all details of a customer record
• Update an entire appointment (all fields)

PATCH – Update Parts of Existing Data

Use when: You want to update only specific fields without replacing everything.

• Change only the customer's email address
• Update just the appointment time (keeping date and other details)
• Modify a single field in a lead record

DELETE – Remove Data

Use when: You want to delete a record or cancel something.

• Cancel an appointment
• Remove a lead from the system
• Delete a temporary entry

Step 7 – Add Headers (Content-Type, Authorization, etc.)

Headers are extra pieces of information sent with each API request. Think of them like notes on an envelope that tell the API how to interpret and process your request.

Common Headers:

1. Content-Type

Tells the API what format the data is in. Most modern APIs use JSON.

• Header name: Content-Type
• Value: application/json

2. Authorization

Provides authentication credentials so the API knows you're allowed to access it.

• Header name: Authorization
• Value: Bearer YOUR_API_TOKEN

(Replace YOUR_API_TOKEN with your actual API key from the service)

How to Add/Remove Headers:

1. Click "Add header" to create a new header row
2. Enter the header name (e.g., Content-Type)
3. Enter the header value (e.g., application/json)
4. To remove a header, click the trash icon next to it

Step 8 – Define Tool Parameters

Parameters are the inputs your assistant needs to collect from the caller before calling the tool. These become the data sent to your API.

Understanding Parameters:

For example, if you're creating a book_appointment tool, you might need parameters like:

• customer_name (string) – The caller's full name
• phone_number (string) – Contact number
• appointment_date (string) – Preferred date
• appointment_time (string) – Preferred time
• service_type (string) – What service they need

Important Behavior:

Here's the magic: If a required parameter is missing, the assistant will automatically ask the caller for it.

For example, if the caller says "I want to book an appointment" without mentioning a date, and appointment_date is a required parameter, the AI will naturally ask: "What date would you prefer for your appointment?"

How to Add Parameters:

1. Click "Add parameter"
2. Enter the parameter name (e.g., customer_email)
3. Choose the type if applicable (string, number, boolean)
4. Mark whether it's required or optional
5. Add a description explaining what this parameter is

Step 9 – Save Your Tool (Create vs Create and Create Another)

At the bottom of the form, you have three action buttons:

Create

Saves the tool and returns you to the Mid Call Tools overview. Use this when you're creating a single tool or finishing up.

Create and Create Another

Saves the current tool and immediately opens a blank form to create another one. Perfect when you're setting up multiple related tools in one session.

Example: If you're building a complete booking system, you might create:

1. check_availability
2. book_appointment
3. cancel_appointment
4. reschedule_appointment

Using "Create and create another" lets you add all four without navigating back and forth.

Cancel

Exits without saving any changes. Use this if you made a mistake or changed your mind.

Once saved, the tool becomes available to your AI assistants. You'll need to reference it in your assistant's prompt or system instructions so the AI knows when to use it.

Best Practices and Example Use Cases

Best Practices:

• Keep names and descriptions clear: Future you (or your team) should instantly understand what each tool does.
• Start small: Create 1-2 tools first and test them thoroughly before building a full suite.
• Ensure endpoint stability: Make sure your APIs are reliable and respond consistently within the timeout period.
• Protect sensitive endpoints: Always use proper authentication (bearer tokens, API keys) to prevent unauthorized access.
• Test with real scenarios: After creating a tool, test it with your AI agent to ensure it works as expected in actual conversations.
• Monitor API usage: Keep track of how often tools are called to avoid hitting API rate limits.

Gulf-Focused Use Cases:

What's Next?

You now know how to create powerful Mid Call Tools that connect your AI phone agents to external systems. Your agents can now interact with CRMs, calendars, databases, and any API you use—all during live conversations.

Recommended Next Steps: