RBM Operations API로 에이전트 관리하기

이동통신사의 핵심 RBM 워크플로에는 새 에이전트에 관한 정보를 검토하고 이동통신사의 네트워크에서 실행하고 가입자에게 메시지를 보낼 수 있는 권한을 승인하거나 거부하는 작업이 포함됩니다.

이 페이지의 코드 스니펫은 JavaScript 및 Curl 샘플에서 가져온 것입니다.

이동통신사에 제출된 모든 에이전트 나열

이동통신사는 개발자가 이동통신사의 네트워크에서 실행하기 위해 제출한 모든 에이전트 목록을 가져올 수 있습니다.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

// Retrieve all agents targeting the carrier
businessCommunicationsApiHelper.listAgents('brands/-').then((response) => {
  console.log('Current agents are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

모든 에이전트 목록을 가져올 때는 브랜드가 필요하지 않으므로 브랜드가 -로 설정됩니다.

이 코드는 이동통신사에서 실행하기 위해 제출된 모든 에이전트 목록을 반환합니다.

{
  "agents": [
    {
      "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent",
      "displayName": "My new agent",
      "rcsBusinessMessagingAgent": {
        "description": "This is the agent description that will be displayed in the Agent info tab in Messages",
        "logoUri": "https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf",
        "heroUri": "https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP",
        "phoneNumbers": [
          {
            "phoneNumber": {
              "number": "+12223334444"
            },
            "label": "Call support"
          }
        ],
        "privacy": {
          "uri": "https://policies.google.com/privacy",
          "label": "Our privacy policy"
        },
        "termsConditions": {
          "uri": "https://policies.google.com/terms",
          "label": "Our Terms and Conditions"
        },
        "color": "#0B78D0",
        "billingConfig": {
          "billingCategory": "NON_CONVERSATIONAL"
        },
        "agentUseCase": "MULTI_USE",
        "hostingRegion": "NORTH_AMERICA",
        "partner": {
          "partnerId": "unique-identifier-for-my-partner",
          "displayName": "My partner",
          "company": "Public name of the company for my partner"
        }
      }
    },
    {
      "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent",
      "displayName": "My second agent",
      "rcsBusinessMessagingAgent": {
        "description": "Another agent description",
        "logoUri": "https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf",
        "heroUri": "https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP",
        "phoneNumbers": [
          {
            "phoneNumber": {
              "number": "+12228885768"
            },
            "label": "Call support"
          }
        ],
        "privacy": {
          "uri": "https://policies.google.com/privacy",
          "label": "Our privacy policy"
        },
        "termsConditions": {
          "uri": "https://policies.google.com/terms",
          "label": "Our Terms and Conditions"
        },
        "color": "#0B78D0",
        "billingConfig": {
          "billingCategory": "CONVERSATIONAL"
        },
        "agentUseCase": "PROMOTIONAL",
        "hostingRegion": "NORTH_AMERICA",
        "partner": {
          "partnerId": "unique-identifier-for-my-partner",
          "displayName": "My partner",
          "company": "Public name of the company for my partner"
        }
      }
    }
  ]
}

결과는 한 번에 한 페이지씩 가져올 수 있습니다. 자세한 내용은 API 참조 를 확인하세요.

에이전트 인증 정보 가져오기

이동통신사는 에이전트의 브랜드 인증 상태를 가져올 수 있습니다. 자세한 내용은 다음을 참고하세요. brands.agents.getVerification.

Node.js

  const businessCommunicationsApiHelper =
    require('@google/rbm-businesscommunications');
  const privateKey =
    require('../../resources/businesscommunications-service-account-credentials.json');
  businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);
  businessCommunicationsApiHelper.getAgentVerification(agents[0].name).then((response) => {
  }).catch((err) => {
    console.log(err);
  });

cURL

  curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/verification" \
    -H "Content-Type: application/json" \
    -H "User-Agent: curl/business-messaging" \
    -H "`oauth2l header --json serviceAccount.json businesscommunications`"

호출자는 브랜드 이름을 포함한 전체 에이전트 이름을 반드시 입력할 필요는 없습니다. 에이전트 ID (@rbm.goog 앞)만 필요하며 브랜드 이름은 -로 설정됩니다.

이 코드는 인증 상태와 파트너 정보를 반환합니다.

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent/verification",
  "verificationState": "VERIFICATION_STATE_UNVERIFIED",
  "agentVerificationContact": {
    "partnerName": "John Doe",
    "partnerEmailAddress": "john.doe@gmail.com",
    "brandContactName": "Bob",
    "brandContactEmailAddress": "bob@brand.com",
    "brandWebsiteUrl": "https://www.brand.com"
  }
}

에이전트 출시 상태 및 설문지 가져오기

이동통신사는 에이전트의 현재 출시 상태와 개발자 출시 설문지를 가져올 수 있습니다.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.getAgentLaunch(agents[0].name).then((response) => {
  console.log('Launch details are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/launch" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

이 코드는 출시 정보를 반환합니다.

{
  "name": "brands/8b5c7f80-b025-486b-bc8a-2d0797559711/agents/my-agent-demo/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Mr",
          "email": "johndoe@developer.com"
        }
      ],
      "optinDescription": "Messages are sent to known MSISDNs",
      "triggerDescription": "We respond to any interaction",
      "interactionsDescription": "Simple conversations with a chatbot",
      "optoutDescription": "User sends stop"
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_LAUNCHED",
        "updateTime": "2023-02-20T15:10:36.528669Z"
      }
    }
  }
}

