Skip to main content
POST
/
v1
/
voice-agents
/
web-tool
Create a new web tool.
curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents/web-tool \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "FUNCTION",
  "name": "Weather API Tool",
  "toolSettings": {
    "serverUrl": "https://api.example.com/webhook",
    "methodType": "POST",
    "authToken": "bearer_token_12345",
    "timeOut": 15,
    "httpHeaders": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "pathParameters": {
      "userId": "12345"
    }
  },
  "description": "A tool that fetches current weather information for a given location.",
  "async": true,
  "messages": [
    {
      "type": "system",
      "content": "You are a helpful weather assistant."
    }
  ],
  "params": {
    "type": "object",
    "properties": {
      "test": {
        "type": "number",
        "description": "Hello world from Hamsa AI!"
      }
    },
    "required": [
      "test"
    ]
  }
}
'
import requests

url = "https://api.tryhamsa.com/v1/voice-agents/web-tool"

payload = {
    "type": "FUNCTION",
    "name": "Weather API Tool",
    "toolSettings": {
        "serverUrl": "https://api.example.com/webhook",
        "methodType": "POST",
        "authToken": "bearer_token_12345",
        "timeOut": 15,
        "httpHeaders": {
            "Content-Type": "application/json",
            "Authorization": "Bearer token"
        },
        "pathParameters": { "userId": "12345" }
    },
    "description": "A tool that fetches current weather information for a given location.",
    "async": True,
    "messages": [
        {
            "type": "system",
            "content": "You are a helpful weather assistant."
        }
    ],
    "params": {
        "type": "object",
        "properties": { "test": {
                "type": "number",
                "description": "Hello world from Hamsa AI!"
            } },
        "required": ["test"]
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'FUNCTION',
    name: 'Weather API Tool',
    toolSettings: {
      serverUrl: 'https://api.example.com/webhook',
      methodType: 'POST',
      authToken: 'bearer_token_12345',
      timeOut: 15,
      httpHeaders: {'Content-Type': 'application/json', Authorization: 'Bearer token'},
      pathParameters: {userId: '12345'}
    },
    description: 'A tool that fetches current weather information for a given location.',
    async: true,
    messages: [{type: 'system', content: 'You are a helpful weather assistant.'}],
    params: {
      type: 'object',
      properties: {test: {type: 'number', description: 'Hello world from Hamsa AI!'}},
      required: ['test']
    }
  })
};

