Integrate any system with 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
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.
Add custom function in dashboard
Click ”+ Add” in the tools section and select “Custom Function” from the dropdown menu.
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
Add endpoint URL
Add the URL where Retell will send the POST request to execute your custom function.
Define parameters
Define the parameters for the custom function using JSON schema format. For guidance, refer to:
Example parameter schema:
Configure speech behavior
Set up how the agent should handle speech during and after function execution:
- Speak during execution: Enable if the agent should speak while the function runs
- Enable for user-facing actions (e.g., getting weather information)
- Disable for background tasks (e.g., attaching notes to call)
- Speak after execution: Enable if the agent should provide feedback after the function completes
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:
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 4000 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.
100.20.5.228
Was this page helpful?