إدارة الوكلاء

ينتمي جميع العملاء إلى علامة تجارية (نشاط تجاري أو مؤسسة أو مجموعة). قبل إنشاء وكيل، يجب إنشاء علامة تجارية مالكة. العلامات التجارية هي أدوات تنظيمية بحتة لمساعدتك في تجميع موظفي الدعم المرتبطين معًا.

تم أخذ مقتطفات التعليمات البرمجية في هذه الصفحة من عيّنات Java وعيّنات 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);
});

Java

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

Java

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

Java

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

Java

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

Java

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 مع كائن يحتوي على خريطة للمفاتيح فقط لجميع المناطق التي تريد تفعيل الوكيل فيها. يتيح استخدام خريطة فارغة الحفاظ على اتساق واجهة برمجة التطبيقات الداخلية في العناصر المستخدَمة بين طلبات واجهة برمجة التطبيقات.

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 مع عنصر يحتوي على خريطة للمفاتيح فقط الخاصة بجميع المناطق التي تم تفعيل الوكيل فيها و جميع المناطق التي يريد الوكيل تفعيلها فيها. يتيح استخدام خريطة فارغة الحفاظ على اتساق واجهة برمجة التطبيقات الداخلية في العناصر المستخدَمة بين طلبات البيانات من واجهة برمجة التطبيقات.

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

Java

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، يمكنك إضافة المزيد من مشغّلي شبكات الجوّال المستهدَفين لتوسيع نطاق وصول الوكيل. لمزيد من التفاصيل، يُرجى الاطّلاع على 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);
});

Java

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)" للحصول على المساعدة.