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 durumuyla ilgili her değişiklik için AgentLaunchEvent gönderir. Örneğin, operatör onayı sonrasında temsilcinizin durumu PENDING'dan LAUNCHED'ye değiştiğinde, değişikliği belirtmek için AgentLaunchEvent etkinliği alırsınız. 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'unuzu 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 verilmektedir.
PENDING Beklemede Talep incelenmek üzere bir taşıyıcıya gönderildi.
LAUNCHED Başlatıldı Mesajlara belirli bir operatör üzerinden izin verilir.
REJECTED Belirli bir taşıyıcıda reddedildi Reddedilme nedeni yorumda belirtilmiştir.
SUSPENDED Belirli bir operatörde askıya alınmış Askıya alınma nedeni yorumda belirtilmiştir.

Veri alanı, başlatma durumu ayrıntılarını içeren Base64 kodlu bir JSON nesnesi içerir. İşte çözülmüş JSON'un bir örneği:

    {
      "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 eylemler gösterilmektedir:

Eski başlatma durumu Yeni başlatma durumu Değişimin tetikleyicisi
PENDING LAUNCHED Temsilci onayı bekleniyor.
PENDING REJECTED Bekleyen temsilci reddedildi.
LAUNCHED SUSPENDED Başlatılan ajan askıya alındı.
SUSPENDED LAUNCHED Askıya alınan ajan yeniden etkinleştirildi.
SUSPENDED TERMINATED Askıya alınmış temsilci sonlandırıldı.
TERMINATED LAUNCHED Sonlandırılan ajan 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 olay, geri dönüş mesajlaşma stratejiniz için iyi bir tetikleyici olacaktır.

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

İletinin teslim edileceği garanti edilmez.

  • Mesaj iletildiyse, webhook'unuzda bir DELIVERED olayı alacaksınız.
  • İ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 dizisinin e-posta listesinden çıkarılırsa

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 aşağıda 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 (örneğin, "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 koduna göre belirlenir. Aşağıdaki tabloda desteklenen her ülke için anahtar kelimeler listelenmiştir.

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

  • Kullanıcı aboneliğini iptal ettikten sonra, spam olarak bildirilmediği sürece konuşma gelen kutusunda kalır; spam olarak bildirilirse Spam ve engellenen klasörüne taşınır.

  • Google, politika ve iş kuralı ihlallerini tespit etmek için bir kullanıcının aboneliğini iptal etmesinin ardından mesaj modellerini izler.

İş 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 mesaj dizisi içinde gerçekleştiremiyorsanız, kullanıcıların abonelik tercihlerini yönetebilecekleri web sitesine veya uygulamaya doğrudan bağlantı içeren bir onay mesajını hemen göndermelisiniz.
  • Kullanıcının aboneliğinden çıkması sonrasında, zorunlu olmayan mesajların gönderilmesi yasaktır.
  • Temel mesajlara hala izin veriliyor. Bunlar şunları içerir:
    • Tek kullanımlık şifreler (OTP'ler) gibi kimlik doğrulamalar
    • Kullanıcının talep ettiği ve onay verdiği belirli bir hizmete ilişkin bildirimler
    • Kullanıcının e-posta listesinden çıkma isteğinin onaylandığına dair mesaj ve iletişim tercihlerini daha ayrıntılı yönetebileceği bilgiler

Örnek

Bir kullanıcı, kullanım durumu çoklu kullanım olan bir havayolu acentesinden aboneliğini iptal ederse, pazarlama mesajları göndermeyi durdurmalısınız. Ancak, kullanıcı belirli bir uçuş için güncelleme almayı açıkça kabul etmişse, uçuş güncellemeleri gönderebilirsiniz.

Abonelikten çıkma nedenleri

Bir kullanıcı aracınızdan aboneliğini iptal ettiğinde, aşağıdaki seçeneklerden birini seçebilir:

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

Şu anda abonelikten çıkma nedenleri iş ortaklarımız veya operatörlerimizle paylaşılmıyor.

Kullanıcı sohbete yeniden abone olur

Kullanıcılar, Google Mesajlar'da daha önce aboneliğini iptal ettikleri bir sohbete yeniden abone olabilirler.

SUBSCRIBE etkinliği, kullanıcının promosyonlar gibi gerekli olmayan içerikler de dahil olmak üzere aracınızdan 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 aboneliğini iptal ettikleri bir sohbete yeniden abone olmalarını sağlar.

  • Abone Ol'u seçmek iki eş zamanlı eylemi tetikler: Google Mesajlar temsilcinize ülkeye özgü bir anahtar kelime (örneğin, "BAŞLAT") gönderir ve RBM platformu webhook'unuza bir ABONE OL olayı 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 listelenmiştir.

    Ülke (ülke kodu) Abonelik anahtar kelimesi
    Amerika Birleşik Devletleri (ABD), Hindistan (IN), Birleşik Krallık (GB), Almanya (DE) BAŞLAT
    İspanya (ES), Meksika (MX) ALTA
    Fransa (FR) Başlangıç
    Brezilya (BR) começar

İş kuralları

  • Bu görüşmeyi yöneten RBM ortağı olarak, kullanıcının yeniden abone olma isteğini yerine getirmek sizin sorumluluğunuzdadır.
  • Yeniden abonelik, promosyonlar gibi temel olmayan içerikler de dahil olmak üzere tüm mesaj türleri için geçerlidir.
  • Bir kullanıcı aboneliğini iptal ettikten sonra işletmenize mesaj gönderirse bu bir yeniden abonelik talebi olarak değerlendirilebilir.
  • Bir kullanıcı mesajlaşma kanalının 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 olaylar

Temsilciniz, insan etkileşimlerini simüle etmek ve kullanıcıya temsilcinizin mesajlarıyla etkileşimde bulunduğundan emin olmak için olaylar gönderir. Kullanıcılar için etkinlikler, konuşmaları içerisinde bildirim olarak görüntülenir.

Biçimlendirme ve değer seçenekleri için phones.agentEvents konusuna bakın.

Aracı bir READ olayı gönderir

Kullanıcılara bu olay, belirli bir mesajın okundu bilgisi olarak görünür. Kullanıcıya RBM platformunun mesajını ilettiğini ve aracının bunu işlediğini bildirir.

Aşağıdaki kod, messageId ile eşleşen bir mesaj için READ olayı 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, bir RBM örnek aracısından alınan bir alıntıdı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, bir RBM örnek aracısından alınan bir alıntıdı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, bir RBM örnek aracısından alınan bir alıntıdı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, bir RBM örnek aracısından alınan bir alıntıdır.

Aracı bir IS_TYPING olayı gönderir

Bu etkinlik, kullanıcılara yazma göstergesi olarak görünür ve temsilcinizin bir 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ılarınız, yazma göstergesinin geçerlilik süresi 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, bir RBM örnek aracısından alınan bir alıntıdır.
Önceki
İleti alma
Sonraki
Yetenek kontrolleri