عوامل را مدیریت کنید

همه نمایندگان به یک برند (کسب و کار، سازمان یا گروه) تعلق دارند. قبل از ایجاد یک نماینده، لازم است یک برند مالک ایجاد کنید. برندها صرفاً سازمانی هستند تا به شما در گروه بندی عوامل مرتبط با یکدیگر کمک کنند

قطعه کد موجود در این صفحه از نمونه های جاوا و نمونه های Node.js گرفته شده است.

ایجاد و تعریف عامل

یک عامل ایجاد کنید

برای ایجاد یک عامل RBM، باید اطلاعات اولیه آن را تعریف کنید.

برای جزئیات بیشتر، به brands.agents.create مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

const newAgentDetails = {
  displayName: 'My new agent',
  name: brandId + '/agents/',
  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'
      }
    ],
    // It's recommended to provide at least one contact method (phone or email) because
    // this is required for launch. For any phone, email, or website provided, a corresponding label
    // must also be included.
    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: 'BASIC_MESSAGE' },
    agentUseCase: 'TRANSACTIONAL',
    hostingRegion: 'EUROPE'
  }
};

businessCommunicationsApiHelper.createAgent(brandId, newAgentDetails).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

Brand brand = api.getBrand(brandId);
logger.info("Brand to operate on: " + brand);
String displayName = flags.getOrDefault("agent_name", "Test RBM Agent: " + now.getSecond());
String suffix = flags.getOrDefault("agent_data_suffix", "API");
RcsBusinessMessagingAgent agentData = AgentFactory.createRbmAgent(suffix);
Agent agent = api.createRbmAgent(brand, displayName, agentData);
logger.info("RBM agent has been created: " + agent);

این کد اطلاعات عامل جدید و یک شناسه منحصر به فرد اختصاص داده شده به عامل را برمی گرداند:

{
  name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_dxuewtvy_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: [ [Object] ],
    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: 'BASIC_MESSAGE' },
    agentUseCase: 'MULTI_USE',
    hostingRegion: 'EUROPE'
  }
}

به دنبال تعریف عامل باشید

شما می توانید یک عامل را با تعیین شناسه ( name ) منحصر به فرد آن بازیابی کنید. برای جزئیات بیشتر، به brands.agents.list مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

// Retrieve details of the first agent (if one has already been created)
businessCommunicationsApiHelper.getAgent(agent.name).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

Agent agent = api.getAgent(flags.get("agent_id"));
logger.info("Agent: " + agent);

این کد اطلاعات عامل را برمی گرداند:

{
  name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_dxuewtvy_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: [ [Object] ],
    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: 'BASIC_MESSAGE' },
    agentUseCase: 'MULTI_USE',
    hostingRegion: 'EUROPE'
  }
}

تأیید و راه اندازی

اطلاعات تایید را ارسال کنید

تأیید نام تجاری برای راه‌اندازی نماینده لازم است. قبل از درخواست راه اندازی باید اطلاعات تأیید را ارسال کنید. توجه داشته باشید که لازم نیست قبل از درخواست راه اندازی منتظر تأیید برند باشید. تایید برند به عنوان بخشی از فرآیند تایید راه اندازی اتفاق می افتد.

برای جزئیات بیشتر، به brands.agents.requestVerification مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

let agentVerificationContact = {
  partnerName: 'Alice',
  partnerEmailAddress: 'alice@thepartner.com',
  brandContactName: 'Bob',
  brandContactEmailAddress: 'bob@thebrand.com',
  brandWebsiteUrl: 'https://thebrand.com/'
};

businessCommunicationsApiHelper.verifyAgent(agent.name, agentVerificationContact).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

AgentVerificationContact contact = AgentFactory.createRbmAgentVerification();
AgentVerification verification = api.requestAgentVerification(agent.getName(), contact);
logger.info("Verification requested: " + verification);

این کد اطلاعات تایید را برمی گرداند:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent",
  "verificationState": "VERIFICATION_STATE_UNVERIFIED",
  "agentVerificationContact": {
    "partnerName": "Alice",
    "partnerEmailAddress": "alice@thepartner.com",
    "brandContactName": "Bob",
    "brandContactEmailAddress": "bob@thebrand.com",
    "brandWebsiteUrl": "https://thebrand.com/"
  }
}

اطلاعات تأیید یک نماینده را جستجو کنید

