Criar Agente
Criar um novo agente de voz com configuração, ajustes de voz e parâmetros de comportamento especificados. O agente será criado com status de rascunho e pode ser publicado posteriormente.
Endpoint
Parâmetros de caminho
Nenhum
Cabeçalhos da requisição
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here
Deve ser definido como application/json
Corpo da requisição
Rótulo do agente (máximo de 255 caracteres)
Nome do agente (máximo de 255 caracteres)
Código de idioma do agente. Valores suportados: pt-BR, pt-PT, en-US, en-CA, es-ES, fr-FR, de-DE, it-IT, nl-NL, ja-JP, ko-KR, zh-TW.
Mensagem inicial que o agente irá dizer. Opcional.
Quão facilmente o agente permite que o chamador o interrompa. Opções: low, medium, high.
Quão agressivamente o agente detecta o fim da fala. Máximo de 255 caracteres.
Comportamento de navegação em URA para chamadas de saída que encontram menus interativos. Máximo de 255 caracteres.
Multiplicador de velocidade de reprodução da conversa. Faixa: 0.1–3.0.
Atraso em segundos antes do agente dizer a mensagem inicial. Faixa: 0–60.
ask_if_human_present_on_idle
Quando true, o agente pergunta “Você ainda está aí?” após o tempo limite de inatividade em vez de encerrar a chamada.
Segundos de silêncio do chamador antes de acionar o comportamento de inatividade. Faixa: 1–60.
Número máximo de re-prompts de inatividade antes de encerrar a chamada. Faixa: 1–10. Opcional.
max_call_duration_seconds
Limite máximo de duração da chamada em segundos. Faixa: 1–3600. Opcional.
say_goodbye_on_max_duration
Quando true, o agente diz uma mensagem de encerramento antes de terminar uma chamada que atinge max_call_duration_seconds. Opcional.
user_inactivity_timeout_seconds
Segundos de inatividade total antes do agente desistir completamente. Faixa: 5–120. Opcional.
initial_idle_time_seconds
Limite de inatividade a usar antes do agente ter dito sua mensagem inicial (lida com casos em que a linha abre, mas o chamador não fala). Faixa: 1–60. Opcional.
initial_max_idle_check_count
Número máximo de prompts iniciais de inatividade antes de terminar. Faixa: 0–10. Opcional.
Temperatura de amostragem para o modelo de linguagem. Faixa: 0–2. Valores menores tornam as respostas mais determinísticas.
Se as chamadas tratadas por este agente devem ser gravadas.
Direção da chamada. Opções: inbound, outbound.
Quem fala primeiro. Opções: agent, user.
Exemplos de Requisição
# Request 1: Create a basic inbound support agent
curl -X POST "https://app.talkover.ai/api/v1/agents" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"name": "SupportBot",
"language": "en-US",
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"endpointing_sensitivity": "auto",
"ivr_navigation_mode": "off",
"conversation_speed": 1.0,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"idle_time_seconds": 5,
"llm_temperature": 0.7,
"enable_recording": true,
"direction": "inbound",
"who_speaks_first": "agent"
}'
# Request 2: Create an outbound sales agent
curl -X POST "https://app.talkover.ai/api/v1/agents" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"label": "Sales Agent",
"description": "Outbound sales calls for product demos",
"name": "SalesBot",
"language": "en-US",
"initial_message": "Hi, this is SalesBot calling about our new product. Do you have a moment?",
"interrupt_sensitivity": "high",
"endpointing_sensitivity": "auto",
"ivr_navigation_mode": "off",
"conversation_speed": 1.2,
"initial_message_delay": 2,
"ask_if_human_present_on_idle": true,
"idle_time_seconds": 10,
"llm_temperature": 0.8,
"enable_recording": true,
"direction": "outbound",
"who_speaks_first": "agent"
}'
Resposta
Resposta de Sucesso (201 Created)
{
"success": true,
"message": "Agent created successfully",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SupportBot",
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"language": "en-US",
"voice": null,
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"conversation_speed": 1.0,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"direction": "inbound",
"who_speaks_first": "agent",
"current_status": "draft",
"is_sandbox": false,
"is_ready_to_publish": false,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"trainings": [],
"actions": [],
"phone_numbers": []
}
}
Respostas de erro
Erro de Validação (422)
{
"success": false,
"message": "The given data was invalid.",
"errors": {
"name": [
"The name field is required."
],
"label": [
"The label field is required."
],
"language": [
"The selected language is invalid."
],
"interrupt_sensitivity": [
"The selected interrupt sensitivity is invalid."
],
"direction": [
"The selected direction is invalid."
],
"conversation_speed": [
"The conversation speed must be between 0.1 and 3.0."
],
"initial_message_delay": [
"The initial message delay must be between 0 and 60."
],
"llm_temperature": [
"The llm temperature must be between 0 and 2."
],
"idle_time_seconds": [
"The idle time seconds must be between 1 and 300."
]
}
}
Erro Não Autorizado (401)
{
"success": false,
"message": "Unauthenticated."
}
Muitas Requisições (429)
{
"success": false,
"message": "Too many requests. Please try again later."
}
