İstemler

İstemler, İşleminizin kullanıcılara yanıtları nasıl oluşturacağını ve İşleminizin kullanıcıların devam etmesini nasıl istediğini tanımlar. İşleminizi oluştururken çağrılara ve sahne içindeki çeşitli yerlere istem ekleyebilirsiniz. İstemler, metin veya sesli yanıt kadar basit olabileceği gibi daha karmaşık da olabilir ve kart, resim, tablo gibi zengin içerikler içerebilir.

Yanıt türleri

Her istemde, Asistan'ın kullanıcılara sunabileceği çeşitli ilgi çekici yanıt türleri arasından seçim yaparsınız:

• Basit yanıtlar: Basit yanıtlar görsel olarak sohbet balonu biçiminde olur ve ses için metin okuma (TTS) veya Konuşma Sentezi Biçimlendirme Dili (SSML) kullanılır. Tüm cihaz türlerinde yalnızca basit yanıtlar desteklenir.
• Zengin yanıtlar: Zengin yanıtlar, kullanıcılarınızın İşlemlerinizle etkileşimini geliştiren görsel veya işlevsel öğeler içerir. Zengin yanıtlar sayesinde, ayrıca tablo biçiminde veriler görüntüleyebilir veya daha uzun biçimli ses içeriklerini oynatabilirsiniz.
• Görsel seçim yanıtları: Görsel seçim yanıtları, kullanıcıların birden fazla seçenek arasından seçim yapabilecekleri görsel bir arayüz sağlar. Bu seçenekler, başlıkları veya bir resim ile en kolay ayırt edilebilir.
• Medya yanıtları: Medya yanıtları, İşlemlerinizin SSML'den daha uzun sesli içerik oynatmasına olanak tanır ve medya denetimleriyle görsel bir bileşen sağlar.
• Etkileşimli Tuval: Etkileşimli Tuval, yanıtları tam ekran web görünümleri olarak oluşturur ve Asistan'ın, görüşmedeki kullanıcıya yanıt olarak gönderdiği etkileşimli bir web uygulaması olarak çalışır. Tuval; HTML, CSS ve JavaScript gibi web standartlarının sağladığı daha fazla esneklik için biraz farklı bir istem biçimi kullanır.

Bu yanıt türlerinin her biri aynı temel istem biçimini kullanır ve aşağıda açıklanan aynı genel özelliklere erişebilir.

İstemin biçimi

Actions projenizde istemleri YAML veya JSON biçiminde tanımlarsınız. Her istem, en fazla iki basit yanıt içerebilir ve isteğe bağlı olarak zengin bir yanıt tanımlayabilir. Yanıtlar aşağıdaki şekillerde tanımlanır:

• first_simple: Kullanıcıya gönderilecek ilk metin veya konuşma (basit) yanıtı.
• content: Basit yanıtlardan sonra gönderilecek ek zengin yanıt içeriği.
• last_simple Kullanıcıya gönderilecek son metin veya konuşma (basit) yanıtı.
• canvas: Etkileşimli Tuval ile entegre olan bir web uygulamasına referans verir.

Varsayılan olarak istemler, bir istem sırasında yukarıdaki sırayla birbirlerine eklenir. Asistan, kullanıcının yanıt verebilmesi için istem sırasındaki tüm istemleri sunar.

Ayrıca, aşağıdaki özellikleri kullanarak isteme esneklik sağlarsınız:

• Adaylar: Adaylar, bir kullanıcının cihaz özelliklerine göre yanıtlar tanımlamanızı sağlar. Örneğin, Asistan'ın yalnızca bir kullanıcı görüntüleme özellikli bir cihazda İşleminizle etkileşimde bulunduğunda zengin yanıtlar göstermesini sağlayabilirsiniz.
• Varyantlar: Varyantlar, tek bir mesajın alternatif varyasyonlarıdır. Örneğin, bir kullanıcı İşleminizi her çağırdığında Asistan'ın beş farklı hoş geldiniz mesajı varyantı arasından seçim yapmasını sağlayabilirsiniz.
• Öneriler: Öneriler, Asistan istemi görüntülediğinde görüntüleme özellikli cihazlardaki kullanıcılara öneri çipleri sağlar.

Varsayılan istem bir aday, bir varyant ve bir first_simple yanıtı kullanır.

Adaylar

Bir istemdeki candidates nesnesi, yanıtları kullanıcının cihaz özelliklerine göre tanımlamanıza olanak tanır. Örneğin, Asistan'ın yalnızca bir kullanıcı görüntüleme özellikli bir cihazda İşleminizle etkileşimde bulunduğunda zengin yanıtlar göstermesini sağlayabilirsiniz. Asistan'ın bir aday döndürebileceği cihaz türlerini tanımlamak için candidates nesnesinin selector özelliğini kullanın.

