Etkinlikler

Etkinlikler, temsilcinizin gönderebileceği ve alabileceği bildirimlerdir. Üç tür etkinlik vardır:

Sunucu tarafından oluşturulan etkinlikler

RBM platformu, temsilcinizi mesajların süresinin dolması gibi sunucu düzeyindeki güncellemeler hakkında bilgilendirmek için etkinlikler gönderir.

Biçimlendirme ve değer seçenekleri için ServerEvent bölümüne bakın.

Temsilci başlatma durumu değişti

RBM platformu, temsilcinizin kullanıma sunma durumundaki her değişiklik için bir AgentLaunchEvent gönderir. Örneğin, operatör onayı sonrasında temsilcinizin durumu PENDING olarak değiştiğinde değişikliği belirtmek için bir AgentLaunchEvent etkinliği alırsınız.LAUNCHED Bu etkinlikler, tüm operatör lansman durumu değişiklikleri için tüm RBM aracılarına gönderilir.

Webhook yapılandırması

Bu bildirimleri almak için iş ortağı düzeyinde veya temsilci düzeyinde webhook kullanabilirsiniz.

Ön koşullar

Etkinlik yükü yapısı

AgentLaunchEvent, Pub/Sub mesajı olarak iletilir. Aşağıda bununla ilgili bir örnek verilmiştir:

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

Etkinlik yükündeki AgentLaunchEvent.LaunchState alanı, aracının yeni başlatma durumunu gösterir. Olası değerler şunlardır:

Değer Temsilci başlatma durumu Ayrıntılar
UNLAUNCHED Başlatılmamış Düzenlemeye izin verilir.
PENDING Beklemede İstek, incelenmek üzere bir operatöre gönderildi.
LAUNCHED Başlatıldı Belirli bir operatörde iletilere izin verilir.
REJECTED Belirli bir kargo şirketi tarafından reddedildi Ret nedeni yorumda belirtilir.
SUSPENDED Belirli bir operatörde askıya alınmış Askıya alınma nedeni yorumda belirtilir.

Veri alanı, lansman durumu ayrıntılarını içeren Base64 kodlu bir JSON nesnesi içerir. Aşağıda, kodu çözülmüş JSON örneği verilmiştir:

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

Aşağıdaki tabloda, aracı başlatma durumları ve bunları tetikleyen işlemler gösterilmektedir:

Eski başlatma durumu Yeni başlatma durumu Değişiklik tetikleyicisi
PENDING LAUNCHED Temsilci onayı bekleniyor.
PENDING REJECTED Beklemedeki temsilci reddedildi.
LAUNCHED SUSPENDED Başlatılan aracı askıya alındı.
SUSPENDED LAUNCHED Askıya alınmış temsilci yeniden etkinleştirildi.
SUSPENDED TERMINATED Askıya alınan temsilci sonlandırıldı.
TERMINATED LAUNCHED Sonlandırılan temsilci başlatıldı.

Mesajın süresi doldu; iptal işlemi başarılı oldu

Mesajın süresi doldu ve başarıyla iptal edildi. Bu etkinlik, yedek mesajlaşma stratejiniz için iyi bir tetikleyici olabilir.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

Mesajın süresi doldu; iptal işlemi başarısız oldu

Mesajın süresi doldu ancak iptal edilmedi.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

İletilerin teslim edileceği garanti edilmez.

  • İleti teslim edildiyse webhook'unuza DELIVERED etkinliği gönderilir.
  • İleti teslim edilmediyse iptal isteği göndermek için iptal API'sini kullanın.

Mesaj zamana duyarlıysa (ör. tek kullanımlık şifre veya sahtekarlık uyarısı) kullanıcıya yinelenen mesajlar gönderilse bile mesajı SMS gibi alternatif bir kanal üzerinden göndermek en iyisidir.

Kullanıcı tarafından oluşturulan etkinlikler

Kullanıcı mesajlarında ve yetenek kontrollerinde olduğu gibi, temsilciniz kullanıcı etkinliklerini JSON olarak alır.

Biçimlendirme ve değer seçenekleri için UserEvent bölümüne bakın.

Kullanıcı, temsilci mesajını alır

Bu etkinlik, bir iletinin teslim edildiğini gösterir.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Kullanıcı, temsilci mesajını okur

Bu etkinlik, bir iletinin açıldığını veya onaylandığını gösterir.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Kullanıcı yazmaya başladığında

