Geliştiriciler

Kancalar ve filtreler

Promptor 2.1.0'ın tüm action ve filter kancaları: argümanlar, varsayılanlar ve yapay zekâ, sohbet, devir, müşteri adayları ve MCP için PHP örnekleri.

Promptor, küçük bir özel eklentiden kullanabileceğiniz WordPress action ve filter kancaları sunar (bu, bir alt temanın functions.php dosyasından daha iyidir, çünkü tema değişikliklerinden etkilenmez). Aşağıdakilerin tamamı 2.1.0 sürümünde bulunur. Pro olarak işaretlenen kancalar yalnızca Promptor Pro etkinken tetiklenir.

Özet

KancaTürArgümanlarSürüm
promptor/openai_chat_endpointfilter$urlFree ve Pro
promptor/openai_embeddings_endpointfilter$urlFree ve Pro
promptor/openai_models_endpointfilter$urlFree ve Pro
promptor/wp_ai_client_factoryfilter$factoryFree ve Pro
promptor/strict_scopefilter$strict, $context_nameFree ve Pro
promptor/scope_rulesfilter$rules, $site_name, $language, $context_nameFree ve Pro
promptor/chat_extra_contextfilter$extra, $argsFree ve Pro
promptor/chat_unansweredfilter$unanswered, $argsFree ve Pro
promptor/chat_actionsfilter$actions, $argsFree ve Pro
promptor/chat_handofffilter$handoff, $argsFree ve Pro
promptor/handoff_request_keywordsfilter$keywordsFree ve Pro
promptor/handoff_frontend_configfilter$configFree ve Pro
promptor_handoffaction$eventFree ve Pro
promptor/engagement_should_renderfilter$allowedFree ve Pro
promptor/engagement_frontend_configfilter$configFree ve Pro
promptor/booking_intent_patternfilter$patternFree ve Pro
promptor/public/ui_settingsfilter$settingsFree ve Pro
promptor/public/example_questionsfilter$questions, $context_keyFree ve Pro
promptor/available_languagesfilter$languagesFree ve Pro
promptor/content_selection_post_typesfilter$post_typesFree ve Pro
promptor/default_content_rolefilter$role, $post_typeFree ve Pro
promptor/item_indexedaction$post_id, $context_name, $chunksFree ve Pro
promptor/settings_tabsfilter$tabsFree ve Pro
promptor_before_insert_submissionfilter$dataFree ve Pro
promptor_after_insert_submissionaction$submission_id, $dataFree ve Pro
promptor_lead_createdaction$submission_id, $leadFree ve Pro
promptor_lead_scoredaction$submission_id, $scorePro
promptor_webhook_payloadfilter$payload, $event, $dataPro
promptor_webhook_headersfilter$headers, $eventPro
promptor_webhook_event_enabledfilter$enabled, $eventPro
promptor_before_update_query_productsfilter$products_csv, $query_idPro (WooCommerce)
promptor_after_update_query_productsaction$query_id, $products_csvPro (WooCommerce)
promptor/mcp_routefilter$routePro
promptor_fs_loadedactionyokFree ve Pro

İki adlandırma stiline dikkat edin: kancaların çoğu eğik çizgi kullanır (promptor/…); müşteri adayı, ürün ve webhook kancaları ise alt çizgi kullanır.

Yapay zekâ uç noktaları

promptor/openai_chat_endpoint

Chat completions URL'sini filtreler. Varsayılan: https://api.openai.com/v1/chat/completions. Sohbet yanıtları ve Yapay zeka ile oluştur (Generate with AI) için kullanılır.

promptor/openai_embeddings_endpoint

Embeddings URL'sini filtreler. Varsayılan: https://api.openai.com/v1/embeddings. Dizinleme, her sorunun embedding'ini (vektörünü) oluşturma ve Pro MCP sunucusunun bilgi araması için kullanılır.

promptor/openai_models_endpoint

Models URL'sini filtreler. Varsayılan: https://api.openai.com/v1/models. Anahtarı Doğrula (Verify Key) ve model listesini yenileme tarafından kullanılır.