می‌توانید وضعیت تأیید برند یک نماینده را بازیابی کنید. برای جزئیات بیشتر، به 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(agent.name).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

AgentVerification verification = api.getAgentVerification(agent.getName());
logger.info("RBM agent verification: " + verification);

این کد وضعیت تأیید و اطلاعات شریک را برمی‌گرداند:

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

یک نماینده برای راه اندازی ارسال کنید

می توانید یک نماینده را برای راه اندازی در یک یا چند شرکت مخابراتی ارسال کنید. برخی از راه‌اندازی‌ها توسط Google مدیریت می‌شوند و برخی دیگر مستقیماً توسط شرکت‌های مخابراتی مدیریت می‌شوند. پرتاب های تحت مدیریت حامل ممکن است الزامات بیشتری داشته باشند. برای اطلاعات بیشتر، راه‌اندازی‌های تحت مدیریت Google در مقابل راه‌اندازی‌های شرکت مخابراتی را ببینید.

قبل از اینکه بتوانید یک نماینده را برای اولین بار راه اندازی کنید، باید اطلاعات تأیید را ارسال کنید . این به Google، شرکت‌های مخابراتی یا هر دو امکان می‌دهد با مخاطب برند شما تأیید کنند که شما مجاز به مدیریت نماینده از طرف آنها هستید. برای جزئیات بیشتر به تأیید برند مراجعه کنید.

پس از ارسال اطلاعات تأیید و تکمیل پیش نیازهای راه اندازی ، می توانید درخواست راه اندازی ارسال کنید.

می توانید یک نماینده را برای راه اندازی در یک یا چند شرکت مخابراتی ارسال کنید. پرسشنامه تکمیل شده پرتاب باید به عنوان بخشی از درخواست راه اندازی ارائه شود. برای جزئیات بیشتر، به brands.agents.requestLaunch مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);
  
let agentLaunch = {
  questionnaire: {
    contacts: [
      {
        name: 'James Bond',
        title: 'Mr 0 0 7',
        email: 'someone@somewhere.com'
      }
    ],
    optinDescription: 'Users accepted our terms of service online.',
    triggerDescription: 'We are reaching preregistered users',
    interactionsDescription: 'This agent does not do much.',
    optoutDescription: 'Reply stop and we stop.',
    agentAccessInstructions: 'This is a a simple agent that reaches registered users.',
    videoUris: [
      'https://www.google.com/a/video'
    ],
    screenshotUris: [
      'https://www.google.com/a/screenshot'
    ]
  },
  launchDetails: {}
};

businessCommunicationsApiHelper.launchAgent(agent.name, agentLaunch).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

Optional<Questionnaire> q = Optional.of(AgentFactory.createRbmQuestionnaire());
AgentLaunch launch = api.requestRbmAgentLaunch(agent.getName(), regionIds, q);
logger.info("RBM agent updated launch: " + launch);

این کد اطلاعات راه اندازی عامل را برمی گرداند:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "James Bond",
          "title": "Mr O O 7",
          "email": "someone@somewhere.com"
        }
      ],
      "optinDescription": "Users accepted our terms of service online.",
      "triggerDescription": "We are reaching preregistered users",
      "interactionsDescription": "This agent does not do much.",
      "optoutDescription": "Reply stop and we stop.",
      "agentAccessInstructions": "This is a a simple agent that reaches registered users.",
      "videoUris": [
        "https://www.google.com/a/video"
      ],
      "screenshotUris": [
        "https://www.google.com/a/screenshot"
      ]
    },
    "launchDetails": {
      "/v1/regions/some-carrier": {
        "launchState": "LAUNCH_STATE_PENDING",
        "updateTime": "2023-02-24T15:02:13.903554Z"
      }
    },
    "launchRegion": "NORTH_AMERICA"
  }
}

توجه داشته باشید که launchRegion منسوخ شده است و قرار است به زودی حذف شود.

یک عامل را به یک یا چند منطقه راه اندازی کنید

