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

# Atualizar assistente

> Atualizar a configuração de um assistente de IA existente

Este endpoint permite atualizar as configurações de um assistente de IA existente. Todos os campos são opcionais - forneça apenas os campos que deseja atualizar.

### Parâmetros de Caminho

<ParamField path="id" type="integer" required>
  O identificador único do assistente a ser atualizado
</ParamField>

### Corpo da Requisição

#### Campos Principais

<ParamField body="assistant_name" type="string" optional>
  O nome do assistente (máximo 255 caracteres)
</ParamField>

<ParamField body="voice_id" type="integer" optional>
  O ID da voz a ser usada para o assistente (deve existir nas vozes disponíveis)
</ParamField>

<ParamField body="language" type="string" optional>
  O nome do idioma para o assistente (máximo 100 caracteres)
</ParamField>

<ParamField body="llm_model" type="string" optional>
  O nome do modelo LLM a ser usado (máximo 100 caracteres)
</ParamField>

<ParamField body="calls_direction" type="string" optional>
  O tipo de direção da chamada. Opções: `receive`, `make`
</ParamField>

<ParamField body="engine_type" type="string" optional>
  O tipo de engine a ser usado. Opções: `pipeline`, `multimodal`
</ParamField>

<ParamField body="timezone" type="string" optional>
  O fuso horário para o assistente (ex: "America/New\_York")
</ParamField>

<ParamField body="initial_message" type="string" optional>
  A mensagem inicial que o assistente falará quando a chamada iniciar
</ParamField>

<ParamField body="system_prompt" type="string" optional>
  O prompt do sistema que define o comportamento e personalidade do assistente
</ParamField>

#### Configuração Opcional

<ParamField body="phone_number_id" type="integer" optional>
  O ID de um número de telefone para atribuir ao assistente (defina como null para desatribuir)
</ParamField>

<ParamField body="tool_ids" type="integer[]" optional>
  Array de IDs de ferramentas de meio de chamada para sincronizar com o assistente. Substitui todas as atribuições de ferramentas existentes. Passe um array vazio para remover todas as ferramentas. Cada elemento deve ser um ID de ferramenta válido que pertença à sua conta.
</ParamField>

<ParamField body="endpoint_type" type="string" optional>
  Tipo de detecção de atividade de voz. Opções: `vad`, `ai`
</ParamField>

<ParamField body="endpoint_sensitivity" type="number" optional>
  Nível de sensibilidade do endpoint (0-5)
</ParamField>

<ParamField body="interrupt_sensitivity" type="number" optional>
  Nível de sensibilidade de interrupção (0-5)
</ParamField>

<ParamField body="ambient_sound_volume" type="number" optional>
  Nível de volume do som ambiente (0-1)
</ParamField>

<ParamField body="post_call_evaluation" type="boolean" optional>
  Se deve ativar a avaliação pós-chamada
</ParamField>

<ParamField body="send_webhook_only_on_completed" type="boolean" optional>
  Se deve enviar webhooks apenas em chamadas concluídas
</ParamField>

#### Ferramentas Integradas