fetch('https://api.tryhamsa.com/v1/voice-agents/web-tool', 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.tryhamsa.com/v1/voice-agents/web-tool",
  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([
    'type' => 'FUNCTION',
    'name' => 'Weather API Tool',
    'toolSettings' => [
        'serverUrl' => 'https://api.example.com/webhook',
        'methodType' => 'POST',
        'authToken' => 'bearer_token_12345',
        'timeOut' => 15,
        'httpHeaders' => [
                'Content-Type' => 'application/json',
                'Authorization' => 'Bearer token'
        ],
        'pathParameters' => [
                'userId' => '12345'
        ]
    ],
    'description' => 'A tool that fetches current weather information for a given location.',
    'async' => true,
    'messages' => [
        [
                'type' => 'system',
                'content' => 'You are a helpful weather assistant.'
        ]
    ],
    'params' => [
        'type' => 'object',
        'properties' => [
                'test' => [
                                'type' => 'number',
                                'description' => 'Hello world from Hamsa AI!'
                ]
        ],
        'required' => [
                'test'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$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.tryhamsa.com/v1/voice-agents/web-tool"

	payload := strings.NewReader("{\n  \"type\": \"FUNCTION\",\n  \"name\": \"Weather API Tool\",\n  \"toolSettings\": {\n    \"serverUrl\": \"https://api.example.com/webhook\",\n    \"methodType\": \"POST\",\n    \"authToken\": \"bearer_token_12345\",\n    \"timeOut\": 15,\n    \"httpHeaders\": {\n      \"Content-Type\": \"application/json\",\n      \"Authorization\": \"Bearer token\"\n    },\n    \"pathParameters\": {\n      \"userId\": \"12345\"\n    }\n  },\n  \"description\": \"A tool that fetches current weather information for a given location.\",\n  \"async\": true,\n  \"messages\": [\n    {\n      \"type\": \"system\",\n      \"content\": \"You are a helpful weather assistant.\"\n    }\n  ],\n  \"params\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"test\": {\n        \"type\": \"number\",\n        \"description\": \"Hello world from Hamsa AI!\"\n      }\n    },\n    \"required\": [\n      \"test\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<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.tryhamsa.com/v1/voice-agents/web-tool")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"FUNCTION\",\n  \"name\": \"Weather API Tool\",\n  \"toolSettings\": {\n    \"serverUrl\": \"https://api.example.com/webhook\",\n    \"methodType\": \"POST\",\n    \"authToken\": \"bearer_token_12345\",\n    \"timeOut\": 15,\n    \"httpHeaders\": {\n      \"Content-Type\": \"application/json\",\n      \"Authorization\": \"Bearer token\"\n    },\n    \"pathParameters\": {\n      \"userId\": \"12345\"\n    }\n  },\n  \"description\": \"A tool that fetches current weather information for a given location.\",\n  \"async\": true,\n  \"messages\": [\n    {\n      \"type\": \"system\",\n      \"content\": \"You are a helpful weather assistant.\"\n    }\n  ],\n  \"params\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"test\": {\n        \"type\": \"number\",\n        \"description\": \"Hello world from Hamsa AI!\"\n      }\n    },\n    \"required\": [\n      \"test\"\n    ]\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.tryhamsa.com/v1/voice-agents/web-tool")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"FUNCTION\",\n  \"name\": \"Weather API Tool\",\n  \"toolSettings\": {\n    \"serverUrl\": \"https://api.example.com/webhook\",\n    \"methodType\": \"POST\",\n    \"authToken\": \"bearer_token_12345\",\n    \"timeOut\": 15,\n    \"httpHeaders\": {\n      \"Content-Type\": \"application/json\",\n      \"Authorization\": \"Bearer token\"\n    },\n    \"pathParameters\": {\n      \"userId\": \"12345\"\n    }\n  },\n  \"description\": \"A tool that fetches current weather information for a given location.\",\n  \"async\": true,\n  \"messages\": [\n    {\n      \"type\": \"system\",\n      \"content\": \"You are a helpful weather assistant.\"\n    }\n  ],\n  \"params\": {\n    \"type\": \"object\",\n    \"properties\": {\n      \"test\": {\n        \"type\": \"number\",\n        \"description\": \"Hello world from Hamsa AI!\"\n      }\n    },\n    \"required\": [\n      \"test\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "success": false,
  "message": "success",
  "data": {
    "id": "d949f13f-40d2-4e48-ac86-b66633070603",
    "persistentId": "cmjx8qzw0000004kz3jek1ktu",
    "version": 1,
    "name": "Weather API Tool",
    "type": "FUNCTION",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "d949f13f-40d2-4e48-ac86-b66633070603",
    "isActive": true,
    "async": true,
    "description": "A tool that fetches current weather information for a given location.",
    "collectionId": "550e8400-e29b-41d4-a716-446655440000",
    "toolSettings": {
      "serverUrl": "https://api.example.com/webhook",
      "httpHeaders": {
        "Content-Type": "application/json",
        "Authorization": "Bearer token"
      },
      "pathParameters": {
        "userId": "12345"
      },
      "timeout": 5000,
      "authToken": "bearer_token_12345",
      "methodType": "POST"
    },
    "params": {
      "location": {
        "type": "string",
        "description": "The location to get weather for"
      }
    },
    "messages": [
      {
        "type": "system",
        "content": "You are a helpful weather assistant."
      }
    ]
  }
}
{
  "code": 123,
  "message": "<string>"
}
{
  "code": 123,
  "message": "<string>"
}
{
  "code": 123,
  "message": "<string>"
}

Authorizations

​
Authorization
string
header
required

Pass the API key in the Authorization header, You need to put Token keyword before the API key. e.g. 'Authorization: Token '

Body

application/json
​
type
enum<string>
required

The type of the web tool.

Available options:
FUNCTION,
MCP
Example:

"FUNCTION"

​
name
string
required

The name of the web tool.

Required string length: 1 - 250
Example:

"Weather API Tool"

​
toolSettings
object
required

Server configuration settings for the web tool.

​
description
string

A description of what the web tool does.

Required string length: 1 - 1000
Example:

"A tool that fetches current weather information for a given location."

​
async
boolean

Whether the tool should run asynchronously. Required when type is FUNCTION, not allowed when type is MCP.

Example:

true

​
messages
object[]

Array of message configurations for the web tool. Each message type must be unique.

Example:
[
  {
    "type": "system",
    "content": "You are a helpful weather assistant."
  }
]
​
params
object

Parameter schema definition for the web tool. Not allowed when type is MCP. This field is a recursive OpenAPI-style shape with 'type', 'properties', 'required', 'items', ...etc. Please refer to the OpenAPI specification for more information.

Example:
{
  "type": "object",
  "properties": {
    "test": {
      "type": "number",
      "description": "Hello world from Hamsa AI!"
    }
  },
  "required": ["test"]
}

Response

Successful response

​
success
boolean
default:false
​
message
string
default:success
​
data
object