에이전트 정의 조회

이동통신사는 고유 식별자(name)를 사용하여 에이전트의 정보를 가져올 수 있습니다.

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.getAgent(agent[0].name).then((response) => {
  console.log('Agent details are:');
  console.log(JSON.stringify(response.data, null, 2));
}).catch((err) => {
  console.log(err);
});

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`"

이 코드는 에이전트 정보를 반환합니다.

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent",
  "displayName": "My new agent",
  "rcsBusinessMessagingAgent": {
    "description": "This is the agent description that will be displayed in the Agent info tab in Messages",
    "logoUri": "https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf",
    "heroUri": "https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP",
    "phoneNumbers": [
      {
        "phoneNumber": {
          "number": "+12223334444"
        },
        "label": "Call support"
      }
    ],
    "privacy": {
      "uri": "https://policies.google.com/privacy",
      "label": "Our privacy policy"
    },
    "termsConditions": {
      "uri": "https://policies.google.com/terms",
      "label": "Our Terms and Conditions"
    },
    "color": "#0B78D0",
    "billingConfig": {
      "billingCategory": "NON_CONVERSATIONAL"
    },
    "agentUseCase": "MULTI_USE",
    "hostingRegion": "NORTH_AMERICA",
    "partner": {
      "partnerId": "unique-identifier-for-my-partner",
      "displayName": "My partner",
      "company": "Public name of the company for my partner"
    }
  }
}

에이전트 출시 상태 변경

이동통신사는 에이전트의 출시 상태를 업데이트하고 상태 변경 이유를 설명하는 의견을 포함할 수 있습니다.

참고: comment 필드의 요구사항은 작업에 따라 다릅니다.

선택사항: 출시 승인.
필수: 거부, 정지, 출시 취소 요청.

이 의견은 이메일로 개발자에게 전송되며 에이전트 기록이 관리 및 비즈니스 커뮤니케이션 콘솔 모두에 표시되고 AgentLaunchEvent 웹훅 알림에 포함됩니다. 이 전송은 모든 상태 업데이트에 적용됩니다.

상태는 다음과 같이 변경해야 합니다.

LAUNCH_STATE_PENDING에서 LAUNCH_STATE_LAUNCHED 또는 LAUNCH_STATE_REJECTED로
LAUNCH_STATE_LAUNCHED에서 LAUNCH_STATE_SUSPENDED로
LAUNCH_STATE_SUSPENDED에서 LAUNCH_STATE_LAUNCHED 또는 LAUNCH_STATE_UNLAUNCHED로

Node.js

const businessCommunicationsApiHelper =
  require('@google/rbm-businesscommunications');

const privateKey =
  require('../../resources/businesscommunications-service-account-credentials.json');

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper
	.updateAgentLaunchState(agentId, 'LAUNCH_STATE_LAUNCHED').then((response) => {
		console.log('Updated launch details are:');
		console.log(JSON.stringify(response.data, null, 2));
	});

cURL

curl -v -X PATCH "https://businesscommunications.googleapis.com/v1/brands/-/agents/AGENT ID/launch" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json serviceAccount.json businesscommunications`" \
  -d "{
    'rcsBusinessMessaging': {
      'launchDetails': {
        '': {
          'launchState': 'LAUNCH_STATE_LAUNCHED',
        }
      }
    }
  }"

