Criar assistente - Sua Sofia

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

name

string

required

O nome do assistente (máx. 255 caracteres)

voice_id

integer

required

O ID da voz a ser usado para o assistente. Use o endpoint Get Voices com o parâmetro mode para obter vozes compatíveis para seu modo de motor.

language_id

integer

required

O ID do idioma para o assistente. Use o endpoint Get Languages para obter idiomas disponíveis.

type

string

required

O tipo do assistente. Opções: inbound, outbound

mode

string

required

O modo do motor. Opções: pipeline, multimodal, dualplex

timezone

string

required

O fuso horário para o assistente (ex.: “Europe/Bucharest”, “America/New_York”)

initial_message

string

required

A mensagem inicial que o assistente falará quando a ligação iniciar (máx. 200 caracteres)

system_prompt

string

required

O prompt do sistema que define o comportamento e personalidade do assistente

Campos Específicos do Modo

llm_model_id

integer

O ID do modelo LLM a ser usado. Obrigatório para modo pipeline.Use o endpoint Get Models para obter modelos disponíveis.

multimodal_model_id

integer

O ID do modelo multimodal. Obrigatório para modos multimodal e dualplex.Use o endpoint Get Models para obter modelos multimodais disponíveis.

chat_llm_fallback_id

integer

ID do modelo LLM de fallback para chamadas de ferramenta em modos multimodal/dualplex. Opcional.

turn_detection_threshold

number

Sensibilidade de detecção de turno para modos multimodal/dualplex (0-1). Padrão: auto

Idiomas Secundários

secondary_language_ids

integer[]

Array de IDs de idiomas adicionais que o assistente pode falar. O assistente detectará automaticamente e mudará de idioma.

"secondary_language_ids": [2, 3, 4]

Configurações da Base de Conhecimento

knowledgebase_id

integer

O ID da base de conhecimento para anexar a este assistente

knowledgebase_mode

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)

Número de Telefone

phone_number_id

integer

O ID de um número de telefone para atribuir ao assistente. Deve pertencer à sua conta.

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.

Ferramentas Personalizadas Durante Chamada

tool_ids

integer[]

Array de IDs de ferramentas personalizadas durante chamada para anexar. Cada ferramenta deve pertencer à sua conta.

"tool_ids": [1, 5, 12]

Ferramentas Integradas

tools

array

Array de ferramentas integradas para ativar. Cada ferramenta tem um type e campos específicos da ferramenta.

Show 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 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

"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"
  }
]

Configurações de Voz e TTS

tts_emotion_enabled

boolean

default:"true"

Se ativar a síntese de texto para fala emocional

voice_stability

number

default:"0.70"

Configuração de estabilidade da voz (0-1). Maior = voz mais consistente

voice_similarity

number

default:"0.50"

Configuração de similaridade da voz (0-1). Maior = mais próxima da voz original

speech_speed

number

default:"1.00"

Multiplicador de velocidade da fala (0.7-1.2)

llm_temperature

number

default:"0.10"

Configuração de temperatura do LLM (0-1). Menor = mais determinístico

synthesizer_provider_id

integer

ID personalizado do provedor TTS. Auto-selecionado baseado no idioma se não fornecido. Use o endpoint Get Synthesizer Providers para descobrir provedores disponíveis.

transcriber_provider_id

integer

ID personalizado do provedor STT. Auto-selecionado baseado no idioma se não fornecido. Apenas modo pipeline. Use o endpoint Get Transcriber Providers para descobrir provedores disponíveis.

Configurações de Comportamento da Ligação

allow_interruptions

boolean

default:"true"

Se permitir interrupções do chamador.

Não pode ser desabilitado para modos multimodal e dualplex.

fillers

boolean

default:"false"

Se usar áudio de preenchimento durante processamento (ex.: “hm”, “deixe-me verificar”).

Disponível apenas para modo pipeline.

filler_config

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.”)

"filler_config": {
  "positive": ["Super!", "Ótimo!", "Perfeito!"],
  "negative": ["Hmm.", "Mhm.", "Entendi."],
  "question": ["Hmm.", "Deixe-me verificar.", "Boa pergunta."],
  "neutral": ["Ok.", "Entendo.", "Anotado."]
}

record

boolean

default:"false"

Se gravar a ligação

enable_noise_cancellation

boolean

default:"true"

Se ativar o cancelamento de ruído

wait_for_customer

boolean

default:"false"

Se verdadeiro, o assistente aguarda o cliente falar primeiro

Configurações de Tempo

max_duration

integer

default:"600"

Duração máxima da ligação em segundos (20-1200)

max_silence_duration

integer

default:"40"

Duração máxima de silêncio antes do re-engajamento em segundos (1-360)

max_initial_silence_duration

integer

Silêncio máximo no início da ligação antes de encerrar (1-120 segundos). Opcional.

ringing_time

integer

default:"30"

Tempo máximo de toque antes de desistir (1-60 segundos)

Configurações de Re-engajamento

reengagement_interval

integer

default:"30"

Intervalo de re-engajamento em segundos (7-600)

