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

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

تم أخذ مقتطفات التعليمات البرمجية في هذه الصفحة من عيّنات Java و عيّنات Node.js.

إنشاء الوكلاء وتعريفهم

إنشاء وكيل

لإنشاء وكيل RBM، عليك تحديد معلوماته الأساسية.

لمزيد من التفاصيل، يُرجى الاطّلاع على brands.agents.create.

cURL

curl -v -X POST "https://businesscommunications.googleapis.com/v1/$BRAND_ID/agents" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json rbm-developer-service-account-credentials.json businesscommunications`" \
  -d "{
    'displayName': 'My test agent',
    'rcsBusinessMessagingAgent': {
      'description': 'My agent description',
      'logoUri': 'https://agent-logos.storage.googleapis.com/_/kt90w53vzw2QSxK6PG1uCeJf',
      'heroUri': 'https://agent-logos.storage.googleapis.com/_/kt90vzob74GQcfeHoEQbVRTP',
      'phoneNumbers': [
        {
            'phoneNumber': {
                'number': '+44800088088'
            },
            'label': 'My number'
        }
      ],
      'emails': [
        {
            'address': 'support@demo.test',
            'label': 'My email'
        }
      ],
      'websites': [
        {
            'uri': 'https://a.demo.test/',
            'label': 'My site'
        }
      ],
      'privacy': {
        'uri': 'https://a.demo.test/privacy',
        'label': 'My privacy policy'
      },
      'termsConditions': {
        'uri': 'https://a.demo.test/terms',
        'label': 'My terms'
      },
      'color': '#FFFFFF',
      'billingConfig': {
        'billingCategory': 'CONVERSATIONAL'
      },
      'agentUseCase': 'TRANSACTIONAL',
      'hostingRegion': 'EUROPE'
    }
  }"
هذا الرمز هو مقتطف من عيّنة RBM Management API.

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: '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.

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

التحقّق والإطلاق

إرسال معلومات التحقّق

يجب التحقّق من العلامة التجارية لإطلاق الوكيل. يجب إرسال معلومات التحقّق قبل تقديم طلب الإطلاق. يُرجى العِلم أنّه ليس عليك انتظار الموافقة على العلامة التجارية قبل تقديم طلب الإطلاق، إذ تتم الموافقة على العلامة التجارية كجزء من عملية الموافقة على الإطلاق. بالنسبة إلى بعض مشغّلي شبكات الجوّال، يجب أيضًا تقديم رمز تحقّق صالح صادر عن هيئة التحقّق.

لمزيد من التفاصيل، يُرجى الاطّلاع على brands.agents.requestVerification.

cURL

curl -v "https://businesscommunications.googleapis.com/v1/brands/$BRAND_ID/agents/$AGENT_ID:requestVerification" \
-H "Content-Type: application/json" \
-H "x-http-method-override: POST" \
-H "User-Agent: curl/business-messaging" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
  'agentVerificationContact': {
     ...
   },
   'agentVerificationToken':
     {'tokenBase64Encoded': '$TOKEN'}
}"

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/"
  },
  "agentVerificationTokens": [
    {
      "verificationAuthorityDisplayName": "Example Verification Authority",
      "expirationTime": "2027-06-16T13:45:14Z",
      "status": "ACTIVE",
      "countryCode": "US",
      "tokenBase64Encoded": "...",
      "certificateChainUri": "https://rbm.goog/certificates?v=5&kid=6CAE185529AABAC216565E99A8DE22504B086209"
    }
  ]
}

البحث عن معلومات التحقّق الخاصة بوكيل

يمكنك استرداد حالة التحقّق من العلامة التجارية لوكيل. لمزيد من التفاصيل، يُرجى الاطّلاع على 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"
  },
  "agentVerificationTokens": [
    {
      "verificationAuthorityDisplayName": "Example Verification Authority",
      "expirationTime": "2027-06-16T13:45:14Z",
      "status": "ACTIVE",
      "countryCode": "US",
      "tokenBase64Encoded": "...",
      "certificateChainUri": "https://rbm.goog/certificates?v=5&kid=6CAE185529AABAC216565E99A8DE22504B086209"
    }
  ]
}

تعديل رموز التحقّق المميّزة وحذفها

إذا كان لديك وكيل تم إطلاقه من قبل، يمكنك تعديله باستخدام رمز تحقّق مميّز. لإضافة رمز أو تعديله، استخدِم طريقة updateVerification (باستخدام طلب PATCH) وحدِّد قناع التعديل agent_verification_tokens.

cURL

curl -v -X PATCH "https://businesscommunications.googleapis.com/v1/brands/$BRAND_ID/agents/$AGENT_ID/verification?updateMask=agent_verification_tokens" \
-H "Content-Type: application/json" \
-H "x-http-method-override: PATCH" \
-H "User-Agent: curl/business-messaging" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
   'agentVerificationTokens': [
     {'tokenBase64Encoded': '$TOKEN'}
   ]
}"

إذا تم إطلاق وكيلك في بلدان متعدّدة، قد تحتاج إلى تحديد رموز مميّزة متعدّدة (واحد لكل بلد) صادرة عن هيئات التحقّق المعتمدة في تلك المناطق. لتحديد رمز مميّز إضافي، استخدِم طريقة updateVerification وقدِّم جميع الرموز المميّزة التي تريد ربطها بالوكيل، بما في ذلك الرموز المميّزة المرتبطة به حاليًا.

لحذف جميع الرموز المميّزة المرتبطة بوكيل، أرسِل قائمة فارغة في طلب PATCH:

cURL

curl -v -X PATCH "https://businesscommunications.googleapis.com/v1/brands/$BRAND_ID/agents/$AGENT_ID/verification?updateMask=agent_verification_tokens" \
-H "Content-Type: application/json" \
-H "x-http-method-override: PATCH" \
-H "User-Agent: curl/business-messaging" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{}"

تحديد وحلّ مشاكل الأخطاء المتعلقة برمز التحقّق المميّز

عند إدارة رموز التحقّق المميّزة وطلب عمليات الإطلاق، قد تواجه الأخطاء التالية:

  • الرمز المميّز غير متوفّر للإطلاق: إذا طلبت الإطلاق على مشغّل شبكة جوّال يتطلب رمزًا مميّزًا، ولكن لم يكن لدى الوكيل رمز، ستتلقّى 400 error (على سبيل المثال، "Verification token matching agent <...> and carrier country US is missing").
  • بيانات الوكيل غير متطابقة: يجب أن يتطابق معرّف الوكيل واسمه وشعاره وبانره في الملف الشخصي للوكيل تمامًا مع البيانات المضمّنة في الرمز المميّز. إذا حاولت إرفاق رمز مميّز غير متطابق، أو طلبت الإطلاق باستخدام رمز مميّز غير متطابق، ستتلقّى 400 error (على سبيل المثال، "Agent ID mismatch. Request agent ID: <...>, Token agent ID: <...>").

إرسال وكيل للإطلاق

يمكنك إرسال وكيل للإطلاق على مشغّل شبكة جوّال واحد أو أكثر. تتولى Google إدارة بعض عمليات الإطلاق، بينما يتولى مشغّلو شبكات الجوّال إدارة عمليات أخرى مباشرةً. قد تتضمّن عمليات الإطلاق التي يديرها مشغّلو شبكات الجوّال متطلبات إضافية. يُرجى الاطّلاع على عمليات الإطلاق التي تديرها Google مقابل عمليات الإطلاق التي يديرها مشغّلو شبكات الجوّال لمزيد من المعلومات.

قبل أن تتمكّن من إطلاق وكيل للمرة الأولى، عليك إرسال معلومات التحقّق. يسمح ذلك لشركة Google أو مشغّلي شبكات الجوّال أو كليهما بالتحقّق من جهة الاتصال بالعلامة التجارية للتأكّد من أنّك مخوّل بإدارة الوكيل نيابةً عنهم. يُرجى الاطّلاع على التحقّق من العلامة التجارية لمعرفة التفاصيل.

بعد إرسال معلومات التحقّق واستيفاء الشروط الأساسية للإطلاق، يمكنك إرسال طلب إطلاق.

يمكنك إرسال وكيل للإطلاق على مشغّل شبكة جوّال واحد أو أكثر. يجب تقديم استبيان الإطلاق المكتمل كجزء من طلب الإطلاق. لمزيد من التفاصيل، يُرجى الاطّلاع على brands.agents.requestLaunch.

cURL

curl -v -X POST "https://businesscommunications.googleapis.com/v1/$AGENT_ID:requestLaunch" \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/business-messaging" \
  -H "`oauth2l header --json rbm-developer-service-account-credentials.json businesscommunications`" \
  -d "{
    'agentLaunch': {
      'rcsBusinessMessaging': {
        'questionnaire': {
          'contacts': [
            {
              'name': 'John Doe',
              'title': 'Product Owner',
              'email': 'support@demo.test'
            }
          ],
          'optinDescription': 'Thanks for your request.',
          'triggerDescription': 'Promotional messages will be triggered in a timely manner.',
          'interactionsDescription': 'Promotional messages are one way.',
          'optoutDescription': 'Sorry to see you go.',
          'agentAccessInstructions': 'Thanks for your request.',
          'videoUris': [
            'https://d2q4iodazzzt8b.cloudfront.net/MicrosoftTeamsvideo2_1758533835.mp4'
          ],
          'screenshotUris': [
            'https://rm.virbm.com/Il9ChvVEhS1na5mr/ee9bc94b468a40688fb7fc71cb1c069c.png'
          ]
        },
        'launchDetails': {
          '/v1/regions/$CARRIER_ID': {}
        }
      }
    }
  }"
هذا الرمز هو مقتطف من عيّنة RBM Management API.

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

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

جافا

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

إذا رفض مشغّل شبكة الجوّال عملية الإطلاق، يمكن للشريك طلب الإطلاق على مشغّل شبكة الجوّال مرة أخرى (يكون الطلب في حالة 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);
});

جافا

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

تضمين الوكلاء المؤرشفين

تستبعد قائمة جميع الوكلاء تلقائيًا الوكلاء الذين أرشفهم الشريك. لتضمين الوكلاء المؤرشفين في النتائج، اضبط المَعلمة includeArchived على true.

Node.js

تقبل طريقة `listAgents` عنصر إعداد اختياريًا لتضمين الوكلاء المؤرشفين.
const businessCommunicationsApiHelper =
 require('@google/rbm-businesscommunications');

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

businessCommunicationsApiHelper.initBusinessCommunicationsApi(privateKey);

// To list all agents including archived ones, set includeArchived to true
const listOptions = {
  includeArchived: true
};

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

جافا

تتضمّن طريقة `listAllAgents` مَعلمة منطقية للتحكّم في مستوى الظهور.
// To list all agents including archived ones, pass 'true' for the includeArchived parameter
boolean includeArchived = true;
Brand brand = api.getBrand(brandId);
logger.info("Brand: " + brand);

// Call listAllAgents with the brand and the includeArchived flag
ListAgentsResponse response = api.listAllAgents(brand, includeArchived);

List agents = response.getAgents().stream()
 .sorted(Comparator.comparing(Agent::getName)).collect(Collectors.toList());

logger.info(String.format("Found %d agents (including archived)", response.getAgents().size()));
for (Agent agent : agents) {
 logger.info(String.format("Agent [%s]: '%s' (Archived: %s)",
    agent.getName(), agent.getDisplayName(), agent.getIsArchived()));
}

إيقاف وكيل

لإيقاف وكيل من منطقة معيّنة، استخدِم طريقة updateLaunch، حدِّد المنطقة المستهدَفة في خريطة الطلب، واضبط launchState على LAUNCH_STATE_UNLAUNCHED.

curl -X PATCH \
"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)" \
-d "{
  'rcsBusinessMessaging': {
    'launchDetails': {
      '/v1/regions/fi-rcs': {
        'launchState': 'LAUNCH_STATE_UNLAUNCHED'
      },
      '/v1/regions/vodafone-idea-india': {
        'launchState': 'LAUNCH_STATE_UNLAUNCHED'
      }
    }
  }
}"

حذف وكيل

لأسباب أمنية، لم يعُد من الممكن حذف وكلاء RBM. للحصول على المساعدة، يُرجى التواصل مع فريق دعم RCS for Business.

أرشفة الوكلاء أو إخراجهم من الأرشيف

للحفاظ على مساحة عمل نظيفة ومنظَّمة، يمكنك أرشفة الوكلاء الذين لم يعودوا قيد الاستخدام. تؤدي أرشفة وكيل إلى إخفائه من نتائج البحث التلقائية عن واجهة برمجة التطبيقات.

الأرشفة هي تغيير في مستوى الظهور فقط. لا تؤدي إلى حذف الوكيل أو التأثير في حالة إطلاقه الأساسية. يمكنك إخراج وكيل من الأرشيف في أي وقت لاستعادة مستوى ظهوره ومواصلة إدارته.

لضمان عدم إخفاء الوكلاء النشطين عن طريق الخطأ، تنطبق القواعد التالية:

  • الأهلية: يمكنك أرشفة الوكلاء الذين يكونون في حالة غير نشطة فقط: UNLAUNCHED، SUSPENDED، أو REJECTED.
  • القيود: لا يمكنك أرشفة وكيل يكون LAUNCHED أو PENDING على أي مشغّل شبكة جوّال. إذا حاولت أرشفة وكيل من هذا النوع، سيتم رفض الطلب مع ظهور خطأ.

تعديل حالة الأرشيف

لأرشفة وكيل أو إخراجه من الأرشيف، استخدِم طريقة التعديل. يجب تضمين المَعلمة updateMask=is_archived في عنوان URL لتحديد الحقل الذي يتم تعديله. للأرشفة، اضبط القيمة المنطقية isArchived على true، ولإخراج الوكيل من الأرشيف، اضبطها على false.

الطريقة: PATCH /v1/brands/{brandId}/agents/{agentId} أضِف is_archived إلى قناع التعديل.

{
  "isArchived": true
}

إدراج الوكلاء باستخدام الفلاتر

تخفي طريقة list الوكلاء المؤرشفين تلقائيًا. لتضمينهم في نتائجك، استخدِم المَعلمة include_archived.

الطريقة: GET /v1/brands/{brandId}/agents?include_archived=true