Create an app action tool
curl --request POST \
--url https://app.famulor.io/api/v1/tools/app-actions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"use_when": "<string>",
"version": "<string>",
"name": "<string>",
"description_override": "<string>",
"fields": [
{
"path": "<string>",
"key": "<string>",
"value": "<unknown>",
"variable": "<string>",
"param": "<string>",
"description": "<string>",
"label": "<string>",
"required": true
}
],
"result_config": {
"paths": [
"<string>"
],
"max_chars": 1850
},
"is_active": true,
"assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://app.famulor.io/api/v1/tools/app-actions"
payload = {
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"use_when": "<string>",
"version": "<string>",
"name": "<string>",
"description_override": "<string>",
"fields": [
{
"path": "<string>",
"key": "<string>",
"value": "<unknown>",
"variable": "<string>",
"param": "<string>",
"description": "<string>",
"label": "<string>",
"required": True
}
],
"result_config": {
"paths": ["<string>"],
"max_chars": 1850
},
"is_active": True,
"assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connection_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
action: '<string>',
use_when: '<string>',
version: '<string>',
name: '<string>',
description_override: '<string>',
fields: [
{
path: '<string>',
key: '<string>',
value: '<unknown>',
variable: '<string>',
param: '<string>',
description: '<string>',
label: '<string>',
required: true
}
],
result_config: {paths: ['<string>'], max_chars: 1850},
is_active: true,
assistant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://app.famulor.io/api/v1/tools/app-actions', 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://app.famulor.io/api/v1/tools/app-actions",
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([
'connection_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'action' => '<string>',
'use_when' => '<string>',
'version' => '<string>',
'name' => '<string>',
'description_override' => '<string>',
'fields' => [
[
'path' => '<string>',
'key' => '<string>',
'value' => '<unknown>',
'variable' => '<string>',
'param' => '<string>',
'description' => '<string>',
'label' => '<string>',
'required' => true
]
],
'result_config' => [
'paths' => [
'<string>'
],
'max_chars' => 1850
],
'is_active' => true,
'assistant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://app.famulor.io/api/v1/tools/app-actions"
payload := strings.NewReader("{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://app.famulor.io/api/v1/tools/app-actions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.famulor.io/api/v1/tools/app-actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"tool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"binding_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"is_active": true,
"app": "<string>",
"app_name": "<string>",
"action": "<string>",
"action_name": "<string>",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"risk": "read",
"confirmation": "ask_first",
"status": "ok",
"update_available": true,
"version": "<string>",
"fields": [
{
"key": "<string>",
"path": "<string>",
"label": "<string>",
"type": "string",
"required": true,
"allowed_modes": [
"ai"
],
"mode": "ai",
"items": "string",
"columns": [
{
"key": "<string>",
"label": "<string>",
"type": "string",
"required": true,
"enum": [
"<string>"
],
"format": "date"
}
],
"cell_type": "string",
"enum": [
"<string>"
],
"format": "date",
"param": "<string>",
"provider_description": "<string>",
"description": "<string>",
"value": "<unknown>",
"variable": "<string>",
"example": "<string>",
"default_value": "<unknown>"
}
],
"model": {
"use_when": "<string>",
"description_override": "<string>"
},
"result_config": {
"mode": "auto",
"max_chars": 1850,
"paths": [
"<string>"
]
},
"revision": 2
}
}Tools
Create an app action tool
Turn one action of a connected app into a reusable tool the assistant can call during conversations. The tool uses the action’s current version; fields you leave out keep their suggested setting. Pass assistant_id to assign the tool right away, or assign it later with PUT /assistants/{id}/tools; an unknown assistant_id returns 404 before anything is created. If the tool is saved but cannot be assigned, the response is 409 with code assignment_failed and error.details.tool_id: assign that tool with PUT /assistants/{id}/tools instead of creating it again. Requires Beta features in the workspace, Automations in the plan, room under the tool limit and an owner or admin credential. Requires both assistants:write and automations:write.
POST
/
tools
/
app-actions
Create an app action tool
curl --request POST \
--url https://app.famulor.io/api/v1/tools/app-actions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"use_when": "<string>",
"version": "<string>",
"name": "<string>",
"description_override": "<string>",
"fields": [
{
"path": "<string>",
"key": "<string>",
"value": "<unknown>",
"variable": "<string>",
"param": "<string>",
"description": "<string>",
"label": "<string>",
"required": true
}
],
"result_config": {
"paths": [
"<string>"
],
"max_chars": 1850
},
"is_active": true,
"assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://app.famulor.io/api/v1/tools/app-actions"
payload = {
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"action": "<string>",
"use_when": "<string>",
"version": "<string>",
"name": "<string>",
"description_override": "<string>",
"fields": [
{
"path": "<string>",
"key": "<string>",
"value": "<unknown>",
"variable": "<string>",
"param": "<string>",
"description": "<string>",
"label": "<string>",
"required": True
}
],
"result_config": {
"paths": ["<string>"],
"max_chars": 1850
},
"is_active": True,
"assistant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connection_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
action: '<string>',
use_when: '<string>',
version: '<string>',
name: '<string>',
description_override: '<string>',
fields: [
{
path: '<string>',
key: '<string>',
value: '<unknown>',
variable: '<string>',
param: '<string>',
description: '<string>',
label: '<string>',
required: true
}
],
result_config: {paths: ['<string>'], max_chars: 1850},
is_active: true,
assistant_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://app.famulor.io/api/v1/tools/app-actions', 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://app.famulor.io/api/v1/tools/app-actions",
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([
'connection_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'action' => '<string>',
'use_when' => '<string>',
'version' => '<string>',
'name' => '<string>',
'description_override' => '<string>',
'fields' => [
[
'path' => '<string>',
'key' => '<string>',
'value' => '<unknown>',
'variable' => '<string>',
'param' => '<string>',
'description' => '<string>',
'label' => '<string>',
'required' => true
]
],
'result_config' => [
'paths' => [
'<string>'
],
'max_chars' => 1850
],
'is_active' => true,
'assistant_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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://app.famulor.io/api/v1/tools/app-actions"
payload := strings.NewReader("{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://app.famulor.io/api/v1/tools/app-actions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.famulor.io/api/v1/tools/app-actions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"connection_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"action\": \"<string>\",\n \"use_when\": \"<string>\",\n \"version\": \"<string>\",\n \"name\": \"<string>\",\n \"description_override\": \"<string>\",\n \"fields\": [\n {\n \"path\": \"<string>\",\n \"key\": \"<string>\",\n \"value\": \"<unknown>\",\n \"variable\": \"<string>\",\n \"param\": \"<string>\",\n \"description\": \"<string>\",\n \"label\": \"<string>\",\n \"required\": true\n }\n ],\n \"result_config\": {\n \"paths\": [\n \"<string>\"\n ],\n \"max_chars\": 1850\n },\n \"is_active\": true,\n \"assistant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"tool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"binding_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"is_active": true,
"app": "<string>",
"app_name": "<string>",
"action": "<string>",
"action_name": "<string>",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"risk": "read",
"confirmation": "ask_first",
"status": "ok",
"update_available": true,
"version": "<string>",
"fields": [
{
"key": "<string>",
"path": "<string>",
"label": "<string>",
"type": "string",
"required": true,
"allowed_modes": [
"ai"
],
"mode": "ai",
"items": "string",
"columns": [
{
"key": "<string>",
"label": "<string>",
"type": "string",
"required": true,
"enum": [
"<string>"
],
"format": "date"
}
],
"cell_type": "string",
"enum": [
"<string>"
],
"format": "date",
"param": "<string>",
"provider_description": "<string>",
"description": "<string>",
"value": "<unknown>",
"variable": "<string>",
"example": "<string>",
"default_value": "<unknown>"
}
],
"model": {
"use_when": "<string>",
"description_override": "<string>"
},
"result_config": {
"mode": "auto",
"max_chars": 1850,
"paths": [
"<string>"
]
},
"revision": 2
}
}Authorizations
API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, loop:read, loop:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, billing:write, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access within the workspace's available capabilities.
Body
application/json
ID of the connected-app connection from GET /automations/connections.
Action ID from GET /automations/connections/{id}/actions.
Pattern:
^[A-Za-z0-9][A-Za-z0-9_.-]{0,199}$When the assistant should use the tool, for example When the caller asks for a callback.
Required string length:
10 - 1000version returned with the action. If the action has changed since, the request fails with 409. Omit it to use the current version.
Required string length:
1 - 200Tool name the assistant sees. Null or omitted generates one from the app and the action.
Pattern:
^[a-zA-Z][a-zA-Z0-9_-]{0,63}$Replaces the generated tool description the assistant sees. Null uses the generated one.
Maximum string length:
900Field settings, matched by path (or by key when path is missing). Fields you leave out keep their suggested setting. Send the fields as they were returned or only the ones you change.
Maximum array length:
300Show child attributes
Show child attributes
ask_first: before an action changes data, the assistant reads the values back and calls the tool again to run it. In messaging and email the second call runs only after a new customer message. On calls and in web chat it runs when it comes at least 4 seconds after the read-back, whether or not the customer answered. ask_first is not a consent record. none: the action runs at once. Defaults to ask_first for actions that change data; actions that only read never ask.
Available options:
ask_first, none How much of the app's result the assistant reads. Null uses the defaults.
Show child attributes
Show child attributes
Whether assistants can use the tool.
Assistant that gets the new tool assigned.
Response
Created. The tool also appears in GET /tools.
An app action tool with its settings.
Show child attributes
Show child attributes