Custom functions allow you to extend your agent’s capabilities by integrating external APIs, providing additional knowledge, or implementing custom logic.

​
Steps to create a custom function

You can create custom functions that will be called by the LLM when needed. When called, Retell sends a POST request to your specified URL with the function name and parameters.

1

Add custom function in dashboard

Click ”+ Add” in the tools section and select “Custom Function” from the dropdown menu.

2

Configure function details

Add a name and description for the custom function. The name should be unique and separated with underscore.

For example:

  • Name: get_weather
  • Description: Get the weather for a city
3

Add endpoint URL

Add the URL where Retell will send the POST request to execute your custom function.

4

Define parameters

Define the parameters for the custom function using JSON schema format. For guidance, refer to:

Example parameter schema:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The city of the weather"
    }
  },
  "required": [
    "city"
  ]
}
5

Configure speech behavior

Set up how the agent should handle speech during and after function execution. These two options are controling agent’s behavior when user is not talking during the function call period. If user interrupts or talks, the agent would respond normally regardless of these settings.

  • Speak during execution: Whether the agent would speak the moment the function is called. Note that currently agent would speak just for one time during the beginning of the function call.
    • Enable for user-facing actions (e.g., getting weather information)
    • Disable for background tasks (e.g., attaching notes to call)
  • Speak after execution: Whether the agent would keep talking / do other actions (maybe call another function) after the function call is completed. You can use this to let agent tell user the result of the function call, continue the conversation, execute another task, etc after the function call is completed, without the need to wait for user to say anything to trigger a response.
    • Probably should enable for almost all cases, except for ones that are like press a digit kind of task where you don’t expect the agent to keep talking.
6

Update prompt for function

It’s best to include in the prompt explicitly when is the best time to invoke the custom function. For example:

When user provided the city name, please get the weather for that city by calling the `get_weather` function.

​
Troubleshooting

If you failed to save the custom function, it is likely because the parameters are not valid.

One common mistake is not adding "type": "object", to the top level of the JSON schema. We recommend clicking one of the examples and update accordingly.

​
Request & response spec

Retell will send a POST request to your endpoint with the following request spec.

Request

  • header
    • X-Retell-Signature: encrypted request body using your secret key, used to verify the request is from Retell. Read more below.
    • Content-Type: application/json. This indicates the payload is in JSON format.
  • body (in JSON format)
    • name: the name of the custom function.
    • call: the call object for you to get more context about the call, it also contains real time transcript up to the time the request is sent. Check out Get Call API for more details about the call object.
    • args: the arguments for the custom function, as a JSON object.

The request will timeout in your specified timeout period, or 2 minutes if not specified. When request fails, it will be retried up to 2 times.

Response

Response should have a status code between 200-299 to indicate success of HTTP POST request. Response to the request can be in various format:

  • string
  • buffer
  • JSON object
  • blob

All these formats will be converted to string before sending to LLM for further processing.

The function result is capped at 15000 characteres to prevent overloading LLM context window.

​
Verifying Request is from Retell

To verify that the request is coming from Retell, you can check the X-Retell-Signature header.

The value is a encrypted request body using your secret key.

import { Retell } from "retell-sdk";

this.app.post("/check-weather", async (req: Request, res: Response) => {
  if (
    !Retell.verify(
      JSON.stringify(req.body),
      process.env.RETELL_API_KEY,
      req.headers["x-retell-signature"] as string,
    )
  ) {
    console.error("Invalid signature");
    return;
  }
  const content = req.body;
  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("/check-weather")
async def check-weather(request: Request):
    try:
        post_data = await request.json()
        valid_signature = retell.verify(
            json.dumps(post_data, separators=(",", ":"), ensure_ascii=False),
            api_key=str(os.environ["RETELL_API_KEY"]),
            signature=str(request.headers.get("X-Retell-Signature")),
        )
        if not valid_signature:
            print(
                "Received Unauthorized",
                post_data["event"],
                post_data["data"]["call_id"],
            )
            return JSONResponse(status_code=401, content={"message": "Unauthorized"})
        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"}
        )
You can also secure your server from public network by only allowlisting Retell IP addresses: 100.20.5.228