Criar assistente

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

POST https://suasofia.online/api//user/assistant

Criar assistente

cURL

curl --request POST \
  --url https://suasofia.online/api/user/assistant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "voice_id": 123,
  "language_id": 123,
  "type": "<string>",
  "mode": "<string>",
  "timezone": "<string>",
  "initial_message": "<string>",
  "system_prompt": "<string>",
  "llm_model_id": 123,
  "multimodal_model_id": 123,
  "chat_llm_fallback_id": 123,
  "turn_detection_threshold": 123,
  "secondary_language_ids": [
    123
  ],
  "knowledgebase_id": 123,
  "knowledgebase_mode": "<string>",
  "phone_number_id": 123,
  "tool_ids": [
    123
  ],
  "tools": [
    {}
  ],
  "tts_emotion_enabled": true,
  "voice_stability": 123,
  "voice_similarity": 123,
  "speech_speed": 123,
  "llm_temperature": 123,
  "synthesizer_provider_id": 123,
  "transcriber_provider_id": 123,
  "allow_interruptions": true,
  "fillers": true,
  "record": true,
  "enable_noise_cancellation": true,
  "wait_for_customer": true,
  "max_duration": 123,
  "max_silence_duration": 123,
  "max_initial_silence_duration": 123,
  "ringing_time": 123,
  "reengagement_interval": 123,
  "reengagement_prompt": "<string>",
  "end_call_on_voicemail": true,
  "voice_mail_message": "<string>",
  "endpoint_type": "<string>",
  "endpoint_sensitivity": 123,
  "interrupt_sensitivity": 123,
  "min_interrupt_words": 123,
  "ambient_sound": "<string>",
  "ambient_sound_volume": 123,
  "is_webhook_active": true,
  "webhook_url": "<string>",
  "send_webhook_only_on_completed": true,
  "include_recording_in_webhook": true,
  "post_call_evaluation": true,
  "post_call_schema": [
    {
      "name": "<string>",
      "type": "<string>",
      "description": "<string>"
    }
  ],
  "variables": {}
}
'

201 Resposta de Sucesso

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

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 Tipos de ferramenta

call_transfer - Transferir a ligação para outro número de telefone

• phone_number (obrigatório): Número de telefone para transferir (ex.: “[phone]”)
• description: Quando transferir a ligação
• custom: Se verdadeiro, IA pode determinar o número de transferência dinamicamente
• timezone: Fuso horário para disponibilidade de transferência

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)

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
• description: Quando oferecer agendamento

"tools": [
  {
    "type": "call_transfer",
    "phone_number": "[phone]",
    "description": "Transferir quando cliente solicitar suporte humano"
  },
  {
    "type": "dtmf_input",
    "description": "Navegar em menus de URA quando necessário"
  },
  {
    "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 do provedor TTS personalizado. Selecionado automaticamente com base no idioma se não fornecido.

transcriber_provider_id · integer

ID do provedor STT personalizado. Selecionado automaticamente com base no idioma se não fornecido. Apenas modo pipeline.

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.

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": "[e-mail]"
}

---

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,
  "tool_ids": [1, 5],
  "tools": [
    {"type": "end_call", "description": "Encerrar ligação quando cliente estiver satisfeito"},
    {"type": "call_transfer", "phone_number": "[phone]", "description": "Transferir para suporte"}
  ],
  "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

id · 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)

201 Resposta de Sucesso

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