reengagement_prompt

string

Prompt personalizado para mensagens de re-engajamento (máx. 1000 caracteres)Exemplo: "Você ainda está aí? Tem alguma outra pergunta?"

Configurações de Correio de Voz

end_call_on_voicemail

boolean

default:"true"

Se encerrar a ligação quando correio de voz for detectado

voice_mail_message

string

Mensagem para deixar no correio de voz antes de desligar (máx. 1000 caracteres)

Detecção de Endpoint

endpoint_type

string

default:"vad"

Tipo de detecção de atividade de voz. Opções: vad, ai

endpoint_sensitivity

number

default:"0.5"

Nível de sensibilidade do endpoint (0-5)

interrupt_sensitivity

number

default:"0.5"

Nível de sensibilidade de interrupção (0-5)

min_interrupt_words

integer

Palavras mínimas antes da interrupção ser permitida (0-10). Defina para habilitar.

Som Ambiente

ambient_sound

string

Som ambiente de fundo. Opções: off, office, city, forest, crowded_room, cafe, nature

ambient_sound_volume

number

default:"0.5"

Nível de volume do som ambiente (0-1)

Configuração de Webhook

is_webhook_active

boolean

default:"false"

Se as notificações de webhook estão ativadas

webhook_url

string

A URL do webhook para notificações pós-ligação. Obrigatório se is_webhook_active for verdadeiro.

send_webhook_only_on_completed

boolean

default:"true"

Se enviar webhooks apenas em ligações completadas (não falhas/sem resposta)

include_recording_in_webhook

boolean

default:"true"

Se incluir URL de gravação no payload do webhook

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

post_call_evaluation

boolean

default:"true"

Se ativar avaliação pós-ligação por IA

post_call_schema

array

Definição do esquema para extração de dados pós-ligação

Show propriedades do post_call_schema

name

string

required

Nome do campo (3-16 caracteres, minúsculo, alfanumérico e underscores apenas)

type

string

required

Tipo de dados. Opções: string, number, bool

description

string

required

Descrição do que este campo representa (3-255 caracteres)

"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"}
]

Variáveis

variables

object

Pares chave-valor de variáveis personalizadas acessíveis em prompts via {{nome_variavel}}

"variables": {
  "company_name": "Acme Corp",
  "product": "Widget Premium",
  "support_email": "suporte@acme.com"
}

Configurações de Conversa Finalizada

conversation_inactivity_timeout

integer

default:"30"

Minutos de inatividade do chat antes da conversa ser considerada finalizada (1-1440)

conversation_ended_retrigger

boolean

default:"false"

Se permitir reativar a conversa após ela terminar por inatividade

conversation_ended_webhook_url

string

URL do webhook chamada quando uma conversa de chat termina por inatividade. Separada do webhook principal de chamadas.

Exemplos de Requisição

Assistente Modo Pipeline

{
  "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

{
  "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

{
  "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

message

string

Mensagem de sucesso confirmando a criação do assistente

data

object

Show propriedades

integer

O identificador único do assistente criado

name

string

O nome do assistente

status

string

O status atual (inactive para novos assistentes)

type

string

O tipo (inbound ou outbound)

mode

string

O modo do motor (pipeline, multimodal ou dualplex)

{
  "message": "Assistente criado com sucesso",
  "data": {
    "id": 789,
    "name": "Assistente de Vendas",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}

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

Referência da API

Assistentes

Chamadas

Conversas

AI

Ferramentas de Chamada

Leads

Campaigns

Números de Telefone

Bases de Conhecimento

SMS

WhatsApp

Webhooks

Chaves da API

​Modos de Motor

​Corpo da Requisição

​Campos Obrigatórios Principais

​Campos Específicos do Modo

​Idiomas Secundários

​Configurações da Base de Conhecimento

​Número de Telefone

​Ferramentas Personalizadas Durante Chamada

​Ferramentas Integradas

​Configurações de Voz e TTS

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

​Configurações de Tempo

​Configurações de Re-engajamento

​Configurações de Correio de Voz

​Detecção de Endpoint

​Som Ambiente

​Configuração de Webhook

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

​Variáveis

​Configurações de Conversa Finalizada

​Exemplos de Requisição

​Assistente Modo Pipeline

​Assistente Modo Multimodal

​Assistente Modo Dualplex

​Resposta

​Notas

Modos de Motor

Corpo da Requisição

Campos Obrigatórios Principais

Campos Específicos do Modo

Idiomas Secundários

Configurações da Base de Conhecimento

Número de Telefone

Ferramentas Personalizadas Durante Chamada

Ferramentas Integradas

Configurações de Voz e TTS

Configurações de Comportamento da Ligação

Configurações de Tempo

Configurações de Re-engajamento

Configurações de Correio de Voz

Detecção de Endpoint

Som Ambiente

Configuração de Webhook

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

Variáveis

Configurações de Conversa Finalizada

Exemplos de Requisição

Assistente Modo Pipeline

Assistente Modo Multimodal

Assistente Modo Dualplex

Resposta

Notas