Pular para o conteúdo

POST /v1/agents

POST
/v1/agents
curl --request POST \
--url https://seu-endereco-da-api/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "avatar": "example", "description": "example", "model": "example", "instructions": "example" }'

Permissão que a Chave de acesso precisa: Gerenciar agentes de IA (agents:manage).

Media typeapplication/json
object
name
required
string
>= 1 characters <= 80 characters
avatar
required
string
description
required
string
model
string
instructions
required
string

Example generated

{
"name": "example",
"avatar": "example",
"description": "example",
"model": "example",
"instructions": "example"
}
Media typeapplication/json
object
id
required
string
name
required
string
avatar
required
string
description
required
string
status
required

Active answers its channels; flows answers only when a flow block or another AI passes it the conversation, and never holds a channel; paused and draft answer no one (draft still answers its test phone)

string
Allowed values: active flows paused draft
model
required
string
temperature
required
number
instructions
required
string
testPhone
required
string
nullable
businessHoursConfigId
required

Business hours the agent follows; null keeps the agent answering at any time

string format: uuid
nullable
outOfHours
required

What the agent does outside the business hours: tell the customer the right hours, or stay silent

string
Allowed values: avisar calado
forbiddenSubjects
required

Subjects the owner forbids the agent to talk about, added on top of the fixed rules; empty keeps the agent as it always was

Array<string>
attemptLimit
required

Consecutive turns without understanding before the agent hands off to a person; null never hands off for this reason

number
nullable >= 1 <= 10
typingWaitSeconds
required

Seconds the agent waits after the customer’s last message before answering, so a burst of short messages gets one reply; null answers each message at once

number
nullable >= 2 <= 10
understandAudio
required

True turns the customer’s audio into text before the agent answers, charged to the AI credit; false makes the agent ask the customer to write.

boolean
voiceReply
required

When the agent answers with a voice note generated from its reply, charged to the AI credit: never, only when the customer’s last message was audio, or always; replies with buttons or a list stay as text

string
Allowed values: never when_customer_audio always
voice
required

Voice of the agent’s voice notes

string
Allowed values: alloy ash ballad coral echo fable nova onyx sage shimmer verse
channelIds
required
Array<string>
intents
required
Array<object>
object
updatedAt
required
string format: date-time
template
required

Ready-made AI the agent was created from; null for an agent written by hand

object
id
required
string format: uuid
slug
required
string
name
required
string
version
required

Template version the agent follows

number

Example

{
"status": "active",
"outOfHours": "avisar",
"voiceReply": "never",
"voice": "alloy"
}