이벤트 수신

에이전트는 RBM 플랫폼에서 웹훅 이벤트를 수신하여 사용자 상호작용과 플랫폼 수준 업데이트를 모두 알려줍니다.

이러한 이벤트는 출처별로 분류됩니다.

사용자 이벤트: 사용자의 기기에서 에이전트로 전송되는 알림으로, 에이전트와의 상호작용을 알립니다.
플랫폼 이벤트: RBM 플랫폼에서 전송하는 에이전트 출시 상태 변경 및 메시지 만료에 관한 알림입니다.

에이전트가 사용자의 기기로 전송하는 상태 이벤트에 관한 자세한 내용은 이벤트 전송을 참고하세요.

텍스트, 파일, 위치 등 사용자 메시지를 처리하는 방법에 관한 자세한 내용은 메시지 수신을 참고하세요.

사용자 이벤트

사용자 이벤트는 메시지 상태 또는 정기 결제 변경사항 (예: 사용자가 정기 결제를 취소하거나 Google 메시지에서 재신청함)을 보고하는 사용자의 기기에서 전송되는 알림입니다.

전체 형식 지정 및 값 옵션은 UserEvent 참조를 참고하세요.

사용자가 에이전트 메시지를 수신함

이 이벤트는 메시지가 사용자의 기기로 전송되었음을 나타냅니다.

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

사용자가 에이전트 메시지를 읽음

이 이벤트는 메시지가 열렸거나 확인되었음을 나타냅니다.

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

사용자가 입력을 시작함

이 이벤트는 사용자가 응답을 입력하고 있음을 나타냅니다.

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

사용자가 추천 작업을 탭함

사용자가 추천 작업을 탭하면 에이전트가 작업의 콜백 데이터가 포함된 이벤트를 수신합니다.

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

사용자가 대화의 정기 결제를 취소함

이 이벤트는 사용자가 에이전트 및 에이전트가 대표하는 비즈니스에서 프로모션과 같은 불필요한 메시지를 수신 거부했음을 나타냅니다. 사용자는 Google 메시지에서 RBM 대화의 정기 결제를 취소하여 이 이벤트를 트리거합니다.

중요: 개발자가 새로운 UNSUBSCRIBE 및 SUBSCRIBE 웹훅 이벤트로 전환할 수 있도록 Google 메시지는 웹훅 이벤트와 함께 "STOP" 및 "START" 메시지도 전송합니다. 지금은 기존의 STOP/START 로직을 사용해도 되지만, GSMA 사양을 준수하기 위해 UNSUBSCRIBE 및 SUBSCRIBE 이벤트를 처리하도록 로직을 업데이트하는 것이 좋습니다.

다음은 JSON 페이로드의 예입니다.

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

정기 결제 취소 작동 방식

정기 결제 취소 옵션은 항상 채팅 메뉴 내에서 사용할 수 있습니다. 프로모션 및 다용도 에이전트의 경우 이 옵션은 읽지 않은 메시지가 일정 수에 도달한 후 채팅에 직접 표시되기도 합니다 (구체적인 규칙은 국가마다 다름).

정기 결제 취소 를 선택하면 두 가지 작업이 동시에 트리거됩니다. Google 메시지는 국가별 키워드 (예: 'STOP')를 에이전트로 전송하고 RBM 플랫폼은 UNSUBSCRIBE 이벤트를 웹훅으로 전송합니다.

키워드는 사용자의 전화번호에 있는 두 글자로 된 국가 코드로 결정됩니다. 다음 표에는 지원되는 각 국가의 키워드가 나와 있습니다.

국가 (국가 코드)	정기 결제 취소 키워드
미국 (US), 인도 (IN), 영국 (GB), 독일 (DE), 네덜란드 (NL)	STOP
스페인 (ES), 멕시코 (MX)	BAJA
프랑스 (FR)	STOP
브라질 (BR)	parar

사용자가 정기 결제를 취소한 후 대화는 스팸으로 신고되지 않는 한 받은편지함에 남아 있으며, 스팸으로 신고되면 스팸 및 차단된 대화 폴더로 이동합니다.
정책 및 비즈니스 규칙 위반을 식별하기 위해 Google은 사용자가 정기 결제를 취소한 후 메시지 패턴을 모니터링합니다.

비즈니스 규칙