Bu etkinlik, kullanıcının yazdığını gösterir.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Kullanıcı kısa mesaj gönderir

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Kullanıcı dosya gönderir

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Kullanıcı, önerilen bir yanıta dokunur.

Kullanıcı, önerilen bir yanıta dokunduğunda temsilciniz, yanıtın geri gönderme verileri ve metniyle birlikte bir etkinlik alır.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

Kullanıcı, önerilen bir işleme dokunur.

Kullanıcı, önerilen bir işleme dokunduğunda aracınız, işlemin geri gönderme verilerini içeren bir etkinlik alır.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

Kullanıcı, ileti dizisinden e-posta listesinden çıkarılır.

Bir kullanıcı, işletmelerden gerekli olmayan mesajlar (ör. promosyonlar) almak istemiyorsa Google Mesajlar'da RBM görüşmesinin aboneliğinden çıkabilir.

UNSUBSCRIBE etkinliği, kullanıcının temsilcinizle ve temsil ettiği işletmeyle olan görüşme aboneliğini iptal ettiğini gösterir. JSON yükü örneğini burada bulabilirsiniz:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

İşleyiş şekli

  • Sohbet menüsünde her zaman E-posta listesinden çık seçeneği bulunur. Tanıtım amaçlı ve çok kullanımlı temsilciler için bu seçenek, belirli sayıda okunmamış mesajdan sonra doğrudan sohbette de gösterilir (ülkeye göre farklı kurallar geçerlidir).

  • Abonelikten çık'ı seçtiğinizde iki işlem aynı anda tetiklenir: Google Mesajlar, temsilcinize ülkeye özgü bir anahtar kelime (ör. "DUR") gönderir ve RBM platformu, webhook'unuza bir UNSUBSCRIBE etkinliği gönderir.

    Anahtar kelime, kullanıcının telefon numarasının iki harfli ülke koduyla belirlenir. Aşağıdaki tabloda, desteklenen her ülke için anahtar kelimeler listelenmektedir.

    Ülke (ülke kodu) Abonelikten çıkma anahtar kelimesi
    ABD (US), Hindistan (IN), Birleşik Krallık (GB), Almanya (DE) DURDUR
    İspanya (ES), Meksika (MX) BAJA
    Fransa (FR) DURDUR
    Brezilya (BR) parar

  • Kullanıcı e-posta listesinden çıktıktan sonra, spam olarak bildirilmediği sürece ileti dizisi gelen kutusunda kalır. Spam olarak bildirilirse Spam ve engellenenler klasörüne taşınır.

  • Google, politika ve işletme kuralı ihlallerini belirlemek için kullanıcının e-posta listesinden çıkmasının ardından mesaj kalıplarını izler.