이 코드는 출시 상태가 변경된 업데이트된 출시 정보를 반환합니다.

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Contact manager",
          "email": "john.doe@gmail.com"
        }
      ],
      "optinDescription": "Users accepted our terms of service online.",
      "triggerDescription": "We are reaching pre-registered users",
      "interactionsDescription": "This agent sends notifications and processes suggested replies.",
      "optoutDescription": "Reply stop and we stop.",
      "agentAccessInstructions": "This is a simple agent that reaches registered users.",
      "videoUris": [
        "https://www.google.com/a/video"
      ],
      "screenshotUris": [
        "https://www.google.com/a/screenshot"
      ]
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_REJECTED",
        "comment": "We don't have a billing contract in place with you.", // Note: The field is optional only for launch approval; otherwise, required.
        "updateTime": "2023-04-28T15:22:10.221191Z"
      }
    }
  }
}

에이전트 숨기기 또는 숨기기 해제

작업공간을 깔끔하게 정리하려면 네트워크에서 더 이상 사용되지 않는 에이전트를 숨길 수 있습니다. 에이전트를 숨기면 기본 API 검색 결과에서 에이전트가 삭제됩니다.

숨기기는 공개 상태만 변경합니다. 특정 이동통신사의 뷰에만 영향을 미치며 파트너 또는 다른 이동통신사의 에이전트 상태에는 영향을 미치지 않습니다. 언제든지 에이전트를 숨기기 해제하여 공개 상태를 복원하고 관리를 계속할 수 있습니다.

활성 에이전트가 실수로 뷰에서 삭제되지 않도록 하려면 다음 규칙이 적용됩니다.

자격요건: 네트워크에서 비활성 상태인 에이전트만 숨길 수 있습니다. 정지됨 또는 거부됨.
제한사항: 네트워크에서 출시 상태가 출시됨 또는 대기 중인 에이전트는 숨길 수 없습니다. 이러한 에이전트를 숨기려고 하면 FAILED_PRECONDITION 오류와 함께 요청이 거부됩니다.

숨기기 상태 업데이트

이동통신사의 에이전트 출시를 숨기거나 숨기기 해제하려면 출시 리소스에서 setAgentLaunchVisibility 메서드를 사용합니다. 숨기려면 isHidden 불리언을 true로 설정하고 숨기기 해제하려면 false로 설정합니다.

메서드: POST /v1/brands/{brandId}/agents/{agentId}/launch:setAgentLaunchVisibility

curl -v -X POST "https://businesscommunications.googleapis.com/v1/brands/$BRAND_ID/agents/$AGENT_ID/launch:setAgentLaunchVisibility" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "$(oauth2l header --json serviceAccount.json businesscommunications)" \
  --data '{
    "name": "brands/$BRAND_ID/agents/$AGENT_ID/launch",
    "isHidden": true
  }'

{
  "name": "brands/8b5c7f80-b025-486b-bc8a-2d0797559711/agents/my-agent-demo/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Mr",
          "email": "johndoe@developer.com"
        }
      ],
      "optinDescription": "Messages are sent to known MSISDNs",
      "triggerDescription": "We respond to any interaction",
      "interactionsDescription": "Simple conversations with a chatbot",
      "optoutDescription": "User sends stop"
    },
    "launchDetails": {
      "/v1/regions/thecarrier": {
        "launchState": "LAUNCH_STATE_SUSPENDED",
        "updateTime": "2026-02-20T15:10:36.528669Z",
        "isHidden": true
      }
    }
  }
}

필터를 사용하여 에이전트 나열

기본적으로 list 메서드는 이동통신사에서 숨긴 에이전트를 제외합니다. 결과에 포함하려면 includeHidden 매개변수를 사용합니다.

에이전트 삭제

보안상의 이유로 더 이상 RBM 에이전트를 삭제할 수 없습니다. 지원 이 필요하면 RCS for Business 지원팀에 문의하세요.

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

이동통신사에 제출된 모든 에이전트 나열

Node.js

cURL

에이전트 인증 정보 가져오기

Node.js

cURL

에이전트 출시 상태 및 설문지 가져오기

Node.js

cURL

에이전트 정의 조회

Node.js

cURL

에이전트 출시 상태 변경

Node.js

cURL

에이전트 숨기기 또는 숨기기 해제

숨기기 상태 업데이트

필터를 사용하여 에이전트 나열

에이전트 삭제

RBM Operations API로 에이전트 관리하기