Create Custom Tool
curl --request POST \
--url https://api.revring.ai/v1/agents/{id}/custom-tools \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"webhookUrl": "<string>",
"enabled": true,
"schema": {},
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": true,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": true,
"maxRetries": 0
}
'import requests
url = "https://api.revring.ai/v1/agents/{id}/custom-tools"
payload = {
"name": "<string>",
"webhookUrl": "<string>",
"enabled": True,
"schema": {},
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": True,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": True,
"maxRetries": 0
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
webhookUrl: '<string>',
enabled: true,
schema: {},
headers: [{key: '<string>', value: '<string>'}],
queryParams: [{key: '<string>', value: '<string>'}],
sendRawRequestBody: true,
responseMode: 'sync',
timeoutSeconds: 60,
executionMessage: '<string>',
responseVariables: [{name: '<string>', path: '<string>'}],
speakAfterResult: true,
maxRetries: 0
})
};
fetch('https://api.revring.ai/v1/agents/{id}/custom-tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.revring.ai/v1/agents/{id}/custom-tools",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'webhookUrl' => '<string>',
'enabled' => true,
'schema' => [
],
'headers' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'queryParams' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'sendRawRequestBody' => true,
'responseMode' => 'sync',
'timeoutSeconds' => 60,
'executionMessage' => '<string>',
'responseVariables' => [
[
'name' => '<string>',
'path' => '<string>'
]
],
'speakAfterResult' => true,
'maxRetries' => 0
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.revring.ai/v1/agents/{id}/custom-tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.revring.ai/v1/agents/{id}/custom-tools")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revring.ai/v1/agents/{id}/custom-tools")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"webhookUrl": "<string>",
"enabled": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"schema": {},
"httpMethod": "GET",
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": true,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": true,
"maxRetries": 0
}
}{
"error": "invalid_body",
"details": {}
}{
"error": "unauthorized"
}{
"error": "billing_inactive"
}{
"error": "not_found"
}Agent Custom Tools
Create Custom Tool
Add a custom tool that the agent can invoke via function calling
POST
/
agents
/
{id}
/
custom-tools
Create Custom Tool
curl --request POST \
--url https://api.revring.ai/v1/agents/{id}/custom-tools \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"webhookUrl": "<string>",
"enabled": true,
"schema": {},
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": true,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": true,
"maxRetries": 0
}
'import requests
url = "https://api.revring.ai/v1/agents/{id}/custom-tools"
payload = {
"name": "<string>",
"webhookUrl": "<string>",
"enabled": True,
"schema": {},
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": True,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": True,
"maxRetries": 0
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
webhookUrl: '<string>',
enabled: true,
schema: {},
headers: [{key: '<string>', value: '<string>'}],
queryParams: [{key: '<string>', value: '<string>'}],
sendRawRequestBody: true,
responseMode: 'sync',
timeoutSeconds: 60,
executionMessage: '<string>',
responseVariables: [{name: '<string>', path: '<string>'}],
speakAfterResult: true,
maxRetries: 0
})
};
fetch('https://api.revring.ai/v1/agents/{id}/custom-tools', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.revring.ai/v1/agents/{id}/custom-tools",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'webhookUrl' => '<string>',
'enabled' => true,
'schema' => [
],
'headers' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'queryParams' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'sendRawRequestBody' => true,
'responseMode' => 'sync',
'timeoutSeconds' => 60,
'executionMessage' => '<string>',
'responseVariables' => [
[
'name' => '<string>',
'path' => '<string>'
]
],
'speakAfterResult' => true,
'maxRetries' => 0
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.revring.ai/v1/agents/{id}/custom-tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.revring.ai/v1/agents/{id}/custom-tools")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.revring.ai/v1/agents/{id}/custom-tools")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"webhookUrl\": \"<string>\",\n \"enabled\": true,\n \"schema\": {},\n \"headers\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"queryParams\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"sendRawRequestBody\": true,\n \"responseMode\": \"sync\",\n \"timeoutSeconds\": 60,\n \"executionMessage\": \"<string>\",\n \"responseVariables\": [\n {\n \"name\": \"<string>\",\n \"path\": \"<string>\"\n }\n ],\n \"speakAfterResult\": true,\n \"maxRetries\": 0\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"webhookUrl": "<string>",
"enabled": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"schema": {},
"httpMethod": "GET",
"headers": [
{
"key": "<string>",
"value": "<string>"
}
],
"queryParams": [
{
"key": "<string>",
"value": "<string>"
}
],
"sendRawRequestBody": true,
"responseMode": "sync",
"timeoutSeconds": 60,
"executionMessage": "<string>",
"responseVariables": [
{
"name": "<string>",
"path": "<string>"
}
],
"speakAfterResult": true,
"maxRetries": 0
}
}{
"error": "invalid_body",
"details": {}
}{
"error": "unauthorized"
}{
"error": "billing_inactive"
}{
"error": "not_found"
}Authorizations
API key for authentication. Generate API keys from the RevRing dashboard. A key is either full access or read-only; a read-only key is refused with 403 read_only_key on any request that creates, changes or deletes.
Path Parameters
Agent ID
Body
application/json
Maximum string length:
64Function definition: type function, a name, a description and JSON Schema parameters
HTTP method used when calling the webhook. Defaults to POST.
Available options:
GET, POST, PUT, PATCH, DELETE Custom HTTP headers to include in webhook requests
Show child attributes
Show child attributes
Custom query parameters appended to the webhook URL
Show child attributes
Show child attributes
When true, sends tool arguments directly as the request body instead of the default wrapper
How the agent treats the webhook call. sync: the agent waits for your webhook's response (up to the tool timeout) and can use it in the conversation. async: the agent acknowledges the tool call immediately and keeps the conversation going while your webhook is delivered in the background; the response is not used. Use async for side effects such as logging, CRM updates or notifications.
Available options:
sync, async Seconds a sync tool waits for the webhook before the agent moves on. Default 8.
Required range:
1 <= x <= 120A line the agent says while a slow sync tool runs, for example "One moment while I check that." The agent answers from the real result when it arrives. Empty or null: the agent waits without speaking.
Maximum string length:
300Fields of a successful JSON response saved as call variables for later tools, by name and response path (for example order.id).
Maximum array length:
20Show child attributes
Show child attributes
When false, the agent does not reply to the tool's result and keeps listening. Only for sync tools.
Extra attempts after a connection error or an HTTP 429, 502, 503 or 504 response, within the tool's time limit. A request that times out is not retried.
Required range:
0 <= x <= 3Response
Custom tool created
Custom function calling tool for agents
Show child attributes
Show child attributes