Aşağıdaki örnekte, selector özelliği cihaz özellikleri bilgilerini içerir. İlk adayda ayarlanan istemler, zengin yanıtlar oluşturabilen bir cihazda kullanıcılara gönderilir. İkinci aday, yalnızca metin ve konuşma yanıtlarını alabilen kullanıcılar için istemler içerir.

candidates:
  - selector:
      surface_capabilities:
        capabilities:
          - RICH_RESPONSE
    first_simple:
      variants:
        - speech: Here's a simple message.
    content:
      card:
        title: Image card title
        text: Some details about the image
        image:
          url: 'https://www.example.com/image/'
  - first_simple:
      variants:
        - speech: Text explains what the image might have shown in more detail.
    

{
  "candidates": [{
    "selector": {
      "surface_capabilities": {
        "capabilities": ["RICH_RESPONSE"]
      }
    },
    "first_simple": {
      "variants": [{
        "speech": "Here's a simple message."
      }]
    },
    "content": {
      "card": {
        "title": "Image card title",
        "text": "Some details about the image",
        "image": {
          "url": "https://www.example.com/image/"
        }
      }
    }
  }, {
    "first_simple": {
      "variants": [{
        "speech": "Text explains what the image might have shown in more detail."
      }]
    }
  }]
}
    

Belirli bir aday için bir veya daha fazla yetenek koşulu sağlayabilirsiniz. Aşağıdaki listede mevcut özellik gereksinimlerinin her biri açıklanmaktadır:

• SPEECH: Cihaz, metin okuma veya SSML aracılığıyla kullanıcıyla konuşabilir.
• RICH_RESPONSE: Cihaz; kartlar, listeler ve tablolar gibi zengin yanıtlar görüntüleyebilir.
• LONG_FORM_AUDIO: Cihaz, müzik ve podcast gibi uzun biçimli ses medyalarını çalabilir.
• INTERACTIVE_CANVAS: Cihaz, Etkileşimli Tuval yanıtı görüntüleyebilir.
• WEB_LINK: Cihaz, bir web tarayıcısını açmak için zengin yanıtlardaki web bağlantılarını kullanabilir.
• HOME_STORAGE: Cihaz, ev depolama alanındaki verilere erişebilir ve bunlara erişebilir.

Varyantlar

Varyantlar, bir yanıtın birden çok sürümünü tanımlama yöntemi sağlar. Asistan, istemi kullanıcıya gönderdiğinde varyantlardan biri rastgele seçilir. Sohbet tasarımında en iyi uygulamalardan biri olarak, kullanıcılara İşleminizle sohbet ederken alternatif yanıtlar verin.

Örneğin, kullanıcıların İşleminizi her çağırdığında aynı yanıtı duymaması için farklı karşılama mesajı varyantları sağlayın:

candidates:
  - first_simple:
      variants:
        - speech: Hello.
        - speech: Hi there.
        - speech: Welcome.
    

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Hello."
      },{
        "speech": "Hi there."
      },{
        "speech": "Welcome."
      }]
    }
  }]
}
    

Öneriler

Öneriler, Asistan istemi görüntülediğinde görüntüleme özellikli cihazlardaki kullanıcılara öneri çipleri sağlar. Konuşmaya devam etmek veya görüşmenin gidişatını değiştirmek için kullanıcı yanıtlarına ipucu vermek amacıyla öneri çiplerini kullanın. Öneri çipi dokunulduğunda, gösterilen metni kullanıcı yazmış gibi tam olarak görüşmenin haline döndürür.

Tek bir istemde, her biri maksimum 25 düz metin karakterinden oluşan en fazla 8 öneriniz olabilir.

Öneri eklemek için her öneriyi içeren bir Suggestion nesnesini ayrı bir title alanında sağlayın. Öneri çipi grubundaki her başlık benzersiz olmalıdır. Actions Builder'da bu nesne, YAML ve JSON'de suggestions olarak temsil edilir.

Örneğin, bir sorunun yanında "Evet" ve "Hayır" önerilerinde bulunabilirsiniz:

candidates:
  - first_simple:
      variants:
        - speech: 'Welcome, do you want to play a game?'
    suggestions:
      - title: 'Yes'
      - title: 'No'
    

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Welcome, do you want to play a game?"
      }]
    },
    "suggestions": [{
      "title": "Yes"
    }, {
      "title": "No"
    }]
  }]
}