İstekleri OpenAI uyumlu bir proxy veya ağ geçidi üzerinden yönlendirmek için bunları kullanın. Uç nokta, OpenAI ile aynı istek ve yanıt biçimini ve aynı Authorization: Bearer anahtarını kabul etmelidir.

add_filter( 'promptor/openai_chat_endpoint', function ( $url ) {
    return 'https://ai-gateway.example.com/v1/chat/completions';
} );

add_filter( 'promptor/openai_embeddings_endpoint', function ( $url ) {
    return 'https://ai-gateway.example.com/v1/embeddings';
} );

promptor/wp_ai_client_factory

WordPress AI Client sağlayıcısı seçildiğinde istemi (prompt) oluşturan callable'ı filtreler. Varsayılan: 'wp_ai_client_prompt' dizesi. Onu sarmalamak veya değiştirmek için aynı imzaya sahip bir callable döndürün; örneğin testlerde günlük kaydı tutmak için.

Yanıt kapsamı

2.1.0'dan beri her istem kapsam kuralları içerir: asistan yalnızca işletmenizle ilgili soruları yanıtlar, genel kültür, kod ve ödev sorularını geri çevirir, asla bilgi uydurmaz ve istem enjeksiyonu (prompt injection) girişimlerini yok sayar. Konu dışı sorular öneri içermeyen kısa bir retle yanıtlanır.

promptor/strict_scope

Kapsam kurallarını kaldırmak için false döndürün; örneğin tek bir bilgi tabanı için. Varsayılan: true.

add_filter( 'promptor/strict_scope', function ( $strict, $context_name ) {
    return 'internal-wiki' === $context_name ? false : $strict;
}, 10, 2 );

promptor/scope_rules

Sistem istemine eklenen kural metnini filtreler. Argümanlar: $rules, $site_name, $language (yanıt dili) ve $context_name. Katı kapsam kapalıyken çağrılmaz.

Sohbet yanıtları

Bu dört filtre her yanıtta, yanıt tarayıcıya gönderilmeden önce çalışır. Her biri şu anahtarları içeren bir $args dizisi alır:

Anahtarİçerik
user_queryZiyaretçinin sorusu
context_nameBilgi tabanı anahtarı
confidenceBulunan içeriğin en iyi benzerlik puanı (0–1)
has_contextHerhangi bir bilgi tabanı içeriği bulunduysa true
explanationYanıt metni
recommendationsÖnerilen hizmet ve ürün sayısı
off_topicYapay zekâ soruyu kapsam dışı olarak işaretlediyse true

(promptor/chat_extra_context daha önce, istem oluşturulurken çalışır ve bunların yerine user_query, context_name ve source_post_ids alır.)

promptor/chat_extra_context

Sistem istemine "ADDITIONAL CONTEXT" başlığı altında eklenecek düz metni döndürün. Varsayılan: boş dize. Pro bunu çalışma saatleri ve oturum açmış bir müşterinin WooCommerce siparişleri için kullanır.

add_filter( 'promptor/chat_extra_context', function ( $extra, $args ) {
    return trim( $extra . "\nOur showroom is closed on public holidays." );
}, 10, 2 );

promptor/chat_unanswered

Sorunun yanıtlanmamış olarak işaretlenip işaretlenmeyeceğine karar verir (unanswered sütununda saklanır ve Yanıtlanmamış (Unanswered) görünümünde listelenir). Varsayılan: hiçbir bilgi tabanı içeriği bulunmadığında ve soru konu dışı olmadığında true. Başparmak aşağı oyu da soruyu işaretler. Yanıtlanmamış soruları inceleme makalesine bakın.

promptor/chat_actions

Yanıtın altında gösterilen eylem çiplerini filtreler. Varsayılan: Promptor'un kendi özelliklerinin doldurduğu boş bir dizi: temsilciye devirden gelen "Bir temsilciyle görüşün" ("Talk to a human") çipi ile Pro "Görüşme planla" ("Book a call") ve kupon çipleri. Her çip type ve label içeren bir dizidir; open_url ve booking için ek olarak url, custom için payload içerir. Desteklenen türler: open_url, booking, quote, handoff, coupon, custom. Sohbet arayüzü bilinmeyen türleri yok sayar. Yanıt konu dışıysa yalnızca handoff çipleri korunur.

