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

When a custom function is called, Retell sends a request (POST, GET, PUT, PATCH, DELETE) to your specified URL with the function name and parameters. You can include headers and query parameters in the request, and extract data from the response.

1

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_user_details
  • Description: Get user details based on name and age
2

Select HTTP Method

Choose the HTTP method that Retell will use to send the request to your endpoint. Available methods include:

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
3

Add endpoint URL

Add the URL where Retell will send the request to execute your custom function. This has to be a valid URL.

4

Set request headers (optional)

You can define custom headers to include with the request Retell sends to your endpoint. Header values can be static or include dynamic variables.

5

Set query parameters (optional)

You can define query parameters to include in the request URL that Retell appends to your endpoint. Query parameter values can be static or include dynamic variables.

6

Define parameters

Define the parameters for the custom function using JSON schema format or JSON form. Only available for POST, PATCH and PUT requests. For guidance, refer to:

Example parameter schema:

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

Example JSON form:

7

Set response variables (optional)

Extract values from the API response and save them as dynamic variables for use later in the conversation.

For example, you can extract a user’s name from the response and reference it later using {{user_name}}.

Example response body

{
  "properties": {
    "user": {
      "name": "John Doe",
      "age": 26
    }
  }
}

​
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 the 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, for POST, PUT and PATCH request)
    • 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 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