> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Agente

> Criar um novo agente de voz com configuração e ajustes especificados

# 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

```
POST /api/v1/agents
```

## Parâmetros de caminho

Nenhum

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Deve ser definido como `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="label" type="string" required>
  Rótulo do agente (máximo de 255 caracteres)
</ParamField>

<ParamField body="description" type="string" required={false}>
  Descrição do agente
</ParamField>

<ParamField body="name" type="string" required>
  Nome do agente (máximo de 255 caracteres)
</ParamField>

<ParamField body="language" type="string" required>
  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`.
</ParamField>

<ParamField body="initial_message" type="string" required={false}>
  Mensagem inicial que o agente irá dizer. Opcional.
</ParamField>

<ParamField body="interrupt_sensitivity" type="string" required>
  Quão facilmente o agente permite que o chamador o interrompa. Opções: `low`, `medium`, `high`.
</ParamField>

<ParamField body="endpointing_sensitivity" type="string" required>
  Quão agressivamente o agente detecta o fim da fala. Máximo de 255 caracteres.
</ParamField>

<ParamField body="ivr_navigation_mode" type="string" required>
  Comportamento de navegação em URA para chamadas de saída que encontram menus interativos. Máximo de 255 caracteres.
</ParamField>

<ParamField body="conversation_speed" type="number" required>
  Multiplicador de velocidade de reprodução da conversa. Faixa: `0.1`–`3.0`.
</ParamField>

<ParamField body="initial_message_delay" type="integer" required>
  Atraso em segundos antes do agente dizer a mensagem inicial. Faixa: `0`–`60`.
</ParamField>

<ParamField body="ask_if_human_present_on_idle" type="boolean" required>
  Quando `true`, o agente pergunta "Você ainda está aí?" após o tempo limite de inatividade em vez de encerrar a chamada.
</ParamField>

<ParamField body="idle_time_seconds" type="integer" required>
  Segundos de silêncio do chamador antes de acionar o comportamento de inatividade. Faixa: `1`–`60`.
</ParamField>

<ParamField body="max_idle_check_count" type="integer" required={false}>
  Número máximo de re-prompts de inatividade antes de encerrar a chamada. Faixa: `1`–`10`. Opcional.
</ParamField>

<ParamField body="max_call_duration_seconds" type="integer" required={false}>
  Limite máximo de duração da chamada em segundos. Faixa: `1`–`3600`. Opcional.
</ParamField>

<ParamField body="say_goodbye_on_max_duration" type="boolean" required={false}>
  Quando `true`, o agente diz uma mensagem de encerramento antes de terminar uma chamada que atinge `max_call_duration_seconds`. Opcional.
</ParamField>

<ParamField body="user_inactivity_timeout_seconds" type="integer" required={false}>
  Segundos de inatividade total antes do agente desistir completamente. Faixa: `5`–`120`. Opcional.
</ParamField>

<ParamField body="initial_idle_time_seconds" type="integer" required={false}>
  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.
</ParamField>

<ParamField body="initial_max_idle_check_count" type="integer" required={false}>
  Número máximo de prompts iniciais de inatividade antes de terminar. Faixa: `0`–`10`. Opcional.
</ParamField>

<ParamField body="llm_temperature" type="number" required>
  Temperatura de amostragem para o modelo de linguagem. Faixa: `0`–`2`. Valores menores tornam as respostas mais determinísticas.
</ParamField>

<ParamField body="enable_recording" type="boolean" required>
  Se as chamadas tratadas por este agente devem ser gravadas.
</ParamField>

<ParamField body="direction" type="string" required>
  Direção da chamada. Opções: `inbound`, `outbound`.
</ParamField>

<ParamField body="who_speaks_first" type="string" required>
  Quem fala primeiro. Opções: `agent`, `user`.
</ParamField>

<ParamField body="phone_number_ids" type="array" required={false}>
  Array de UUIDs de números de telefone a atribuir a este agente na criação. Use [Listar Números de Telefone](/api-reference/endpoints/list-phone-numbers) para recuperar os IDs disponíveis. Também pode ser definido posteriormente via [Atualizar Chamadas do Agente](/api-reference/endpoints/update-agent-calling).
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // Request 1: Create a basic inbound support agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // Request 2: Create an outbound sales agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (201 Created)

<ResponseExample>
  ```json theme={null}
  {
    "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": []
    }
  }
  ```
</ResponseExample>

## Respostas de erro

### Erro de Validação (422)

<ResponseExample>
  ```json theme={null}
  {
    "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."
      ]
    }
  }
  ```
</ResponseExample>

### Erro Não Autorizado (401)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### Muitas Requisições (429)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>