add_filter( 'promptor/chat_actions', function ( $actions, $args ) {
    if ( false !== stripos( $args['user_query'], 'warranty' ) ) {
        $actions[] = array(
            'type'  => 'open_url',
            'label' => 'Warranty terms',
            'url'   => home_url( '/warranty/' ),
        );
    }
    return $actions;
}, 10, 2 );

Bir custom çipi, document üzerinde detail.action (çip) ve detail.context ile bir promptor:action DOM olayı tetikler; böylece kendi JavaScript kodunuz tepki verebilir. Yanıtların altındaki eylem düğmeleri makalesine bakın.

promptor/chat_handoff

Sohbet arayüzünün bir temsilci önerip önermeyeceğini filtreler. Varsayılan: array( 'suggest' => false, 'reason' => '', 'summary' => '' ). Promptor'un temsilciye devir özelliği suggest değerini true yapar ve reason olarak requested veya low_confidence verir.

Temsilciye devir

promptor/handoff_request_keywords

"Bir kişiyle görüşmek istiyorum" anlamına gelen ifadeleri filtreler (İngilizce, Türkçe, Almanca, İspanyolca, Fransızca, İtalyanca ve Portekizce yerleşik olarak gelir). Eşleştirme büyük/küçük harfe duyarsızdır ve kelime sınırlarını dikkate alır. Kendi dilinizi veya ifadelerinizi buraya ekleyin.

add_filter( 'promptor/handoff_request_keywords', function ( $keywords ) {
    $keywords[] = 'met een medewerker';
    return $keywords;
} );

promptor/handoff_frontend_config

Sohbet arayüzüne aktarılan temsilciye devir ayarlarını filtreler: enabled, channels, show_channel_buttons, include_summary, livechat_launch, livechat_custom_js, hours (enabled, is_open, next_open) ve away_message.

promptor_handoff

Bir ziyaretçi bir devir kanalı seçtiğinde veya canlı sohbeti açtığında tetiklenir. $event şunları içerir: time, channel, reason (requested, low_confidence veya manual), context, summary, page_url, transcript ve user_id. Promptor son 50 olayı promptor_handoff_log seçeneğinde tutar; Pro'da, açtıysanız konuşma dökümünü Slack'e veya e-postaya da gönderir. Ziyaretçileri bir temsilciye yönlendirme makalesine bakın.

add_action( 'promptor_handoff', function ( $event ) {
    error_log( sprintf( 'Promptor handoff via %s (%s)', $event['channel'], $event['reason'] ) );
} );

Etkileşim

promptor/engagement_should_render

Ayarlar › Etkileşim (Settings › Engagement) bölümündeki sayfa hedefleme kuralları uygulandıktan sonra kayan açılır pencerenin geçerli sayfada gösterilip gösterilmeyeceğini filtreler. Gizlemek için false döndürün.

promptor/engagement_frontend_config

Sohbet arayüzüne aktarılan etkileşim ayarlarını filtreler: trigger, trigger_delay, trigger_scroll, greeting, booking_url ve booking_label.

promptor/booking_intent_pattern

Bir sorunun randevuyla ilgili olup olmadığına karar veren düzenli ifadeyi filtreler; bu da Pro "Görüşme planla" çipini gösterir. Karşılama mesajı, sayfa hedefleme ve etkileşim tetikleyicileri makalesine bakın.

Ön yüz ve dil

promptor/public/ui_settings

Bir sohbetin birleştirilmiş arayüz ayarlarını, Promptor bunları CSS değişkenlerine dönüştürüp sohbet arayüzüne aktarmadan önce filtreler. Anahtarlar promptor_ui_settings seçeneğiyle eşleşir; örneğin primary_color, user_bubble_color, widget_bg_color, header_title, header_subtitle, input_placeholder, font_size, border_radius.