이 대화를 관리하는 RBM 파트너는 정기 결제 취소 요청을 준수해야 합니다.
메시지 스레드 내에서 정기 결제를 취소할 수 없는 경우 사용자가 정기 결제 환경설정을 관리할 수 있는 웹사이트 또는 앱으로 연결되는 직접 링크가 포함된 확인 메시지를 즉시 전송해야 합니다.
사용자가 정기 결제를 취소한 후에는 불필요한 메시지를 전송할 수 없습니다.
필수 메시지는 계속 허용됩니다. 필수 메시지에는 다음이 포함됩니다.
- 일회용 비밀번호 (OTP)와 같은 인증
- 사용자가 요청하고 동의한 특정 서비스에 관한 알림
- 사용자의 정기 결제 취소 요청 확인(통신 환경설정을 추가로 관리할 수 있는 정보 포함)

예

사용 사례가 다용도인 항공사 에이전트의 정기 결제를 사용자가 취소하면 마케팅 메시지 전송을 중지해야 합니다. 하지만 사용자가 특정 항공편의 업데이트를 수신하는 데 명시적으로 동의한 경우 항공편 업데이트를 전송할 수 있습니다.

정기 결제 취소 이유

사용자가 에이전트의 정기 결제를 취소할 때 다음 옵션 중에서 이유를 선택할 수 있습니다.

스팸
가입한 적 없음
메시지가 너무 많이 옴
더 이상 관심이 없음
기타

정기 결제 취소 이유는 파트너가 사용자가 정기 결제를 취소하는 이유를 파악할 수 있도록 애널리틱스 개요 에 표시됩니다.

사용자가 대화의 정기 결제를 재신청함

이 이벤트는 사용자가 프로모션과 같은 불필요한 콘텐츠를 포함하여 에이전트의 메시지를 다시 수신하기를 원함을 나타냅니다. 사용자는 Google 메시지에서 이전에 정기 결제를 취소한 대화의 정기 결제를 재신청하여 이 이벤트를 트리거할 수 있습니다.

다음은 JSON 페이로드의 예입니다.

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

정기 결제 재신청 작동 방식

채팅 메뉴와 채팅 내 링크에서 모두 사용할 수 있는 정기 결제 옵션을 사용하면 사용자가 정기 결제를 취소한 대화의 정기 결제를 재신청할 수 있습니다.

정기 결제 를 선택하면 두 가지 작업이 동시에 트리거됩니다. Google 메시지는 국가별 키워드 (예: 'START')를 에이전트로 전송하고 RBM 플랫폼은 SUBSCRIBE 이벤트를 웹훅으로 전송합니다. 구체적인 키워드는 사용자의 전화번호에 있는 두 글자로 된 국가 코드로 결정됩니다. 다음 표에는 지원되는 각 국가의 키워드가 나와 있습니다.

국가 (국가 코드)	정기 결제 키워드
미국 (US), 인도 (IN), 영국 (GB), 독일 (DE), 네덜란드 (NL)	START
스페인 (ES), 멕시코 (MX)	ALTA
프랑스 (FR)	Démarrer
브라질 (BR)	começar

비즈니스 규칙

이 대화를 관리하는 RBM 파트너는 정기 결제 재신청 요청을 준수해야 합니다.
정기 결제 재신청은 프로모션과 같은 불필요한 콘텐츠를 포함한 모든 메시지 유형에 적용됩니다.
사용자가 정기 결제를 취소한 후 비즈니스에 메시지를 보내면 정기 결제 재신청 요청으로 간주될 수 있습니다.
사용자가 메시지 채널 외부에서 정기 결제를 재신청하는 경우 (예: 웹사이트) RBM 파트너는 상태를 업데이트하고 그에 따라 메시지 전송을 재개해야 합니다.

플랫폼 이벤트

RBM 플랫폼은 플랫폼 이벤트를 전송하여 에이전트의 출시 상태 또는 메시지 만료 변경사항을 에이전트에 알립니다.

에이전트 출시 상태가 변경됨

RBM 플랫폼은 에이전트의 출시 상태가 변경될 때마다 AgentLaunchEvent를 전송합니다. 예를 들어 에이전트의 상태가 PENDING에서 LAUNCHED로 변경되는 경우입니다. 이 이벤트는 Pub/Sub 메시지로 전송됩니다. 이 이벤트를 다른 이벤트와 구분하려면 message.attributes.type 경로에서 agent_launch_event 값을 확인하세요.

웹훅 구성

파트너 수준 또는 에이전트 수준 웹훅을 사용하여 이러한 알림을 수신할 수 있습니다.

기본 요건

