> ## 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.

# Criar assistente

> Criar um novo assistente de IA com configuração especificada.

Este endpoint permite criar um novo assistente de IA com opções abrangentes de configuração.

## Modos de Motor

A API suporta três modos de motor, cada um com diferentes capacidades:

| Modo         | Descrição                                  | Campos Obrigatórios   |
| ------------ | ------------------------------------------ | --------------------- |
| `pipeline`   | Pipeline tradicional STT → LLM → TTS       | `llm_model_id`        |
| `multimodal` | IA multimodal em tempo real                | `multimodal_model_id` |
| `dualplex`   | Cérebro multimodal + voz TTS personalizada | `multimodal_model_id` |

### Corpo da Requisição

#### Campos Obrigatórios Principais

<ParamField body="name" type="string" required>
  O nome do assistente (máx. 255 caracteres)
</ParamField>

<ParamField body="voice_id" type="integer" required>
  O ID da voz a ser usado para o assistente. Use o endpoint [Get Voices](/api-reference/assistants/get-voices) com o parâmetro `mode` para obter vozes compatíveis para seu modo de motor.
</ParamField>

<ParamField body="language_id" type="integer" required>
  O ID do idioma para o assistente. Use o endpoint [Get Languages](/api-reference/assistants/get-languages) para obter idiomas disponíveis.
</ParamField>

<ParamField body="type" type="string" required>
  O tipo do assistente. Opções: `inbound`, `outbound`
</ParamField>

<ParamField body="mode" type="string" required>
  O modo do motor. Opções: `pipeline`, `multimodal`, `dualplex`
</ParamField>

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

<ParamField body="initial_message" type="string" required>
  A mensagem inicial que o assistente falará quando a ligação iniciar (máx. 200 caracteres)
</ParamField>

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

#### Campos Específicos do Modo

<ParamField body="llm_model_id" type="integer">
  O ID do modelo LLM a ser usado. **Obrigatório para modo `pipeline`.**

  Use o endpoint [Get Models](/api-reference/assistants/get-models) para obter modelos disponíveis.
</ParamField>

<ParamField body="multimodal_model_id" type="integer">
  O ID do modelo multimodal. **Obrigatório para modos `multimodal` e `dualplex`.**

  Use o endpoint [Get Models](/api-reference/assistants/get-models) para obter modelos multimodais disponíveis.
</ParamField>

<ParamField body="chat_llm_fallback_id" type="integer">
  ID do modelo LLM de fallback para chamadas de ferramenta em modos multimodal/dualplex. Opcional.
</ParamField>

<ParamField body="turn_detection_threshold" type="number">
  Sensibilidade de detecção de turno para modos multimodal/dualplex (0-1). Padrão: auto
</ParamField>

#### Idiomas Secundários

<ParamField body="secondary_language_ids" type="integer[]">
  Array de IDs de idiomas adicionais que o assistente pode falar. O assistente detectará automaticamente e mudará de idioma.

  ```json theme={null}
  "secondary_language_ids": [2, 3, 4]
  ```
</ParamField>

#### Configurações da Base de Conhecimento

<ParamField body="knowledgebase_id" type="integer">
  O ID da base de conhecimento para anexar a este assistente
</ParamField>

<ParamField body="knowledgebase_mode" type="string">
  Como usar a base de conhecimento. Opções:

  * `function_call` - IA chama uma função para buscar (obrigatório para multimodal/dualplex)
  * `prompt` - Conhecimento é injetado no prompt (apenas pipeline)
</ParamField>

#### Número de Telefone

<ParamField body="phone_number_id" type="integer">
  O ID de um número de telefone para atribuir ao assistente. Deve pertencer à sua conta.

  <Warning>
    Para assistentes `inbound`, o número de telefone não pode ser do tipo Caller ID e não pode estar já atribuído a outro assistente inbound.
  </Warning>
</ParamField>

#### Ferramentas Personalizadas Durante Chamada

