Ana içeriğe atla
POST
/
user
/
assistant
Asistan oluştur
curl --request POST \
  --url https://api.example.com/user/assistant \
  --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,
  "filler_config": {},
  "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": {},
  "conversation_inactivity_timeout": 123,
  "conversation_ended_retrigger": true,
  "conversation_ended_webhook_url": "<string>"
}
'
{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}
Bu endpoint, kapsamlı yapılandırma seçenekleriyle yeni bir AI asistanı oluşturmanıza olanak tanır.

Motor Modları

API, her biri farklı yeteneklere sahip üç motor modunu destekler:
ModAçıklamaZorunlu Alanlar
pipelineGeleneksel STT → LLM → TTS işlem hattıllm_model_id
multimodalGerçek zamanlı multimodal AImultimodal_model_id
dualplexMultimodal beyin + özel TTS sesimultimodal_model_id

İstek Gövdesi

Temel Zorunlu Alanlar

name
string
gerekli
Asistanın adı (maks. 255 karakter)
voice_id
integer
gerekli
Asistan için kullanılacak ses ID’si. Motor modunuzla uyumlu sesleri almak için mode parametresiyle Sesleri Getir uç noktasını kullanın.
language_id
integer
gerekli
Asistan için dil ID’si. Mevcut dilleri almak için Dilleri Getir uç noktasını kullanın.
type
string
gerekli
Asistan türü. Seçenekler: inbound, outbound
mode
string
gerekli
Motor modu. Seçenekler: pipeline, multimodal, dualplex
timezone
string
gerekli
Asistan için saat dilimi (ör. “Europe/Bucharest”, “America/New_York”)
initial_message
string
gerekli
Arama başladığında asistanın söyleyeceği ilk mesaj (maks. 200 karakter)
system_prompt
string
gerekli
Asistanın davranışını ve kişiliğini tanımlayan sistem istemi

Moda Özel Alanlar

llm_model_id
integer
Kullanılacak LLM model ID’si. pipeline modu için zorunludur.Mevcut modelleri almak için Modelleri Getir uç noktasını kullanın.
multimodal_model_id
integer
Multimodal model ID’si. multimodal ve dualplex modları için zorunludur.Mevcut multimodal modelleri almak için Modelleri Getir uç noktasını kullanın.
chat_llm_fallback_id
integer
Multimodal/dualplex modlarında araç çağrıları için yedek LLM model ID’si. İsteğe bağlı.
turn_detection_threshold
number
Multimodal/dualplex modları için konuşma sırası algılama hassasiyeti (0-1). Varsayılan: otomatik

İkincil Diller

secondary_language_ids
integer[]
Asistanın konuşabileceği ek dil ID’lerinin dizisi. Asistan dilleri otomatik olarak algılar ve geçiş yapar.
"secondary_language_ids": [2, 3, 4]

Bilgi Bankası Ayarları

knowledgebase_id
integer
Bu asistana eklenecek bilgi bankası ID’si
knowledgebase_mode
string
Bilgi bankasının nasıl kullanılacağı. Seçenekler:
  • function_call - AI arama yapmak için bir fonksiyon çağırır (multimodal/dualplex için zorunlu)
  • prompt - Bilgi isteme enjekte edilir (yalnızca pipeline)

Telefon Numarası

phone_number_id
integer
Asistana atanacak telefon numarasının ID’si. Hesabınıza ait olmalıdır.
inbound asistanlar için telefon numarası Arayan Kimliği türünde olamaz ve başka bir gelen arama asistanına zaten atanmış olamaz.

Özel Görüşme İçi Araçlar

tool_ids
integer[]
Eklenecek özel görüşme içi araç ID’lerinin dizisi. Her araç hesabınıza ait olmalıdır.
"tool_ids": [1, 5, 12]

Yerleşik Araçlar

tools
array
Etkinleştirilecek yerleşik araçların dizisi. Her aracın bir type değeri ve araca özel alanları vardır.
"tools": [
  {
    "type": "call_transfer",
    "phone_number": "+1234567890",
    "description": "Transfer when customer requests human support"
  },
  {
    "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": "End call when customer confirms satisfaction"
  }
]

Ses ve TTS Ayarları

