이 페이지는 Cloud Translation API를 통해 번역되었습니다.

이벤트 수신

에이전트는 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",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

사용자가 파일을 전송함

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

사용자가 추천 답장을 탭함

사용자가 추천 답장을 탭하면 상담사는 답장의 포스트백 데이터와 텍스트가 포함된 이벤트를 수신합니다.

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

사용자가 추천 작업을 탭함

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

{
  "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 메시지는 국가별 키워드 (예: '중지')를 상담사에게 전송하고 RBM 플랫폼은 UNSUBSCRIBE 이벤트를 웹훅으로 전송합니다.

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

국가 (국가 코드) 수신 거부 키워드

독일 (DE), 미국 (US), 영국 (GB), 인도 (IN) 중지

스페인 (ES), 멕시코 (MX) BAJA

프랑스(FR) 중지

브라질(BR) parar
사용자가 수신 거부한 후에도 대화는 받은편지함에 남아 있습니다. 단, 스팸으로 신고된 경우에는 스팸 및 차단된 대화 폴더로 이동됩니다.
정책 및 비즈니스 규칙 위반을 식별하기 위해 Google에서는 사용자가 수신 거부한 후 메시지 패턴을 모니터링합니다.

국가 (국가 코드)	수신 거부 키워드
독일 (DE), 미국 (US), 영국 (GB), 인도 (IN)	중지
스페인 (ES), 멕시코 (MX)	BAJA
프랑스(FR)	중지
브라질(BR)	parar

비즈니스 규칙

이 대화를 관리하는 RBM 파트너는 사용자의 수신 거부 요청을 준수해야 합니다.
메시지 대화목록 내에서 수신 거부를 실행할 수 없는 경우 사용자가 구독 환경설정을 관리할 수 있는 웹사이트 또는 앱으로 연결되는 직접 링크가 포함된 확인 메시지를 즉시 전송해야 합니다.
사용자가 수신을 거부한 후에는 불필요한 메시지를 전송할 수 없습니다.
필수 메시지는 계속 허용됩니다. 예를 들면 다음과 같습니다.
- 인증(예: 일회용 비밀번호(OTP))
- 사용자가 요청하고 동의한 특정 서비스에 관한 알림
- 사용자의 수신 거부 요청 확인, 커뮤니케이션 환경설정을 추가로 관리할 수 있는 정보 포함

예

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

수신 거부 이유

사용자가 에이전트의 구독을 해지할 때 다음 옵션 중에서 이유를 선택할 수 있습니다.

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

수신 거부 이유는 파트너가 사용자의 수신 거부 이유를 파악할 수 있도록 분석 개요에 표시됩니다.

사용자가 대화를 다시 구독함

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

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

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

재구독 작동 방식

채팅 메뉴와 채팅 내 링크에서 사용할 수 있는 구독 옵션을 사용하면 사용자가 구독 취소한 대화를 다시 구독할 수 있습니다.
구독을 선택하면 두 가지 작업이 동시에 트리거됩니다. Google 메시지에서 국가별 키워드 (예: '시작')를 에이전트에 전송하고 RBM 플랫폼에서 구독 이벤트를 웹훅에 전송합니다. 특정 키워드는 사용자 전화번호의 두 글자 국가 코드에 따라 결정됩니다. 다음 표에는 지원되는 각 국가의 키워드가 나와 있습니다.

국가 (국가 코드) 구독 키워드

독일 (DE), 미국 (US), 영국 (GB), 인도 (IN) 시작

스페인 (ES), 멕시코 (MX) ALTA

프랑스(FR) Démarrer

브라질(BR) começar

국가 (국가 코드)	구독 키워드
독일 (DE), 미국 (US), 영국 (GB), 인도 (IN)	시작
스페인 (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 필드는 에이전트의 새로운 실행 상태를 나타냅니다. 가능한 값은 다음과 같습니다.

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

데이터 필드에는 출시 상태 세부정보가 포함된 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`	`TERMINATED`	정지된 에이전트가 종료되었습니다.
`TERMINATED`	`LAUNCHED`	종료된 에이전트가 실행되었습니다.

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

이 이벤트는 메시지의 TTL (수명)이 만료되었으며 메시지가 성공적으로 취소되었음을 나타냅니다. 이는 대체 메시지 전략에 적합한 트리거입니다.

전체 형식 지정 및 값 옵션은 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와 같은 대체 채널을 통해 메시지를 전송하는 것이 좋습니다.

일정 보내기

기능 확인

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

사용자 이벤트

사용자가 상담사 메시지를 수신함

사용자가 상담사 메시지를 읽음

사용자가 입력 시작

사용자가 문자 메시지를 보냄

사용자가 파일을 전송함

사용자가 추천 답장을 탭함

사용자가 추천 작업을 탭함

사용자가 대화 수신을 거부함

수신 거부 작동 방식

비즈니스 규칙

예

수신 거부 이유

사용자가 대화를 다시 구독함

재구독 작동 방식

비즈니스 규칙

플랫폼 이벤트

에이전트 실행 상태가 변경됨

웹훅 구성

기본 요건

이벤트 페이로드 구조

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

메시지가 만료되었으며 취소가 실패했습니다.

이벤트 수신