İşletme kuralları

  • Bu görüşmeyi yöneten RBM iş ortağı olarak, kullanıcının e-posta listesinden çıkma isteğine uymak sizin sorumluluğunuzdadır.
  • Abonelikten çıkma işlemini ileti dizisinde gerçekleştiremiyorsanız kullanıcıların abonelik tercihlerini yönetebileceği web sitesine veya uygulamaya doğrudan bağlantı içeren bir onay mesajını hemen göndermeniz gerekir.
  • Kullanıcı abonelikten çıktıktan sonra gerekli olmayan mesajlar göndermek yasaktır.
  • Önemli mesajlara izin verilmeye devam edilir. Bunlardan bazıları:
    • Tek kullanımlık şifreler (OTP'ler) gibi kimlik doğrulamalar
    • Kullanıcının istediği ve izin verdiği belirli bir hizmetle ilgili bildirimler
    • Kullanıcının e-posta listesinden çıkma isteğinin onaylandığına dair bilgi ve iletişim tercihlerini daha ayrıntılı yönetmeyle ilgili bilgiler

Örnek

Kullanım alanı çoklu kullanım olan bir havayolu temsilcisinin e-posta listesinden çıkan kullanıcılara pazarlama mesajları göndermeyi durdurmanız gerekir. Ancak, kullanıcı söz konusu uçuşla ilgili güncellemeleri almayı açıkça kabul ettiyse uçuş güncellemeleri gönderebilirsiniz.

Abonelikten çıkma nedenleri

Kullanıcılar, temsilcinizin e-posta listesinden çıkarken aşağıdaki seçeneklerden birini belirleyebilir:

  • Kaydolunmadı
  • Çok sayıda mesaj
  • Artık ilgimi çekmiyor
  • Spam
  • Diğer

Şu anda, e-posta listesinden çıkma nedenleri iş ortakları veya operatörlerle paylaşılmamaktadır.

Kullanıcı, görüşmeye yeniden abone olur.

Kullanıcılar, Google Mesajlar'da daha önce aboneliklerini iptal ettikleri bir ileti dizisine yeniden abone olabilir.

SUBSCRIBE etkinliği, kullanıcının promosyonlar gibi gerekli olmayan içerikler de dahil olmak üzere temsilcinizden mesaj almak istediğini gösterir. JSON yükü örneğini aşağıda bulabilirsiniz:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

İşleyiş şekli

  • Hem sohbet menüsünden hem de sohbet içi bağlantıdan erişilebilen Abone ol seçeneği, kullanıcıların abonelikten çıktıkları bir sohbete yeniden abone olmalarını sağlar.

  • Abone ol'u seçtiğinizde iki işlem aynı anda tetiklenir: Google Mesajlar, temsilcinize ülkeye özgü bir anahtar kelime (ör. "BAŞLA") gönderir ve RBM platformu, webhook'unuza bir SUBSCRIBE etkinliği gönderir.

    Belirli anahtar kelime, kullanıcının telefon numarasının iki harfli ülke koduna göre belirlenir. Aşağıdaki tabloda, desteklenen her ülke için anahtar kelimeler listelenmektedir.

    Ülke (ülke kodu) Abone olma anahtar kelimesi
    ABD (US), Hindistan (IN), Birleşik Krallık (GB), Almanya (DE) BAŞLAT
    İspanya (ES), Meksika (MX) ALTA
    Fransa (FR) Démarrer
    Brezilya (BR) começar

İşletme kuralları

  • Bu görüşmeyi yöneten RBM iş ortağı olarak, kullanıcının yeniden abone olma isteğine uymak sizin sorumluluğunuzdadır.
  • Yeniden abonelik, promosyonlar gibi zorunlu olmayan içerikler de dahil olmak üzere tüm mesaj türleri için geçerlidir.
  • Bir kullanıcı, e-posta listesinden çıktıktan sonra işletmenize mesaj gönderirse bu, yeniden abone olma isteği olarak değerlendirilebilir.
  • Kullanıcı, mesajlaşma kanalı dışında (örneğin, web sitenizde) yeniden abone olursa durumunu güncellemek ve buna göre mesaj göndermeye devam etmek RBM iş ortağı olarak sizin sorumluluğunuzdadır.

Aracı tarafından oluşturulan etkinlikler

Temsilciniz, insan etkileşimlerini simüle etmek ve kullanıcıya temsilcinizin mesajlarıyla etkileşimde bulunduğunu bildirmek için etkinlikler gönderir. Kullanıcılar için etkinlikler, görüşmelerinde bildirim olarak gösterilir.

Biçimlendirme ve değer seçenekleri için phones.agentEvents bölümüne bakın.

Temsilci, READ etkinliğini gönderir.

Bu etkinlik, kullanıcılara belirli bir mesajın okunma onayı olarak görünür. Bu mesaj, RBM platformunun kullanıcının mesajını ilettiğini ve temsilcinin mesajı işlediğini bildirir.

Aşağıdaki kod, eşleşen messageId içeren bir ileti için READ etkinliğini gönderir.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 Bu kod, RBM örnek temsilcisinden alınmıştır.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 Bu kod, RBM örnek temsilcisinden alınmıştır.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 Bu kod, RBM örnek temsilcisinden alınmıştır.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 Bu kod, RBM örnek temsilcisinden alınmıştır.

Temsilci, IS_TYPING etkinliğini gönderir.

Bu etkinlik, kullanıcılara yazma göstergesi olarak görünür ve temsilcinizin mesaj yazdığını bildirir. Yazma göstergesi kısa bir süre sonra (yaklaşık 20 saniye) veya kullanıcının cihazı temsilcinizden yeni bir mesaj aldığında sona erer. Aracınız, yazma göstergesinin geçerlilik bitiş zamanlayıcısını sıfırlamak için birden fazla IS_TYPING etkinliği gönderebilir.

Aşağıdaki kod, bir IS_TYPING etkinliği gönderir.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 Bu kod, RBM örnek temsilcisinden alınmıştır.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 Bu kod, RBM örnek temsilcisinden alınmıştır.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 Bu kod, RBM örnek temsilcisinden alınmıştır.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 Bu kod, RBM örnek temsilcisinden alınmıştır.
Önceki
İleti alma
Sonraki
Yetenek kontrolleri