RBM 메시징을 위한 웹훅을 구성합니다 (사용자 메시지 및 사용자 이벤트를 수신하기 위한 요구사항).
사용자 이벤트와 에이전트 출시 상태 이벤트 를 구분하려면 message.attributes.type 경로에서 agent_launch_event 값을 확인하세요.

이벤트 페이로드 구조

AgentLaunchEvent는 Pub/Sub 메시지로 전송됩니다. 예를 들면 다음과 같습니다.

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

이벤트 페이로드의 AgentLaunchEvent.LaunchState 필드는 에이전트의 새로운 출시 상태를 나타냅니다. 가능한 값은 다음과 같습니다.

값	에이전트 출시 상태	세부정보
`PENDING`	대기 중	요청이 검토를 위해 운송업체로 전송되었습니다.
`LAUNCHED`	출시됨	특정 이동통신사에서 메시지가 허용됩니다.
`REJECTED`	특정 이동통신사에서 거부됨	거부 이유는 댓글에 지정되어 있습니다.
`SUSPENDED`	특정 이동통신사에서 정지됨	정지 이유는 댓글에 지정되어 있습니다.
`UNLAUNCHED`	출시되지 않음	모든 이동통신사에서 출시되지 않은 에이전트는 수정할 수 있습니다.

데이터 필드에는 출시 상태 세부정보가 포함된 Base64로 인코딩된 JSON 객체가 포함됩니다. 다음은 디코딩된 JSON의 예입니다.

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

이동통신사에서 시작한 출시 상태 변경

이러한 전환은 일반적으로 검토 및 시행 절차 중에 이동통신사에서 처리하는 허용된 전환입니다.

이전 출시 상태	새 출시 상태	트리거 작업
`PENDING`	`LAUNCHED`	출시 요청을 승인합니다.
`PENDING`	`REJECTED`	출시 요청을 거부합니다.
`LAUNCHED`	`SUSPENDED`	시행/관리상의 이유로 정지합니다.
`SUSPENDED`	`LAUNCHED`	에이전트를 활성 상태로 복원합니다.
`SUSPENDED`	`UNLAUNCHED`	에이전트를 종료합니다.

파트너에서 시작한 출시 상태 변경

이러한 전환은 일반적으로 파트너에서 처리하는 허용된 전환입니다.

이전 출시 상태	새 출시 상태	트리거 작업
`UNSPECIFIED`	`PENDING`	제출하여 검토받기
`UNLAUNCHED`	`PENDING`	제출하여 검토받기
`REJECTED`	`PENDING`	다시 제출하여 검토받기

메시지가 만료됨, 취소 성공

이 이벤트는 메시지의 TTL (Time to Live)이 만료되었으며 메시지가 취소되었음을 나타냅니다. 이는 대체 메시지 전략을 위한 좋은 트리거입니다.

전체 형식 지정 및 값 옵션은 ServerEvent 참조를 참고하세요.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

메시지가 만료됨, 취소 실패

이 이벤트는 메시지의 TTL이 만료되었지만 취소되지 않았음을 나타냅니다.

전체 형식 지정 및 값 옵션은 ServerEvent 참조를 참고하세요.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

메시지 전송은 보장되지 않습니다.

메시지가 전송되면 웹훅에서 DELIVERED 이벤트를 수신합니다.
메시지가 전송되지 않은 경우 취소 API를 사용하여 취소 요청을 전송합니다.

OTP 또는 사기 알림과 같이 시간에 민감한 메시지는 사용자에게 중복 메시지가 전송되더라도 SMS와 같은 대체 채널을 통해 전송하는 것이 좋습니다.

일정 보내기

기능 확인

이벤트 수신 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

사용자 이벤트

사용자가 에이전트 메시지를 수신함

사용자가 에이전트 메시지를 읽음

사용자가 입력을 시작함

사용자가 추천 작업을 탭함

사용자가 대화의 정기 결제를 취소함

정기 결제 취소 작동 방식

비즈니스 규칙

예

정기 결제 취소 이유

사용자가 대화의 정기 결제를 재신청함

정기 결제 재신청 작동 방식

비즈니스 규칙

플랫폼 이벤트

에이전트 출시 상태가 변경됨

웹훅 구성

기본 요건

이벤트 페이로드 구조

이동통신사에서 시작한 출시 상태 변경

파트너에서 시작한 출시 상태 변경

메시지가 만료됨, 취소 성공

메시지가 만료됨, 취소 실패

이벤트 수신