add_filter( 'promptor/public/ui_settings', function ( $settings ) {
    if ( is_page( 'support' ) ) {
        $settings['header_title']  = 'Support Assistant';
        $settings['primary_color'] = '#0f766e';
    }
    return $settings;
} );

promptor/public/example_questions

Sohbet açıldığında gösterilen önerilen soruları filtreler. $questions soruları tutar; $context_key bilgi tabanı anahtarıdır.

Değiştirmeden önce $questions değerinin kendi kurulumunuzdaki türünü error_log( print_r( $questions, true ) ) ile kontrol edin ve aynı türü döndürün.

promptor/available_languages

Ayarlar › Kullanıcı Arayüzü Ayarları › Dil (Settings › UI Settings › Language) bölümünde sunulan dilleri locale => label dizisi olarak filtreler. Varsayılan olarak İngilizceyi ve Promptor'un languages klasöründe bulunan her paketlenmiş çeviriyi listeler. Eklenti dilini değiştirme makalesine bakın.

Bilgi tabanı

promptor/content_selection_post_types

İçerik seçiminde sekme olarak sunulan yazı türlerini filtreler. $post_types, adlarına göre anahtarlanmış WP_Post_Type nesnelerinden oluşan bir dizidir. Bir türün sekmesini gizlemek için onu kaldırın.

add_filter( 'promptor/content_selection_post_types', function ( $post_types ) {
    unset( $post_types['attachment'], $post_types['e-landing-page'] );
    return $post_types;
} );

promptor/default_content_role

Bir yazı türü için varsayılan İçerik Rolü'nü (Content Role) filtreler. service, product, blog veya faq döndürün; başka herhangi bir değer blog olur.

add_filter( 'promptor/default_content_role', function ( $role, $post_type ) {
    return 'treatment' === $post_type ? 'service' : $role;
}, 10, 2 );

promptor/item_indexed

Bir yazı, sayfa, ürün, dosya veya Soru-Cevap girdisi; Senkronize Et (Sync) ile, yayımlama veya güncellemede otomatik yeniden dizinlemeyle ya da bir Soru-Cevap girdisinin kaydedilmesiyle dizine eklendikten veya yeniden dizine eklendikten sonra tetiklenir. Pro tarayıcıyla URL üzerinden dizine eklenen sayfalar bu kancayı tetiklemez. Argümanlar: yazı kimliği, bilgi tabanı anahtarı ve oluşturulan parça sayısı.

Yönetim

promptor/settings_tabs

Promptor'un Ayarlar (Settings) ekranındaki sekmeleri slug => tab object olarak filtreler. Bir sekme nesnesinin render() yöntemine sahip olması gerekir; register_settings() ve get_label() yöntemleri de olabilir. Promptor kendi 2.1.0 sekmelerini (Temsilciye Devir ve Kanallar (Handoff & Channels), Etkileşim, MCP Sunucusu (MCP Server), WooCommerce Asistanı (WooCommerce Assistant)) bu filtre üzerinden kaydeder.

Müşteri adayları

promptor_before_insert_submission

Müşteri adayı satırını {prefix}promptor_submissions tablosuna kaydedilmeden hemen önce filtreler. $data şunları içerir: name, email, phone, recommendations, notes, query_id ve submitted_at. recommendations, Services: Web Design, SEO; Products: Starter Kit gibi bir dizedir.

add_filter( 'promptor_before_insert_submission', function ( $data ) {
    $data['notes'] = trim( $data['notes'] . "\n\nSource page: " . wp_get_referer() );
    return $data;
} );

promptor_after_insert_submission

Bir müşteri adayı kaydedildikten sonra tetiklenir. Yeni satır kimliğini ve aynı $data değerini alır.

promptor_lead_created

Bir müşteri adayı kaydedildikten hemen sonra ve e-posta ile Slack bildirimleri gönderilmeden önce tetiklenir. $lead şunları içerir: id, name, email, phone, message, services (hizmet başlıkları dizisi) ve products. Pro bu eylemi webhook'lar (öncelik 10) ve müşteri adayı puanlaması (öncelik 20) için kullanır.