برای راه‌اندازی یک عامل به یک یا چند منطقه، زمانی که عامل قبلاً راه‌اندازی نشده است ، متد requestLaunch را با یک شی که حاوی نقشه‌ای از کلیدهای تنها برای همه مناطقی است که می‌خواهید عامل راه‌اندازی کند، فراخوانی کنید. استفاده از یک نقشه خالی اجازه می دهد تا ثبات API داخلی در اشیاء مورد استفاده بین فراخوانی های API حفظ شود.

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID:requestLaunch" \
-H "Content-Type: application/json" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
  'name': 'brands/BRAND_ID/agents/AGENT_ID/launch',
  'rcsBusinessMessaging': {
    'questionnaire': {
      'contacts': [
        {
          'name': 'Contact person 000',
          'title': 'Contact manager 000',
          'email': 'user@domain.com000'
        }
      ],
      'optinDescription': 'Opt-in description 0',
      'triggerDescription': 'Trigger description 0',
      'optoutDescription': 'Opt-out description 0',
      'agentAccessInstructions': 'Agent instructions 0',
      'videoUris': [
        'https://www.youtube.com/watch?v=NN75im_us4k'
      ],
      'screenshotUris': [
        'https://www.youtube.com/watch?v=NN75im_us4k'
      ]
    },
    'launchDetails': {
      '/v1/regions/fi-rcs': {}
    }
  }
}"

برای راه‌اندازی یک عامل به یک یا چند منطقه (زمانی که عامل قبلاً راه‌اندازی شده است )، متد requestLaunch را با یک شی حاوی نقشه‌ای از کلیدهای همه مناطقی که عامل قبلاً روی آنها راه‌اندازی شده است و همه مناطقی که عامل می‌خواهد به آنها راه‌اندازی کند، فراخوانی کنید. استفاده از یک نقشه خالی اجازه می دهد تا ثبات API داخلی در اشیاء مورد استفاده بین فراخوانی های API حفظ شود.

curl -X POST \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID:requestLaunch" \
-H "Content-Type: application/json" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
  'name': 'brands/BRAND_ID/agents/AGENT_ID/launch',
  'rcsBusinessMessaging': {
    'launchDetails': {
      '/v1/regions/fi-rcs': {},
      '/v1/regions/vodafone-idea-india': {}
    }
  }
}"

اگر عاملی متد requestLaunch را فراخوانی کند اما همه مناطقی را که عامل از قبل به عنوان کلید راه اندازی شده است شامل نشود، خطای 400 - Bad Request پرتاب می شود.

وضعیت راه اندازی یک نماینده را جستجو کنید

شما می توانید وضعیت راه اندازی فعلی یک عامل را بازیابی کنید. برای جزئیات بیشتر، به brands.agents.getLaunch مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.getAgentLaunch(agent.name).then((response) => {

}).catch((err) => {
  console.log(err);
});

جاوا

AgentLaunch launch = api.getAgentLaunch(agent.getName());
logger.info("RBM agent launch: " + launch);

CURL

curl \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID/launch" \
-H "Content-Type: application/json" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)"

اگر راه‌اندازی توسط شرکت مخابراتی رد شود، شریک می‌تواند مجدداً راه‌اندازی را در شرکت مخابراتی درخواست کند (درخواست دارای وضعیت UNSPECIFIED و باطن دارای وضعیت REJECTED است).

این کد اطلاعات راه اندازی و وضعیت راه اندازی را برای هر حامل هدف برمی گرداند:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "James Bond",
          "title": "Mr O O 7",
          "email": "someone@somewhere.com"
        }
      ],
      "optinDescription": "Users accepted our terms of service online.",
      "triggerDescription": "We are reaching preregistered users",
      "interactionsDescription": "This agent does not do much.",
      "optoutDescription": "Reply stop and we stop.",
      "agentAccessInstructions": "This is a a simple agent that reaches registered users.",
      "videoUris": [
        "https://www.google.com/a/video"
      ],
      "screenshotUris": [
        "https://www.google.com/a/screenshot"
      ]
    },
    "launchDetails": {
      "/v1/regions/some-carrier": {
        "launchState": "LAUNCH_STATE_PENDING",
        "updateTime": "2023-02-24T15:02:13.903554Z"
      }
    },
    "launchRegion": "NORTH_AMERICA"
  }
}

توجه داشته باشید که launchRegion منسوخ شده است و قرار است به زودی حذف شود.

حامل های اضافی را به راه اندازی یک نماینده اضافه کنید

پس از اینکه اطلاعات راه‌اندازی فعلی را برای نماینده خود با استفاده از فراخوان brands.agents.getLaunch API بازیابی کردید، می‌توانید حامل‌های هدف بیشتری را برای گسترش دامنه دسترسی نماینده خود اضافه کنید. برای جزئیات بیشتر، به brands.agents.updateLaunch مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);');