<ParamField body="tools" type="array">
  Array de ferramentas integradas. **Substitui todas as ferramentas integradas existentes.** Passe um array vazio `[]` para remover todas as ferramentas.

  <Expandable title="Tipos de ferramentas">
    **call\_transfer** - Transferir a chamada para outro número de telefone

    * `phone_number` (obrigatório): Número de telefone para transferir
    * `description`: Quando transferir a chamada
    * `custom`: Se verdadeiro, a IA pode determinar o número de transferência dinamicamente
    * `timezone`: Fuso horário para disponibilidade de transferência
    * `warm_transfer`: Enviar uma mensagem para o cliente antes de transferir (padrão: `false`)
    * `warm_transfer_message`: Prompt dizendo à IA o que falar antes de transferir (ex.: "Informe ao cliente que a chamada está sendo transferida.")

    **warm\_call\_transfer** - Transferência aquecida com briefing do supervisor

    * `supervisor_phone` (obrigatório): Número de telefone para discar para a transferência aquecida (ex.: "+14155552001"). Se `custom_sip` estiver ativado, este é um endereço SIP ou extensão interna.
    * `outbound_phone_id` (obrigatório): ID do número de telefone usado para discar para o supervisor.
    * `description` (obrigatório): **Quando transferir** — descreve quando a IA deve iniciar a transferência aquecida (ex.: "Transferir a chamada para um supervisor humano quando o cliente solicitar falar com uma pessoa real.")
    * `custom_sip`: Ativar para inserir um endereço SIP personalizado ou extensão interna em vez de um número de telefone (padrão: `false`)
    * `caller_id_mode`: Qual número de telefone o supervisor vê ao receber a chamada. Opções: `outbound_number` (padrão — mostra o número de saída), `customer_number` (mostra o número do chamador), `custom` (mostra um número personalizado)
    * `custom_caller_id`: Número de telefone personalizado mostrado ao supervisor. Usado apenas quando `caller_id_mode` é `custom`.
    * `hold_music`: Áudio tocado para o chamador enquanto em espera. Opções: `hold_music` (padrão — toca música de espera padrão), `none` (silêncio, sem música)
    * `hold_music_volume`: Nível de volume para música de espera, 0-100 (padrão: `80`)
    * `hold_message`: Mensagem falada para o chamador antes de colocá-lo em espera (padrão: "Por favor aguarde enquanto eu conecto você com um supervisor.")
    * `summary_instructions`: Instruções para como a IA deve informar o supervisor sobre a chamada (padrão: "Apresente a conversa da sua perspectiva:\n- QUEM está ligando (nome, empresa se mencionado)\n- POR QUE ligaram (seu objetivo ou problema)\n- POR QUE um humano é necessário neste momento\n\nMantenha breve (2-3 frases).")
    * `briefing_initial_message`: A primeira mensagem que a IA diz ao supervisor quando ele atende (padrão: "Olá! Tenho um chamador na linha que precisa da sua assistência. Posso informá-lo sobre a situação?")
    * `connected_message`: Mensagem falada ao chamador após o supervisor ser conectado (padrão: "Você está agora conectado com um supervisor. Vou deixá-los conversarem.")

    **end\_call** - Encerrar a chamada programaticamente

    * `description`: Quando a IA deve encerrar a chamada

    **dtmf\_input** - Enviar tons DTMF (entrada de teclado)

    * `description`: Quando usar entrada DTMF (para navegação IVR)

    **collect\_keypad** - Coletar entrada de teclado do chamador

    * `timeout`: Segundos para aguardar entrada, 1-30 (padrão: 5)
    * `stop_key`: Tecla que encerra a entrada. Opções: `#` (padrão), `*`

    **calendar\_integration** - Agendar compromissos via Cal.com

    * `calcom_api_key` (obrigatório): Sua chave API do Cal.com
    * `calcom_event_slug` (obrigatório): O slug do tipo de evento do Cal.com
    * `calcom_team_slug`: Slug da equipe se o evento pertencer a uma equipe Cal.com
    * `calcom_endpoint`: Região da API Cal.com. Opções: `us` (padrão — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (usa `calcom_custom_endpoint`)
    * `calcom_custom_endpoint`: URL base da API Cal.com personalizada. Usado apenas quando `calcom_endpoint` é `custom` (ex.: `https://my-calcom-instance.com`).
    * `calcom_booking_fields`: Array de campos de reserva personalizados para o evento. Cada campo tem:
      * `slug` (obrigatório): Identificador do campo
      * `type` (obrigatório): Tipo do campo (ex.: "text", "email", "phone", "select")
      * `label` (obrigatório): Rótulo de exibição
      * `required`: Se o campo é obrigatório (padrão: `false`)
      * `options`: Array de opções para campos select
    * `description`: Quando oferecer agendamento
  </Expandable>

  ```json theme={null}
  "tools": [
    {
      "type": "dtmf_input",
      "description": "Navigate IVR when needed"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567890",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it."
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    },
    {
      "type": "end_call",
      "description": "End call when done"
    }
  ]
  ```
</ParamField>

#### Configuração de Webhook

<ParamField body="is_webhook_active" type="boolean" optional>
  Se as notificações de webhook estão ativadas
</ParamField>

<ParamField body="webhook_url" type="string" optional>
  A URL do webhook para notificações pós-chamada (pode ser definida como null para remover)
</ParamField>

#### Configurações de Interrupção

<ParamField body="use_min_interrupt_words" type="boolean" optional>
  Se deve usar a configuração de palavras mínimas de interrupção
</ParamField>

<ParamField body="min_interrupt_words" type="integer" optional>
  Número mínimo de palavras antes que a interrupção seja permitida (0-10)
</ParamField>

#### Variáveis e Esquema

<ParamField body="variables" type="object" optional>
  Pares chave-valor de variáveis personalizadas para o assistente
</ParamField>

<ParamField body="synthesizer_provider_id" type="integer">
  ID do provedor TTS personalizado. Defina como `null` para usar o padrão do idioma. Use o endpoint [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) para descobrir provedores disponíveis.
</ParamField>

<ParamField body="transcriber_provider_id" type="integer">
  ID do provedor STT personalizado. Apenas no modo pipeline. Defina como `null` para usar o padrão do idioma. Use o endpoint [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) para descobrir provedores disponíveis.
</ParamField>

#### Configurações de Comportamento da Chamada

<ParamField body="allow_interruptions" type="boolean">
  Se deve permitir interrupções do chamador.

  <Warning>Não pode ser desabilitado para os modos `multimodal` e `dualplex`.</Warning>
</ParamField>

<ParamField body="fillers" type="boolean">
  Se deve usar áudio de preenchimento durante o processamento.

  <Warning>Disponível apenas para o modo `pipeline`.</Warning>
</ParamField>

<ParamField body="filler_config" type="object">
  Perfis de palavras de preenchimento personalizadas por categoria. Substitui a configuração de preenchimento existente. Cada categoria é um array de frases curtas.

  * `positive`: Palavras de preenchimento para respostas positivas/afirmativas
  * `negative`: Palavras de preenchimento para respostas negativas/neutras
  * `question`: Palavras de preenchimento ao processar uma pergunta
  * `neutral`: Palavras de preenchimento para reconhecimentos neutros

  ```json theme={null}
  "filler_config": {
    "positive": ["Ótimo!", "Perfeito!"],
    "negative": ["Hmm.", "Entendo."],
    "question": ["Boa pergunta.", "Deixe-me verificar."],
    "neutral": ["Ok.", "Anotado."]
  }
  ```
</ParamField>

<ParamField body="record" type="boolean">
  Se deve gravar a chamada
</ParamField>

<ParamField body="enable_noise_cancellation" type="boolean">
  Se deve ativar o cancelamento de ruído
</ParamField>

<ParamField body="wait_for_customer" type="boolean">
  Se verdadeiro, o assistente aguarda o cliente falar primeiro
</ParamField>

#### Configurações de Tempo

<ParamField body="max_duration" type="integer">
  Duração máxima da chamada em segundos (20-1200)
</ParamField>

<ParamField body="max_silence_duration" type="integer">
  Duração máxima de silêncio antes do reengajamento em segundos (1-360)
</ParamField>

<ParamField body="max_initial_silence_duration" type="integer">
  Silêncio máximo no início da chamada antes de encerrar (1-120 segundos). Defina como `null` para desabilitar.
</ParamField>

<ParamField body="ringing_time" type="integer">
  Tempo máximo de toque antes de desistir (1-60 segundos)
</ParamField>

#### Configurações de Reengajamento

<ParamField body="reengagement_interval" type="integer">
  Intervalo de reengajamento em segundos (7-600)
</ParamField>

<ParamField body="reengagement_prompt" type="string">
  Prompt personalizado para mensagens de reengajamento (máximo 1000 caracteres). Defina como `null` para usar o padrão.
</ParamField>

#### Configurações de Caixa Postal

<ParamField body="end_call_on_voicemail" type="boolean">
  Se deve encerrar a chamada quando caixa postal for detectada
</ParamField>

<ParamField body="voice_mail_message" type="string">
  Mensagem para deixar na caixa postal antes de desligar (máximo 1000 caracteres). Defina como `null` para desabilitar.
</ParamField>

#### Detecção de Endpoint

<ParamField body="endpoint_type" type="string">
  Tipo de detecção de atividade de voz. Opções: `vad`, `ai`
</ParamField>

<ParamField body="endpoint_sensitivity" type="number">
  Nível de sensibilidade do endpoint (0-5)
</ParamField>

<ParamField body="interrupt_sensitivity" type="number">
  Nível de sensibilidade de interrupção (0-5)
</ParamField>

<ParamField body="min_interrupt_words" type="integer">
  Palavras mínimas antes que a interrupção seja permitida (0-10). Defina como `null` para desabilitar.
</ParamField>

#### Som Ambiente

<ParamField body="ambient_sound" type="string">
  Som ambiente de fundo. Opções: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`
</ParamField>

<ParamField body="ambient_sound_volume" type="number">
  Nível de volume do som ambiente (0-1)
</ParamField>

#### Configuração de Webhook

<ParamField body="is_webhook_active" type="boolean">
  Se as notificações de webhook estão habilitadas
</ParamField>

<ParamField body="webhook_url" type="string">
  A URL do webhook para notificações pós-chamada. Defina como `null` para remover.
</ParamField>

<ParamField body="send_webhook_only_on_completed" type="boolean">
  Se deve enviar webhooks apenas em chamadas concluídas (não falharam/não atenderam)
</ParamField>

<ParamField body="include_recording_in_webhook" type="boolean">
  Se deve incluir URL de gravação no payload do webhook
</ParamField>

#### Avaliação Pós-Chamada

<ParamField body="post_call_evaluation" type="boolean">
  Se deve ativar a avaliação pós-chamada da IA
</ParamField>

<ParamField body="post_call_schema" type="array">
  Schema definition for post-call data extraction. Replaces existing schema.

  <Expandable title="post_call_schema properties">
    <ParamField body="post_call_schema[].name" type="string" required>
      O nome do campo do esquema (apenas alfanumérico e underscores)
    </ParamField>

    <ParamField body="post_call_schema[].type" type="string" required>
      O tipo de dados. Opções: `string`, `number`, `bool`
    </ParamField>

    <ParamField body="post_call_schema[].description" type="string" required>
      Descrição do que este campo representa
    </ParamField>
  </Expandable>
</ParamField>

#### Ferramenta de Encerrar Chamada

<ParamField body="end_call_tool.description" type="string" optional>
  Descrição para a funcionalidade da ferramenta de encerrar chamada (máximo 500 caracteres)
</ParamField>

#### Configurações de Conversa Encerrada

<ParamField body="conversation_inactivity_timeout" type="integer">
  Minutos de inatividade do chat antes que a conversa seja considerada encerrada (1-1440). Defina como `null` para desabilitar. Padrão: `30`
</ParamField>

<ParamField body="conversation_ended_retrigger" type="boolean">
  Se deve permitir redisparo da conversa após encerrar devido à inatividade
</ParamField>

<ParamField body="conversation_ended_webhook_url" type="string">
  URL do webhook chamada quando uma conversa de chat termina devido à inatividade. Defina como `null` para remover. Separado do webhook principal de chamada.
</ParamField>

***

<ParamField body="llm_temperature" type="number" optional>
  Configuração de temperatura do LLM (0-1)
</ParamField>

<ParamField body="voice_stability" type="number" optional>
  Configuração de estabilidade da voz (0-1)
</ParamField>

<ParamField body="voice_similarity" type="number" optional>
  Configuração de similaridade da voz (0-1)
</ParamField>

<ParamField body="speech_speed" type="number" optional>
  Multiplicador de velocidade da fala (0.7-1.2)
</ParamField>

#### Configurações de Comportamento da Chamada

<ParamField body="allow_interruptions" type="boolean" optional>
  Se deve permitir interrupções do chamador
</ParamField>

<ParamField body="filler_audios" type="boolean" optional>
  Se deve usar áudio de preenchimento durante o processamento
</ParamField>

<ParamField body="re_engagement_interval" type="integer" optional>
  Intervalo de reengajamento em segundos (7-600)
</ParamField>

<ParamField body="max_call_duration" type="integer" optional>
  Duração máxima da chamada em segundos (20-1200)
</ParamField>

<ParamField body="max_silence_duration" type="integer" optional>
  Duração máxima de silêncio em segundos (1-120)
</ParamField>

<ParamField body="end_call_on_voicemail" type="boolean" optional>
  Se deve encerrar a chamada quando uma caixa postal for detectada
</ParamField>

<ParamField body="noise_cancellation" type="boolean" optional>
  Se deve ativar o cancelamento de ruído
</ParamField>

<ParamField body="record_call" type="boolean" optional>
  Se deve gravar a chamada
</ParamField>

<ParamField body="who_speaks_first" type="string" optional>
  Quem fala primeiro na chamada. Opções: `AI assistant`, `Customer`
</ParamField>

### Resposta

<ResponseField name="message" type="string">
  Mensagem de sucesso confirmando a atualização do assistente
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      O identificador único do assistente atualizado
    </ResponseField>

    <ResponseField name="name" type="string">
      O nome do assistente
    </ResponseField>

    <ResponseField name="status" type="string">
      O status atual do assistente
    </ResponseField>

    <ResponseField name="type" type="string">
      O tipo de assistente (`inbound` ou `outbound`)
    </ResponseField>

    <ResponseField name="mode" type="string">
      O modo da engine (`pipeline` ou `multimodal`)
    </ResponseField>
  </Expandable>
</ResponseField>

### Respostas de Erro

<ResponseField name="404 Not Found">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Mensagem de erro quando o assistente não é encontrado ou não pertence ao usuário autenticado
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Validation Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Mensagem de erro indicando falha de validação
    </ResponseField>

    <ResponseField name="errors" type="object">
      Erros de validação detalhados para cada campo
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="500 Internal Server Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Mensagem de erro indicando falha na atualização do assistente
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Success Response theme={null}
  {
    "message": "Assistente atualizado com sucesso",
    "data": {
      "id": 789,
      "name": "Assistente de Vendas Atualizado",
      "status": "active",
      "type": "outbound",
      "mode": "pipeline"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "message": "Assistente não encontrado"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Falha na validação",
    "errors": {
      "speech_speed": [
        "A velocidade da fala deve estar entre 0.7 e 1.2."
      ],
      "webhook_url": [
        "A URL do webhook deve ser uma URL válida."
      ]
    }
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Falha na atualização do assistente"
  }
  ```
</ResponseExample>

### Observações

* Apenas os campos que você fornecer no corpo da requisição serão atualizados
* Todas as regras de validação se aplicam da mesma forma que ao criar um assistente
* Para remover a atribuição de um número de telefone, defina `phone_number_id` como `null`
* Para desativar o webhook, defina `webhook_url` como `null` ou `is_webhook_active` como `false`
* O assistente deve pertencer ao usuário autenticado para ser atualizado
  "mode":