add_action( 'promptor_lead_created', function ( $submission_id, $lead ) {
    wp_remote_post( 'https://crm.example.com/api/leads', array(
        'timeout' => 10,
        'headers' => array( 'Content-Type' => 'application/json' ),
        'body'    => wp_json_encode( array(
            'external_id' => $submission_id,
            'name'        => $lead['name'],
            'email'       => $lead['email'],
            'phone'       => $lead['phone'],
            'services'    => $lead['services'],
        ) ),
    ) );
}, 10, 2 );

Bu müşteri adayı kancaları, ziyaretçi formun gönderilmesini beklerken çalışır. Onları hızlı tutun veya işi wp_schedule_single_event() ile kuyruğa alın. Pro ile bunun yerine webhook'ları kullanabilirsiniz.

promptor_lead_scored (Pro)

Pro yeni bir müşteri adayını puanladıktan sonra tetiklenir. $score şunları içerir: lead_id, email, lead_score (0–105), lead_temperature (hot, warm veya cold), confidence_level, scoring_factors, scoring_details, scored_at ve score_version. Webhook yükünde bulunmayan puana ihtiyacınız olduğunda kullanın. Müşteri adayı puanlama: Hot, Warm ve Cold makalesine bakın.

Webhook'lar (Pro)

promptor_webhook_payload, promptor_webhook_headers ve promptor_webhook_event_enabled, Promptor'un webhook URL'nize gönderdiklerini değiştirir. Örnekleriyle birlikte Webhook yükü ve imza doğrulama makalesinde belgelenmiştir.

WooCommerce ürünleri (Pro)

promptor_before_update_query_products

Bir sohbet için products_added_to_cart alanına kaydedilmek üzere olan, virgülle ayrılmış ürün kimlikleri listesini filtreler. Argümanlar: $products_csv, $query_id.

promptor_after_update_query_products

Bu liste kaydedildikten sonra tetiklenir. Argümanlar: $query_id, $products_csv.

MCP sunucusu (Pro)

promptor/mcp_route

promptor/v1 REST ad alanı altındaki MCP uç noktası yolunu filtreler. Varsayılan değer Ayarlar › MCP Sunucusu (Settings › MCP Server) bölümündeki Uç nokta yolu (Endpoint path) alanından gelir (mcp). İzin verilen karakterler: harfler, rakamlar, _, - ve /; başka bir şey içerirse mcp değerine geri döner. Yönetim ekranı ve bağlantı kod parçacıkları her zaman filtrelenmiş değeri gösterir. Claude, ChatGPT veya Cursor'ı MCP sunucusuyla bağlama makalesine bakın.

promptor/mcp_is_pro ve promptor/mcp_data_service de vardır. Bunlar Promptor'un kendi test paketi için test noktalarıdır; canlı bir sitede kullanmayın.

Lisanslama

promptor_fs_loaded

Promptor Freemius lisanslama SDK'sını başlattıktan sonra tetiklenir. Argüman almaz.

Sabitler

Bunları wp-config.php dosyasında yalnızca ihtiyacınız olduğunu biliyorsanız tanımlayın (ücretsiz sürüm):

SabitAmaç
PROMPTOR_TRIAL_API_URLÜcretsiz deneme arka uç URL'sini geçersiz kılar.
PROMPTOR_TELEMETRY_HMAC_SECRETİsteğe bağlı telemetriyi imzalamak için kullanılan anahtarı geçersiz kılar.

PROMPTOR_VERSION, PROMPTOR_PATH ve PROMPTOR_URL eklenti tarafından tanımlanır ve kodunuzda okunabilir.

İlgili makaleler

Hâlâ yardıma mı ihtiyacınız var?

Destek ekibimiz her talebi yanıtlar. WordPress sürümünüzü, Promptor sürümünüzü ve ne gördüğünüzü yazın.

SSS'yi okuyunHer sürümde nelerin değiştiğini görün

Destek talebi oluştur

Tüm yardım konuları