Criar ferramenta de chamada
curl --request POST \
--url https://suasofia.online/api/user/tools \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"body_format": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"static_fields": [
{
"key": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>",
"required": true
}
]
}
'import requests
url = "https://suasofia.online/api/user/tools"
payload = {
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"body_format": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"static_fields": [
{
"key": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>",
"required": True
}
]
}
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({
name: '<string>',
description: '<string>',
endpoint: '<string>',
method: '<string>',
body_format: '<string>',
timeout: 123,
headers: [{name: '<string>', value: '<string>'}],
static_fields: [{key: '<string>', value: '<string>'}],
schema: [{name: '<string>', type: '<string>', description: '<string>', required: true}]
})
};
fetch('https://suasofia.online/api/user/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://suasofia.online/api/user/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>',
'description' => '<string>',
'endpoint' => '<string>',
'method' => '<string>',
'body_format' => '<string>',
'timeout' => 123,
'headers' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'static_fields' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'schema' => [
[
'name' => '<string>',
'type' => '<string>',
'description' => '<string>',
'required' => true
]
]
]),
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://suasofia.online/api/user/tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\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://suasofia.online/api/user/tools")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://suasofia.online/api/user/tools")
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 \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"message": "Ferramenta criada com sucesso",
"data": {
"id": 1,
"name": "check_order_status",
"description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
"type": "http",
"endpoint": "https://api.yourstore.com/orders/{order_id}/status",
"method": "GET",
"body_format": "json",
"timeout": 10,
"headers": [
{
"name": "Content-Type",
"value": "application/json"
},
{
"name": "Authorization",
"value": "Bearer {{crm_key}}"
}
],
"static_fields": [
{
"key": "source",
"value": "suasofia"
},
{
"key": "caller",
"value": "{{customer_phone}}"
}
],
"schema": [
{
"name": "order_id",
"type": "string",
"description": "O ID do pedido do cliente",
"required": true
},
{
"name": "amount",
"type": "float",
"description": "Total do pedido como um decimal, ex: 19.99",
"required": false
},
{
"name": "priority_order",
"type": "boolean",
"description": "Se este é um pedido prioritário",
"required": false
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres).",
"errors": {
"name": [
"O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres)."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de chamada. Por favor, atualize seu plano para criar mais ferramentas."
}
Mid Call Tools
Criar ferramenta de chamada
Crie uma nova ferramenta de chamada
POST
/
user
/
tools
Criar ferramenta de chamada
curl --request POST \
--url https://suasofia.online/api/user/tools \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"body_format": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"static_fields": [
{
"key": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>",
"required": true
}
]
}
'import requests
url = "https://suasofia.online/api/user/tools"
payload = {
"name": "<string>",
"description": "<string>",
"endpoint": "<string>",
"method": "<string>",
"body_format": "<string>",
"timeout": 123,
"headers": [
{
"name": "<string>",
"value": "<string>"
}
],
"static_fields": [
{
"key": "<string>",
"value": "<string>"
}
],
"schema": [
{
"name": "<string>",
"type": "<string>",
"description": "<string>",
"required": True
}
]
}
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({
name: '<string>',
description: '<string>',
endpoint: '<string>',
method: '<string>',
body_format: '<string>',
timeout: 123,
headers: [{name: '<string>', value: '<string>'}],
static_fields: [{key: '<string>', value: '<string>'}],
schema: [{name: '<string>', type: '<string>', description: '<string>', required: true}]
})
};
fetch('https://suasofia.online/api/user/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://suasofia.online/api/user/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>',
'description' => '<string>',
'endpoint' => '<string>',
'method' => '<string>',
'body_format' => '<string>',
'timeout' => 123,
'headers' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'static_fields' => [
[
'key' => '<string>',
'value' => '<string>'
]
],
'schema' => [
[
'name' => '<string>',
'type' => '<string>',
'description' => '<string>',
'required' => true
]
]
]),
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://suasofia.online/api/user/tools"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\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://suasofia.online/api/user/tools")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://suasofia.online/api/user/tools")
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 \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"endpoint\": \"<string>\",\n \"method\": \"<string>\",\n \"body_format\": \"<string>\",\n \"timeout\": 123,\n \"headers\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"static_fields\": [\n {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"schema\": [\n {\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"description\": \"<string>\",\n \"required\": true\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"message": "Ferramenta criada com sucesso",
"data": {
"id": 1,
"name": "check_order_status",
"description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
"type": "http",
"endpoint": "https://api.yourstore.com/orders/{order_id}/status",
"method": "GET",
"body_format": "json",
"timeout": 10,
"headers": [
{
"name": "Content-Type",
"value": "application/json"
},
{
"name": "Authorization",
"value": "Bearer {{crm_key}}"
}
],
"static_fields": [
{
"key": "source",
"value": "suasofia"
},
{
"key": "caller",
"value": "{{customer_phone}}"
}
],
"schema": [
{
"name": "order_id",
"type": "string",
"description": "O ID do pedido do cliente",
"required": true
},
{
"name": "amount",
"type": "float",
"description": "Total do pedido como um decimal, ex: 19.99",
"required": false
},
{
"name": "priority_order",
"type": "boolean",
"description": "Se este é um pedido prioritário",
"required": false
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres).",
"errors": {
"name": [
"O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres)."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de chamada. Por favor, atualize seu plano para criar mais ferramentas."
}
Este endpoint permite que você crie uma nova ferramenta de chamada que pode ser usada pelos seus assistentes de IA para interagir com APIs externas durante as chamadas.
Parâmetros do Corpo
A API pública cria ferramentas de requisição HTTP. Ferramentas da Plataforma de Automação (que
geram um fluxo vinculado) são criadas a partir do painel. Os valores das ferramentas suportam
variáveis dinâmicas — use
{param} para parâmetros extraídos pela IA na URL, e
{{variavel}} (ex: {{customer_phone}}) na URL, valores de cabeçalho e valores de campo estáticos.string
required
Nome da ferramenta — letras, números e sublinhados, começando com uma letra ou sublinhado (máx 64 caracteres, ex:
get_weather, book_appointment)string
required
Explicação detalhada de quando e como a IA deve usar esta ferramenta (máx 255 caracteres)
string
required
URL válida do endpoint da API a ser chamada (máx 2048 caracteres)
string
required
Método HTTP:
GET, POST, PUT, PATCH ou DELETEstring
Como o corpo da requisição é codificado para métodos de escrita (POST/PUT/PATCH):
json (padrão) ou form (application/x-www-form-urlencoded)integer
Tempo limite da requisição em segundos (1-30, padrão: 10)
array
array
array
Parâmetros que a IA irá extrair da conversa e enviar para o endpoint
Show propriedades do esquema
Show propriedades do esquema
string
required
Nome do parâmetro (1-64 caracteres, deve começar com uma letra ou sublinhado, pode conter letras, números e sublinhados)
string
required
Tipo do parâmetro:
string, number, float ou booleanstring
required
Descrição para ajudar a IA a entender como extrair este parâmetro (3-255 caracteres)
boolean
Se a IA deve coletar este parâmetro. Parâmetros opcionais são enviados apenas quando um valor foi coletado. O padrão é
false.Campos de Resposta
string
Mensagem de sucesso
object
O objeto da ferramenta criada
Show propriedades dos dados
Show propriedades dos dados
integer
O identificador único da ferramenta
string
O nome da ferramenta
string
Descrição da ferramenta
string
Tipo da ferramenta:
http ou automationstring
URL do endpoint da API
string
Método HTTP
string
Codificação do corpo da requisição:
json ou forminteger
Tempo limite da requisição em segundos
array
Cabeçalhos HTTP
array
Pares chave/valor fixos sempre enviados com a requisição
array
Esquema de parâmetros
string
Timestamp ISO 8601
string
Timestamp ISO 8601
{
"message": "Ferramenta criada com sucesso",
"data": {
"id": 1,
"name": "check_order_status",
"description": "Use esta ferramenta para verificar o status do pedido de um cliente.",
"type": "http",
"endpoint": "https://api.yourstore.com/orders/{order_id}/status",
"method": "GET",
"body_format": "json",
"timeout": 10,
"headers": [
{
"name": "Content-Type",
"value": "application/json"
},
{
"name": "Authorization",
"value": "Bearer {{crm_key}}"
}
],
"static_fields": [
{
"key": "source",
"value": "suasofia"
},
{
"key": "caller",
"value": "{{customer_phone}}"
}
],
"schema": [
{
"name": "order_id",
"type": "string",
"description": "O ID do pedido do cliente",
"required": true
},
{
"name": "amount",
"type": "float",
"description": "Total do pedido como um decimal, ex: 19.99",
"required": false
},
{
"name": "priority_order",
"type": "boolean",
"description": "Se este é um pedido prioritário",
"required": false
}
],
"created_at": "2025-10-10T12:00:00.000000Z",
"updated_at": "2025-10-10T12:00:00.000000Z"
}
}
{
"message": "O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres).",
"errors": {
"name": [
"O nome da ferramenta deve começar com uma letra ou sublinhado e conter apenas letras, números e sublinhados (máx 64 caracteres)."
]
}
}
{
"message": "Você atingiu o limite do seu plano de 5 ferramentas de chamada. Por favor, atualize seu plano para criar mais ferramentas."
}
Anexando Ferramentas a Assistentes
Após criar uma ferramenta, você precisa anexá-la a um assistente para usá-la durante as chamadas. As ferramentas são gerenciadas através da API de Assistentes:- Criar Assistente - Use o parâmetro
tool_idspara anexar ferramentas ao criar um assistente - Atualizar Assistente - Use o parâmetro
tool_idspara adicionar, remover ou substituir ferramentas em um assistente existente