Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.retellai.com/llms.txt

Use this file to discover all available pages before exploring further.

In the previous section, we showed what’s tools. In this section, we will show you how to add them to your agent.

Define Functions (Common Part)

No matter what type of tool you are using, there are some fields you have to define.
  1. tool name: the unique identifier of the tool.
    • Must be consisted of a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64 (no space allowed).
    • it has to be unique across all tools available to the model at any given time.
    • best to be a natural language string that LLM can understand like transfer_to_support.
  2. description: a clear description of what this tool does, sometimes you can also include when to call the tool in this field.
    • This can be optional for some pre-defined tools, as we have some default values (see below for details).
    • IMPORTANT: generally you would write what this tool does here, and write in prompt explicitly when you want to call this tool. (for example: “step 6. After all questions answered, call function end_call to hang up.”)

Pre-defined Tools

There are several pre-defined tools we already provide for your convenience.

Pre-defined Tool Types

End Call

This tool is used to end the call, no matter if it’s web or phone call, no matter if it’s a Retell number or your own Twilio. You can specify a description about when to end the call. If description omitted, it would use the default End the call with user. When end call is triggered, it would always say a farewell sentence like to user before hanging up.

Transfer Call

This tool can only be used when it’s a phone number from Retell or imported.
This tool is used to transfer the call to another number, and it can even be another phone associated with Retell agent. You can specify a description about when to transfer the call. If description omitted, it would use the default Transfer the call to another number. When transfer call is triggered, it would always say a sentence like “Transferring you to… one moment” to user before actual transferring. When you need to have multiple numbers to transfer to (for example, transfer to support department, transfer to sales department), you need to define multiple transfer tools with different names, and in prompt explicitly write when to invoke which tool.

Press Digit

This tool is used to press digit or digits, mainly to navigate IVR. If description omitted, it would use the default The digit to press, can be a single digit, or a combination of digits like '1234*'. Usually either selecting an option in IVR or entering information like phone number. Since IVR is usually speaks slowly, this tool tends to wait for a bit longer before actually pressing the digit.

Check Availability with cal.com

This tool is used to check the availability of an event on cal.com. You can specify a description about when to check the availability. It will automatically handle relative date time references like “tomorrow”, “next week”, “next month” for you ,and automatically deduces a range out of it (for example, “tomorrow” would be from 00:00 to 23:59 of tomorrow). If there’re no nearby availability, it can also retrieve the availability nearby that range. The returned result is parsed based on timezone specified. If no timezone specified, it would uses the timezone of the Retell server. When this tool is triggered, it would always say a sentence like “Checking the availability of event…” to user. The tool requires a Cal.com API key, a cal event type id (retrieved in the url when you configure a cal event, for example: https://app.cal.com/event-types/654321 event type id is 654321). This tool is commonly used in conjunction with the book appointment cal.com tool.

Book Appointment with cal.com

This tool is used to book an appointment with specified event on cal.com. You can specify a description about when to book the appointment. It will automatically handle relative date time references like “tomorrow 5pm”, “next Tuesday 2pm” for you. It would utilize the timezone specified to parse the time reference to the ISO8601 format to use in the API call. When this tool is triggered, it would always say a sentence like “Booking an appointment for you…” to user. The tool requires a Cal.com API key, a cal event type id (retrieved in the url when you configure a cal event, for example: https://app.cal.com/event-types/654321 event type id is 654321). This tool is commonly used in conjunction with the check appointment cal.com tool. If user selected a time that’s not available, this tool would return message like “cannot book appointment at this time”. Therefore it’s recommended to retrieve availability first before booking an appointment.

Add via Dashboard

Step 1 - Add end call tool

Click ”+ Add” and select “End Call”.
Adding an end call tool from the tool selection menu

Step 2 - Provide more details to the tool

  1. Clarify the conditions under which the call should be terminated.
End call tool configuration with termination conditions
  1. It’s advisable to reiterate the requirements in the prompt to ensure optimal precision.
Agent prompt reiterating end call conditions for precision
  1. Don’t forget clicking “Save LLM” on the top right.

Add via API

You can also add predefined tools programmatically.
// install the sdk: https://docs.retellai.com/get-started/sdk
import Retell from 'retell-sdk';

const retell = new Retell({ apiKey: "YOUR_API_KEY" });

const agentResponse = await retell.llm.update('your_llm_id', {
  general_tools: [
    {
      name: 'end_call',
      description: 'end the call if the customer has said goodbye',
      type: 'end_call',
    }
  ]
});

Custom Tools

For tasks not covered by pre-defined tools, you can define your custom tool to execute external APIs, provide knowledge to agent, etc. For custom tools, apart from the usual name and description you would define a URL and the parameters for it. Once the LLM decides to call this tool, we will POST to the URL defined with the function name and parameters, and the call information.

Add via Dashboard

Custom function tool configuration in the dashboard with URL and parameter fields
Save the settings, then interact with the agent. If users inquire about the weather for a city, the LLM will query your server for information and relay the response back to the users.

Add via API

You can also add the tool programmatically, similar to how you added it for pre-defined tools.

Define Parameters for Custom Tool

This is a JSON schema to let the LLM know what inputs this tool would need. For example, for the following get-weather custom tool, we defined the parameters to be a city name.
{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city of the weather"
    }
  },
  "required": [
    "city"
  ]
}
Then upon triggering of the tool we will POST the a JSON body data like the following to the URL specified:
{
  "call": {
    "call_type": "phone_call",
    "from_number": "+12137771234",
    "to_number": "+12137771235",
    "direction": "inbound",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "opt_out_sensitive_data_storage": true
  },
  "name": "get_weather",
  "args": {
    "city": "New York"
  }
}

