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

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

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

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

ایجاد یک عامل

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

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

نود جی اس

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: 'NON_CONVERSATIONAL' },
    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: 'NON_CONVERSATIONAL' },
    agentUseCase: 'MULTI_USE',
    hostingRegion: 'EUROPE'
  }
}

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

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

نود جی اس

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: 'NON_CONVERSATIONAL' },
    agentUseCase: 'MULTI_USE',
    hostingRegion: 'EUROPE'
  }
}

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

ارسال اطلاعات تأیید

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

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

نود جی اس

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 مراجعه کنید.

نود جی اس

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

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

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

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

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

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

نود جی اس

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 مراجعه کنید.

نود جی اس

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 \
"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 بازیابی کردید، می‌توانید حامل‌های هدف بیشتری را برای گسترش دسترسی نماینده خود اضافه کنید. برای جزئیات بیشتر، به brands.agents.updateLaunch مراجعه کنید.

نود جی اس

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 مراجعه کنید.

نود جی اس

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 تماس بگیرید.