Custom Function

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 custom function is called, Retell sends a POST request to your specified URL with the function name and parameters.

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

​

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.

​

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"}
        )