tts_emotion_enabled
boolean
varsayılan:"true"
Duygusal metin-konuşma sentezinin etkinleştirilip etkinleştirilmeyeceği
voice_stability
number
varsayılan:"0.70"
Ses kararlılığı ayarı (0-1). Yüksek = daha tutarlı ses
voice_similarity
number
varsayılan:"0.50"
Ses benzerliği ayarı (0-1). Yüksek = orijinal sese daha yakın
speech_speed
number
varsayılan:"1.00"
Konuşma hızı çarpanı (0.7-1.2)
llm_temperature
number
varsayılan:"0.10"
LLM sıcaklık ayarı (0-1). Düşük = daha belirleyici
synthesizer_provider_id
integer
Özel TTS sağlayıcı ID’si. Belirtilmezse dile göre otomatik seçilir. Mevcut sağlayıcıları keşfetmek için Sentezleyici Sağlayıcıları Getir uç noktasını kullanın.
transcriber_provider_id
integer
Özel STT sağlayıcı ID’si. Belirtilmezse dile göre otomatik seçilir. Yalnızca pipeline modu. Mevcut sağlayıcıları keşfetmek için Yazıya Dökücü Sağlayıcıları Getir uç noktasını kullanın.

Arama Davranış Ayarları

allow_interruptions
boolean
varsayılan:"true"
Arayan kişinin sözünü kesmesine izin verilip verilmeyeceği.
multimodal ve dualplex modlarında devre dışı bırakılamaz.
fillers
boolean
varsayılan:"false"
İşleme sırasında dolgu seslerinin kullanılıp kullanılmayacağı (ör. “hmm”, “bir kontrol edeyim”).
Yalnızca pipeline modu için kullanılabilir.
filler_config
object
Kategori bazında özel dolgu kelime profilleri. Belirtilmezse, asistanın diline göre varsayılanlar ayarlanır. Her kategori kısa ifadelerden oluşan bir dizidir.
  • positive: Olumlu/onaylayıcı yanıtlar için dolgu kelimeleri (ör. “Harika!”, “Mükemmel!”)
  • negative: Olumsuz/nötr yanıtlar için dolgu kelimeleri (ör. “Hmm.”, “Mhm.”)
  • question: Bir soru işlenirken dolgu kelimeleri (ör. “Hmm.”, “Bir düşüneyim.”)
  • neutral: Nötr onaylar için dolgu kelimeleri (ör. “Tamam.”, “Anlıyorum.”)
"filler_config": {
  "positive": ["Super!", "Great!", "Perfect!"],
  "negative": ["Hmm.", "Mhm.", "I see."],
  "question": ["Hmm.", "Let me check.", "Good question."],
  "neutral": ["Ok.", "I understand.", "Noted."]
}
record
boolean
varsayılan:"false"
Aramanın kaydedilip kaydedilmeyeceği
enable_noise_cancellation
boolean
varsayılan:"true"
Gürültü engellemenin etkinleştirilip etkinleştirilmeyeceği
wait_for_customer
boolean
varsayılan:"false"
true ise asistan müşterinin önce konuşmasını bekler

Zamanlama Ayarları

max_duration
integer
varsayılan:"600"
Saniye cinsinden maksimum arama süresi (20-1200)
max_silence_duration
integer
varsayılan:"40"
Yeniden etkileşim öncesi saniye cinsinden maksimum sessizlik süresi (1-360)
max_initial_silence_duration
integer
Arama başlangıcında sonlandırma öncesi maksimum sessizlik süresi (1-120 saniye). İsteğe bağlı.
ringing_time
integer
varsayılan:"30"
Vazgeçme öncesi maksimum çalma süresi (1-60 saniye)

Yeniden Etkileşim Ayarları

reengagement_interval
integer
varsayılan:"30"
Saniye cinsinden yeniden etkileşim aralığı (7-600)
reengagement_prompt
string
Yeniden etkileşim mesajları için özel istem (maks. 1000 karakter)Örnek: "Hâlâ orada mısınız? Başka sorularınız var mı?"

Sesli Mesaj Ayarları

end_call_on_voicemail
boolean
varsayılan:"true"
Sesli mesaj algılandığında aramanın sonlandırılıp sonlandırılmayacağı
voice_mail_message
string
Kapatmadan önce sesli mesaja bırakılacak mesaj (maks. 1000 karakter)

Uç Nokta Algılama

