업데이트: 출시 노트에서 새로운 기능 및 제품 업데이트를 확인하세요.

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

이벤트

이벤트는 상담사가 전송하고 수신할 수 있는 알림입니다. 이벤트에는 세 가지 유형이 있습니다.

서버 생성: RBM 플랫폼에서 에이전트로 전송
사용자 생성: 사용자 기기에서 에이전트로 전송됨
상담사 생성: 상담사가 사용자에게 전송

서버 생성 이벤트

RBM 플랫폼은 메시지 만료와 같은 서버 수준 업데이트를 에이전트에게 알리는 이벤트를 전송합니다.

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

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

RBM 플랫폼은 에이전트의 출시 상태가 변경될 때마다 AgentLaunchEvent를 전송합니다. 예를 들어 이동통신사 승인 후 에이전트의 상태가 PENDING에서 LAUNCHED로 변경되면 변경사항을 나타내는 AgentLaunchEvent 이벤트가 수신됩니다. 이러한 이벤트는 모든 RBM 에이전트에 대해 모든 이동통신사 출시 상태 변경에 대해 전송됩니다.

웹훅 구성

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

기본 요건

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`	종료된 에이전트가 실행되었습니다.

메시지가 만료되었습니다. 취소가 완료되었습니다.

메시지가 만료되어 취소되었습니다. 이 이벤트는 대체 메시지 전략의 좋은 트리거가 될 수 있습니다.

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

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

메시지가 만료되었지만 취소되지 않았습니다.

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

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

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

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

사용자 생성 이벤트

사용자 메시지 및 기능 확인과 마찬가지로 에이전트는 사용자 이벤트를 JSON으로 수신합니다.

형식 지정 및 값 옵션은 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"
  }
}

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

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

사용자가 비즈니스로부터 프로모션과 같은 불필요한 메시지를 받고 싶지 않은 경우 Google 메시지에서 RBM 대화를 수신 거부할 수 있습니다.

UNSUBSCRIBE 이벤트는 사용자가 에이전트 및 에이전트가 대표하는 비즈니스와의 대화를 수신 거부했음을 나타냅니다. 다음은 JSON 페이로드의 예입니다.

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

작동 방식

수신 거부 옵션은 항상 채팅 메뉴 내에서 사용할 수 있습니다. 프로모션 및 다용도 에이전트의 경우 이 옵션은 특정 수의 읽지 않은 메시지 (구체적인 규칙은 국가마다 다름)가 표시된 후 채팅에도 직접 표시됩니다.
수신 거부를 선택하면 두 가지 작업이 동시에 트리거됩니다. Google 메시지는 국가별 키워드 (예: '중지')를 상담사에게 전송하고 RBM 플랫폼은 수신 거부 이벤트를 웹훅에 전송합니다.

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

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

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

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

프랑스(FR) 중지

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

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

비즈니스 규칙

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

예

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

수신 거부 이유

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

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

현재 수신 거부 이유는 파트너 또는 이동통신사와 공유되지 않습니다.

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

사용자는 Google 메시지에서 이전에 수신 거부한 대화에 다시 참여할 수 있습니다.

SUBSCRIBE 이벤트는 사용자가 프로모션과 같은 불필요한 콘텐츠를 포함하여 에이전트로부터 메시지를 수신하기를 원함을 나타냅니다. 다음은 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 파트너는 사용자의 상태를 업데이트하고 그에 따라 메시지 전송을 재개해야 합니다.

에이전트 생성 이벤트

상담사는 사람의 상호작용을 시뮬레이션하고 상담사가 사용자의 메시지에 응답하고 있음을 사용자에게 알리기 위해 이벤트를 전송합니다. 사용자의 경우 이벤트가 대화 내에 알림으로 표시됩니다.

형식 지정 및 값 옵션은 phones.agentEvents를 참고하세요.

상담사가 `READ` 이벤트를 전송함

사용자에게 이 이벤트는 특정 메시지의 읽음 확인으로 표시됩니다. RBM 플랫폼에서 메시지를 전송했으며 에이전트가 메시지를 처리하고 있음을 사용자에게 알립니다.

다음 코드는 일치하는 messageId이 있는 메시지에 대해 READ 이벤트를 전송합니다.

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);

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

자바

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");

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

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)

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

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");

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

상담사가 `IS_TYPING` 이벤트를 전송함

사용자에게 이 이벤트는 입력 표시기로 표시되며 에이전트가 메시지를 작성하고 있음을 알립니다. 입력 표시기는 짧은 시간(약 20초)이 지나거나 사용자 기기가 상담사로부터 새 메시지를 수신하면 만료됩니다. 에이전트는 여러 IS_TYPING 이벤트를 전송하여 입력 표시기의 만료 타이머를 재설정할 수 있습니다.

다음 코드는 IS_TYPING 이벤트를 전송합니다.

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!');
});

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

자바

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");

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

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')

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

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");

이 코드는 RBM 샘플 에이전트에서 발췌한 것입니다.

메시지 수신

기능 확인

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

서버 생성 이벤트

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

웹훅 구성

기본 요건

이벤트 페이로드 구조

메시지가 만료되었습니다. 취소가 완료되었습니다.

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

사용자 생성 이벤트

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

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

사용자가 입력 시작

사용자가 문자 메시지를 보냅니다.

사용자가 파일을 전송함

사용자가 추천 답장을 탭함

사용자가 추천 작업을 탭함

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

작동 방식

비즈니스 규칙

예

수신 거부 이유

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

작동 방식

비즈니스 규칙

에이전트 생성 이벤트

상담사가 READ 이벤트를 전송함

cURL

Node.js

자바

Python

C#

상담사가 IS_TYPING 이벤트를 전송함

cURL

Node.js

자바

Python

C#

이벤트

상담사가 `READ` 이벤트를 전송함

상담사가 `IS_TYPING` 이벤트를 전송함