// To launch an agent to further carriers, we need to first obtain the existing
// launch information and extend it with the new carrier(s).
businessCommunicationsApiHelper.getAgentLaunch(agent.name).then((response) => {
  let existingLaunch = response.data.rcsBusinessMessaging;

  // Now we add the new carrier to the existing launch
  existingLaunch.launchDetails[config.launchCarrier2] = null;

  // And we submit the launch again
  businessCommunicationsApiHelper.launchAgent(agent.name, existingLaunch).then((response) => {
    console.log('Launch details are:');
    console.log(JSON.stringify(response.data, null, 2));
  }).catch((err) => {
    console.log(err);
  });
}).catch((err) => {
  console.log(err);
});

این کد اطلاعات راه اندازی به روز شده را برمی گرداند:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_7jo0trhw_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "James Bond",
          "title": "Mr O O 7",
          "email": "someone@somewhere.com"
        }
      ],
      "optinDescription": "Users accepted our terms of service online.",
      "triggerDescription": "We are reaching preregistered users",
      "interactionsDescription": "This agent does not do much.",
      "optoutDescription": "Reply stop and we stop.",
      "agentAccessInstructions": "This is a a simple agent that reaches registered users.",
      "videoUris": [
        "https://www.google.com/a/video"
      ],
      "screenshotUris": [
        "https://www.google.com/a/screenshot"
      ]
    },
    "launchDetails": {
      "/v1/regions/some-carrier": {
        "launchState": "LAUNCH_STATE_PENDING",
        "updateTime": "2023-02-24T15:02:13.903554Z"
      },
      "/v1/regions/another-carrier": {
        "launchState": "LAUNCH_STATE_PENDING",
        "updateTime": "2023-02-24T15:04:50.456552Z"
      }
    },
    "launchRegion": "NORTH_AMERICA"
  }
}

پس از راه اندازی و نگهداری

تمام عوامل ایجاد شده برای یک برند را فهرست کنید

توسعه‌دهنده می‌تواند فهرستی از تمام عواملی که برای یک برند ایجاد کرده‌اند را بازیابی کند. برای جزئیات بیشتر، به brands.agents.list مراجعه کنید.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

businessCommunicationsApiHelper.listAgents(brand.name).then((response) => {
  console.log('Current agents are:');
  console.log(response.data);
  datastore.saveJsonData('agents', response.data.agents);
}).catch((err) => {
  console.log(err);
});

جاوا

Brand brand = api.getBrand(brandId);
logger.info("Brand: " + brand);
ListAgentsResponse response = api.listAllAgents(brand);
List<Agent> agents = response.getAgents().stream()
  .sorted(Comparator.comparing(Agent::getName)).collect(Collectors.toList());
logger.info(String.format("Found %d agents", response.getAgents().size()));
for (Agent agent : agents) {
  logger.info(String.format("Agent [%s]: '%s'", agent.getName(), agent.getDisplayName()));
}

این کد لیستی از تمام نمایندگان متعلق به برند را برمی گرداند:

{
  agents: [
    {
      name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent',
      displayName: 'My new agent',
      rcsBusinessMessagingAgent: [Object]
    },
    {
      name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_ciymyd2b_agent',
      displayName: 'My second agent',
      rcsBusinessMessagingAgent: [Object]
    },
    {
      name: 'brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_helof85o_agent',
      displayName: 'My third agent',
      rcsBusinessMessagingAgent: [Object]
    }
  ]
}

یک عامل را راه اندازی کنید

برای باز کردن یک عامل از یک منطقه خاص، متد updateLaunch را فراخوانی کنید، منطقه مورد نظر را در نقشه تماس مشخص کنید و launchState روی LAUNCH_STATE_UNLAUNCHED تنظیم کنید.

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID" \
-H "Content-Type: application/json" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)"\
-d "{
  'rcsBusinessMessaging': {
    'launchDetails': {
      '/v1/regions/fi-rcs': {
        'launchState': 'LAUNCH_STATE_UNLAUNCHED'
      },
      '/v1/regions/vodafone-idea-india': {
        'launchState': 'LAUNCH_STATE_UNLAUNCHED'
      }
    }
  }
}"

یک نماینده را حذف کنید

به دلایل امنیتی، عوامل RBM دیگر قابل حذف نیستند. برای کمک با پشتیبانی RBM تماس بگیرید.