endpoint_type
string
varsayılan:"vad"
Ses etkinliği algılama türü. Seçenekler: vad, ai
endpoint_sensitivity
number
varsayılan:"0.5"
Uç nokta hassasiyet seviyesi (0-5)
interrupt_sensitivity
number
varsayılan:"0.5"
Söz kesme hassasiyet seviyesi (0-5)
min_interrupt_words
integer
Söz kesmeye izin verilmeden önceki minimum kelime sayısı (0-10). Etkinleştirmek için ayarlayın.

Ortam Sesi

ambient_sound
string
Arka plan ortam sesi. Seçenekler: off, office, city, forest, crowded_room, cafe, nature
ambient_sound_volume
number
varsayılan:"0.5"
Ortam sesi ses seviyesi (0-1)

Webhook Yapılandırması

is_webhook_active
boolean
varsayılan:"false"
Webhook bildirimlerinin etkin olup olmadığı
webhook_url
string
Arama sonrası bildirimler için webhook URL’si. is_webhook_active değeri true ise zorunludur.
send_webhook_only_on_completed
boolean
varsayılan:"true"
Webhook’ların yalnızca tamamlanan aramalarda gönderilip gönderilmeyeceği (başarısız/cevapsız aramalar hariç)
include_recording_in_webhook
boolean
varsayılan:"true"
Webhook yüküne kayıt URL’sinin dahil edilip edilmeyeceği

Arama Sonrası Değerlendirme

post_call_evaluation
boolean
varsayılan:"true"
AI arama sonrası değerlendirmesinin etkinleştirilip etkinleştirilmeyeceği
post_call_schema
array
Arama sonrası veri çıkarma için şema tanımı
"post_call_schema": [
  {"name": "status", "type": "bool", "description": "Was the call objective achieved"},
  {"name": "summary", "type": "string", "description": "Brief summary of the call"}
]

Değişkenler

variables
object
İstemlerde {{variable_name}} aracılığıyla erişilebilen özel değişkenlerin anahtar-değer çiftleri
"variables": {
  "company_name": "Acme Corp",
  "product": "Premium Widget",
  "support_email": "support@acme.com"
}

Görüşme Sona Erme Ayarları

conversation_inactivity_timeout
integer
varsayılan:"30"
Görüşmenin sona ermiş sayılması için dakika cinsinden sohbet etkinsizlik süresi (1-1440)
conversation_ended_retrigger
boolean
varsayılan:"false"
Etkinsizlik nedeniyle sona erdikten sonra görüşmenin yeniden tetiklenmesine izin verilip verilmeyeceği
conversation_ended_webhook_url
string
Bir sohbet görüşmesi etkinsizlik nedeniyle sona erdiğinde çağrılan webhook URL’si. Ana arama webhook’undan ayrıdır.

Örnek İstekler

Pipeline Modu Asistanı

{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Bucharest",
  "initial_message": "Hello! How can I help you today?",
  "system_prompt": "You are a professional sales assistant...",
  "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": "End call when customer is satisfied"
    },
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer to support"
    },
    {
      "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": "#"
    }
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Are you still there?"
}

Multimodal Modu Asistanı

{
  "name": "Support Bot",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/New_York",
  "initial_message": "Hi! Welcome to support.",
  "system_prompt": "You are a helpful destek asistanı...",
  "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
}

Dualplex Modu Asistanı

{
  "name": "Premium Asistan",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Bucharest",
  "initial_message": "Buna ziua!",
  "system_prompt": "Esti un asistent profesionist...",
  "multimodal_model_id": 4,
  "chat_llm_fallback_id": 2,
  "secondary_language_ids": [1, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "ambient_sound": "office",
  "ambient_sound_volume": 0.3
}

Yanıt

message
string
Asistan oluşturma işlemini onaylayan başarı mesajı
data
object
{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}

Notlar

  • Asistanın başarıyla oluşturulması için tüm zorunlu alanlar sağlanmalıdır
  • Uyumlu sesleri almak için mode parametresiyle Sesleri Getir uç noktasını kullanın
  • Multimodal/dualplex modları için knowledgebase_mode değeri function_call olmalıdır
  • Multimodal/dualplex modları için allow_interruptions her zaman etkindir
  • Dolgu kelimeleri yalnızca pipeline modunda kullanılabilir
  • Asistan varsayılan olarak inactive durumuyla oluşturulur