Verify and Handle the Request

Now you’ve got the tool call request, you need to verify the request is from Retell and handle it.
You can secure your server from public network by only allowlisting Retell IP addresses: 100.20.5.228
Make sure to check in your server if you have all the required arguments you need, because LLM can hallucinate and make mistakes. Once you have the result data, you can write it back in the response as a JSON object or plain string. Please note that we will cap the response to 4000 characters to avoid hitting context window upper limits.
import { Retell } from "retell-sdk";
import express from "express";

const app = express();
// Use raw body for signature verification, not JSON.stringify(req.body).
app.use(express.raw({ type: "application/json" }));

app.post("/check-weather", async (req, res) => {
  const rawBody = req.body.toString("utf-8");
  if (
    !Retell.verify(
      rawBody,
      process.env.RETELL_API_KEY,
      req.headers["x-retell-signature"],
    )
  ) {
    console.error("Invalid signature");
    return;
  }
  const content = JSON.parse(rawBody);
  if (content.args.city === "New York") {
    return res.json("25f and sunny");
  } else {
    return res.json("20f and cloudy");
  }
});
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from retell import Retell

retell = Retell(api_key=os.environ["RETELL_API_KEY"])

@app.post("/webhook")
async def handle_webhook(request: Request):
    try:
        raw_body = (await request.body()).decode("utf-8")
        valid_signature = retell.verify(
            raw_body,
            api_key=str(os.environ["RETELL_API_KEY"]),
            signature=str(request.headers.get("X-Retell-Signature")),
        )
        if not valid_signature:
            print("Received Unauthorized")
            return JSONResponse(status_code=401, content={"message": "Unauthorized"})
        post_data = json.loads(raw_body)
        args = post_data["args"]
        if args["city"] == "New York":
            return JSONResponse(status_code=200, content={"result": "25f and sunny"})
        else:
            return JSONResponse(status_code=200, content={"result": "20f and cloudy"})
    except Exception as err:
        print(f"Error in webhook: {err}")
        return JSONResponse(
            status_code=500, content={"message": "Internal Server Error"}
        )

Use Ngrok for Local Testing (Optional)

If you are using localhost to test, you can use ngrok to produce a production url to feed into dashboard If you are not familiar with ngrok, a tutorial can be found here.