Actions & Tools

By default, your agent only talks. Tools are powers you grant it — like fetching data from your CRM or transferring the call to a human.

When you add a tool, you describe what it does in plain English. The AI decides when to use it.

There are four kinds:

1. HTTP tools — call your API
2. Client tools — run JavaScript in the visitor's browser (web only)
3. MCP servers — connect to other AI tools / databases
4. Transfer tools — hand the call to a human or another agent

1. HTTP tools (most common)

Let the bot call your API mid-conversation.

Example use cases:

• "Look up customer's order status"
• "Check if a phone number is registered"
• "Save a new lead to the CRM"
• "Send an OTP via SMS"

Add an HTTP tool

Configure → Actions → HTTP Tools → + Add

How it works in practice

You set up the tool above. A caller says "What's the status of order ORD-1234?"

1. AI sees the tool description, decides to use it
2. AI extracts order_id = "ORD-1234" from the caller's words
3. osmTalk sends GET https://api.shop.com/orders/ORD-1234 with your headers
4. Your API responds, say { "status": "shipped", "tracking": "AWB987" }
5. AI summarizes the response in natural speech: "Your order ORD-1234 was shipped — tracking number AWB987."

You don't write code to glue these steps. You just describe the tool.

Personalize the request body with {{variables}}

If you pass dynamic variables at call start, you can use them in the URL, headers, or body:

URL: https://api.example.com/orders?campaign={{campaign_id}}&order={order_id}
Headers: { "X-Caller-Name": "{{first_name}}" }

{{campaign_id}} (from call-start) is filled in automatically. {order_id} (from the AI's tool args) comes from the conversation.

2. Client tools (web widget only)

Run JavaScript on the page the user is browsing. Useful for "show this on screen while we talk":

How it works

You declare the tool name + parameters + a preview response. The osmTalk widget on your page receives the function call and you implement it in your widget integration code:

window.osmtalk.on("tool_call", ({ name, args }) => {
  if (name === "highlight_product") {
    document.querySelector(`[data-product-id="${args.product_id}"]`)
      .classList.add("highlight");
  }
});

Only works on browser web calls — not phone or WhatsApp.

3. MCP servers (advanced)

MCP = Model Context Protocol. It's a standard for AI tools.

You can connect external MCP servers (like the official filesystem, GitHub, postgres servers) and your agent gets all their capabilities for free.

Example: Postgres MCP

In Configure → Actions → MCP Servers → + Add:

Your agent now has tools like query_postgres(sql) automatically — describe the data you want and the AI writes SQL and calls the tool.

Security: only add MCP servers you trust. They have full access to whatever the server can do — file system, database, network.

For full MCP setup: MCP Integration Guide.

4. Transfer tools

Move the call to someone (or some other agent).

Transfer to a human

Configure → Actions → Call Transfer → Transfer to Human

The bot picks up the cue from the conversation. When triggered:

1. Bot says "Let me get someone who can help — one moment."
2. Bot dials the destination number
3. The caller is connected to that human; bot exits the call

Transfer to another agent (mid-call)

If you have specialized agents (Sales, Support, Tech, Billing), you can let the front-line agent route to them.

Configure → Actions → Call Transfer → Transfer to Other Agents

Add each agent you want to route to. Give a short trigger description for each:

Calls don't drop — the same call continues with the new agent's prompt. The conversation history is preserved.

Direct keypad routes (DTMF)

If you want callers to skip the AI entirely — "press 1 for sales, 2 for support" — set up keypad routes:

Configure → Advanced → Keypad (DTMF)

Full guide: Keypad routing.

Tool best practices

Common questions

"The bot has the tool but never uses it." The description isn't clear. Tell the AI exactly when to use it. Use examples.

"The bot uses the tool when it shouldn't." Same fix in reverse — add a "DO NOT use this tool when..." sentence.

"My API responds in 5 seconds and the bot sounds dead." Add a waitMessage: "Let me check that for you...". Or speed up your API.

"My tool call returns an error." Set errorMessage: "I couldn't find that information. Could you try again with the order number?" so the bot handles failures gracefully.

"Will the tool work on all channels?"

• HTTP tools: yes (phone, web, WhatsApp)
• Client tools: web only
• MCP: yes, all channels
• Transfer: phone primarily; agent-to-agent works on web too