<ParamField body="tool_ids" type="integer[]">
  Array de IDs de ferramentas personalizadas durante chamada para anexar. Cada ferramenta deve pertencer à sua conta.

  ```json theme={null}
  "tool_ids": [1, 5, 12]
  ```
</ParamField>

#### Ferramentas Integradas

<ParamField body="tools" type="array">
  Array de ferramentas integradas para ativar. Cada ferramenta tem um `type` e campos específicos da ferramenta.

  <Expandable title="Tool types">
    **call\_transfer** - Transferir a ligação para outro número de telefone

    * `phone_number` (obrigatório): Número de telefone para transferir (ex.: "+1234567890")
    * `description`: Quando transferir a ligação
    * `custom`: Se verdadeiro, IA pode determinar número de transferência dinamicamente
    * `timezone`: Fuso horário para disponibilidade de transferência
    * `warm_transfer`: Enviar mensagem ao 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 ligação está sendo transferida.")

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

    * `supervisor_phone` (obrigatório): Número de telefone para discar para a transferência calorosa (ex.: "+14155552001"). Se `custom_sip` estiver habilitado, é 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. Use [Get Phone Numbers](/api-reference/assistants/get-phone-numbers) para encontrar números disponíveis.
    * `description` (obrigatório): **Quando transferir** — descreve quando a IA deve iniciar a transferência calorosa (ex.: "Transferir a ligação para um supervisor humano quando o cliente solicitar falar com uma pessoa real.")
    * `custom_sip`: Habilitar para inserir endereço SIP personalizado ou extensão interna em vez de número de telefone (padrão: `false`)
    * `caller_id_mode`: Qual número de telefone o supervisor vê ao receber a ligação. 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 ao chamador antes de colocá-lo em espera (padrão: "Por favor aguarde enquanto eu o conecto com um supervisor.")
    * `summary_instructions`: Instruções sobre como a IA deve briefar o supervisor sobre a ligação (padrão: "Apresente a conversa da sua perspectiva:\n- QUEM está ligando (nome, empresa se mencionada)\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 fala para o supervisor quando eles atendem (padrão: "Olá! Tenho um chamador na linha que precisa da sua assistência. Posso briefá-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 conversando.")

    **end\_call** - Encerrar a ligação programaticamente

    * `description`: Quando a IA deve encerrar a ligação

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

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

    **collect\_keypad** - Coletar entrada do 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 personalizada da API Cal.com. 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": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transferir quando cliente solicitar suporte humano"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "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": "Encerrar ligação quando cliente confirmar satisfação"
    }
  ]
  ```
</ParamField>

#### Configurações de Voz e TTS

<ParamField body="tts_emotion_enabled" type="boolean" default="true">
  Se ativar a síntese de texto para fala emocional
</ParamField>

<ParamField body="voice_stability" type="number" default="0.70">
  Configuração de estabilidade da voz (0-1). Maior = voz mais consistente
</ParamField>

<ParamField body="voice_similarity" type="number" default="0.50">
  Configuração de similaridade da voz (0-1). Maior = mais próxima da voz original
</ParamField>

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

<ParamField body="llm_temperature" type="number" default="0.10">
  Configuração de temperatura do LLM (0-1). Menor = mais determinístico
</ParamField>

<ParamField body="synthesizer_provider_id" type="integer">
  ID personalizado do provedor TTS. Auto-selecionado baseado no idioma se não fornecido. 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 personalizado do provedor STT. Auto-selecionado baseado no idioma se não fornecido. Apenas modo pipeline. Use o endpoint [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) para descobrir provedores disponíveis.
</ParamField>

#### Configurações de Comportamento da Ligação

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

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

<ParamField body="fillers" type="boolean" default="false">
  Se usar áudio de preenchimento durante processamento (ex.: "hm", "deixe-me verificar").

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

<ParamField body="filler_config" type="object">
  Perfis personalizados de palavras de preenchimento por categoria. Se não fornecido, padrões são definidos baseados no idioma do assistente. Cada categoria é um array de frases curtas.

  * `positive`: Palavras de preenchimento para respostas positivas/afirmativas (ex.: "Ótimo!", "Perfeito!")
  * `negative`: Palavras de preenchimento para respostas negativas/neutras (ex.: "Hmm.", "Mhm.")
  * `question`: Palavras de preenchimento ao processar uma pergunta (ex.: "Hmm.", "Deixe-me pensar.")
  * `neutral`: Palavras de preenchimento para reconhecimentos neutros (ex.: "Ok.", "Entendo.")

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

<ParamField body="record" type="boolean" default="false">
  Se gravar a ligação
</ParamField>

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

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

#### Configurações de Tempo

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

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

<ParamField body="max_initial_silence_duration" type="integer">
  Silêncio máximo no início da ligação antes de encerrar (1-120 segundos). Opcional.
</ParamField>

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

#### Configurações de Re-engajamento

<ParamField body="reengagement_interval" type="integer" default="30">
  Intervalo de re-engajamento em segundos (7-600)
</ParamField>

<ParamField body="reengagement_prompt" type="string">
  Prompt personalizado para mensagens de re-engajamento (máx. 1000 caracteres)

  Exemplo: `"Você ainda está aí? Tem alguma outra pergunta?"`
</ParamField>

#### Configurações de Correio de Voz

<ParamField body="end_call_on_voicemail" type="boolean" default="true">
  Se encerrar a ligação quando correio de voz for detectado
</ParamField>

<ParamField body="voice_mail_message" type="string">
  Mensagem para deixar no correio de voz antes de desligar (máx. 1000 caracteres)
</ParamField>

#### Detecção de Endpoint

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

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

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

<ParamField body="min_interrupt_words" type="integer">
  Palavras mínimas antes da interrupção ser permitida (0-10). Defina para habilitar.
</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" default="0.5">
  Nível de volume do som ambiente (0-1)
</ParamField>

#### Configuração de Webhook

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

<ParamField body="webhook_url" type="string">
  A URL do webhook para notificações pós-ligação. **Obrigatório se `is_webhook_active` for verdadeiro.**
</ParamField>

<ParamField body="send_webhook_only_on_completed" type="boolean" default="true">
  Se enviar webhooks apenas em ligações completadas (não falhas/sem resposta)
</ParamField>

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

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

<ParamField body="post_call_evaluation" type="boolean" default="true">
  Se ativar avaliação pós-ligação por IA
</ParamField>

<ParamField body="post_call_schema" type="array">
  Definição do esquema para extração de dados pós-ligação

  <Expandable title="propriedades do post_call_schema">
    <ParamField body="name" type="string" required>
      Nome do campo (3-16 caracteres, minúsculo, alfanumérico e underscores apenas)
    </ParamField>

    <ParamField body="type" type="string" required>
      Tipo de dados. Opções: `string`, `number`, `bool`
    </ParamField>

    <ParamField body="description" type="string" required>
      Descrição do que este campo representa (3-255 caracteres)
    </ParamField>
  </Expandable>

  ```json theme={null}
  "post_call_schema": [
    {"name": "status", "type": "bool", "description": "O objetivo da ligação foi alcançado"},
    {"name": "summary", "type": "string", "description": "Resumo breve da ligação"}
  ]
  ```
</ParamField>

#### Variáveis

<ParamField body="variables" type="object">
  Pares chave-valor de variáveis personalizadas acessíveis em prompts via `{{nome_variavel}}`

  ```json theme={null}
  "variables": {
    "company_name": "Acme Corp",
    "product": "Widget Premium",
    "support_email": "suporte@acme.com"
  }
  ```
</ParamField>

#### Configurações de Conversa Finalizada

<ParamField body="conversation_inactivity_timeout" type="integer" default="30">
  Minutos de inatividade do chat antes da conversa ser considerada finalizada (1-1440)
</ParamField>

<ParamField body="conversation_ended_retrigger" type="boolean" default="false">
  Se permitir reativar a conversa após ela terminar por inatividade
</ParamField>

<ParamField body="conversation_ended_webhook_url" type="string">
  URL do webhook chamada quando uma conversa de chat termina por inatividade. Separada do webhook principal de chamadas.
</ParamField>

***

## Exemplos de Requisição

### Assistente Modo Pipeline

```json theme={null}
{
  "name": "Assistente de Vendas",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "America/Sao_Paulo",
  "initial_message": "Olá! Como posso ajudar você hoje?",
  "system_prompt": "Você é um assistente profissional de vendas...",
  "llm_model_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "prompt",
  "fillers": true,
  "filler_config": {
    "positive": ["Great!", "Perfect!", "Awesome!"],
    "negative": ["Hmm.", "I see."],
    "question": ["Good question.", "Let me check."],
    "neutral": ["Ok.", "Noted.", "I understand."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {
      "type": "end_call",
      "description": "Encerrar ligação quando cliente estiver satisfeito"
    },
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transferir para suporte"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transferir a ligação para um supervisor humano quando o cliente solicitar falar com uma pessoa real.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Por favor aguarde enquanto eu o conecto com um supervisor.",
      "summary_instructions": "Apresente a conversa da sua perspectiva:\n- QUEM está ligando (nome, empresa se mencionada)\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": "Olá! Tenho um chamador na linha que precisa da sua assistência. Posso briefá-lo sobre a situação?",
      "connected_message": "Você está agora conectado com um supervisor. Vou deixá-los conversando."
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    }
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Você ainda está aí?"
}
```

### Assistente Modo Multimodal

```json theme={null}
{
  "name": "Bot de Suporte",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/Sao_Paulo",
  "initial_message": "Oi! Bem-vindo ao suporte.",
  "system_prompt": "Você é um agente de suporte prestativo...",
  "multimodal_model_id": 1,
  "chat_llm_fallback_id": 2,
  "turn_detection_threshold": 0.7,
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "tts_emotion_enabled": false
}
```

### Assistente Modo Dualplex

```json theme={null}
{
  "name": "Agente Premium",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "America/Sao_Paulo",
  "initial_message": "Bom dia!",
  "system_prompt": "Você é um assistente profissional...",
  "multimodal_model_id": 4,
  "chat_llm_fallback_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "ambient_sound": "office",
  "ambient_sound_volume": 0.3
}
```

***

## Resposta

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

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

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

    <ResponseField name="status" type="string">
      O status atual (`inactive` para novos assistentes)
    </ResponseField>

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

    <ResponseField name="mode" type="string">
      O modo do motor (`pipeline`, `multimodal` ou `dualplex`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Resposta de Sucesso theme={null}
  {
    "message": "Assistente criado com sucesso",
    "data": {
      "id": 789,
      "name": "Assistente de Vendas",
      "status": "inactive",
      "type": "outbound",
      "mode": "pipeline"
    }
  }
  ```

  ```json 422 Erro de Validação theme={null}
  {
    "message": "Falha na validação",
    "errors": {
      "name": ["O campo nome é obrigatório."],
      "voice_id": ["A voz selecionada não é compatível com o tipo de motor escolhido."],
      "knowledgebase_mode": ["Apenas o modo function_call está disponível para assistentes multimodais."]
    }
  }
  ```
</ResponseExample>

***

## Notas

* Todos os campos obrigatórios devem ser fornecidos para criação bem-sucedida do assistente
* Use o endpoint Get Voices com parâmetro `mode` para obter vozes compatíveis
* Para modos multimodal/dualplex, `knowledgebase_mode` deve ser `function_call`
* Para modos multimodal/dualplex, `allow_interruptions` está sempre ativo
* Fillers estão disponíveis apenas no modo pipeline
* O assistente é criado com status `inactive` por padrão