إدارة الوكلاء باستخدام واجهة برمجة تطبيقات عمليات RBM

يتضمّن سير عمل RBM الأساسي لمشغّلي شبكات الجوّال مراجعة المعلومات حول الوكلاء الجدد والموافقة على منحهم الإذن بإطلاق الوكلاء على شبكة مشغّل شبكة الجوّال وإرسال الرسائل إلى المشتركين أو رفض منحهم الإذن.

تم أخذ مقتطفات الرمز البرمجي في هذه الصفحة من عيّنات Javascript وCurl.

عرض قائمة بجميع الوكلاء الذين تم إرسالهم إلى شركة النقل

يمكن لمشغّل شبكة الجوَّال الحصول على قائمة بجميع البرامج التي أرسلها المطوّرون لإطلاقها على شبكة مشغّل شبكة الجوَّال.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

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

cURL

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

تم ضبط العلامة التجارية على - لأنّها غير مطلوبة عند استرداد قائمة بجميع العملاء.

يعرض هذا الرمز قائمة بجميع الوكلاء الذين تم إرسالهم إلى مشغّل شبكة الجوّال لإطلاقهم:

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

يمكن استرداد النتائج صفحة واحدة في كل مرة. يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للحصول على التفاصيل.

الحصول على معلومات التأكّد من الوكيل

يمكن لشركة النقل الحصول على حالة التحقّق من العلامة التجارية للوكيل. لمزيد من التفاصيل، يمكنك الاطّلاع على brands.agents.getVerification.

Node.js

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

cURL

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

ليس بالضرورة أن يعرف المتصل اسم الوكيل بالكامل، بما في ذلك اسم العلامة التجارية. يجب إدخال معرّف الوكيل فقط (قبل @rbm.goog)، مع ضبط اسم العلامة التجارية على -.

يعرض هذا الرمز حالة التحقّق ومعلومات الشريك:

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

الحصول على حالة إطلاق الوكيل والاستبيان

يمكن لمشغّل شبكة الجوّال الحصول على حالة الإطلاق الحالية للوكيل واستبيان الإطلاق الخاص بالمطوّر.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

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

cURL

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

ليس بالضرورة أن يعرف المتصل اسم الوكيل بالكامل، بما في ذلك اسم العلامة التجارية. يجب إدخال معرّف الوكيل فقط (قبل @rbm.goog)، مع ضبط اسم العلامة التجارية على -.

تعرض هذه التعليمات البرمجية معلومات الإطلاق:

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

البحث عن تعريف وكيل

يمكن لمشغّل شبكة الجوّال استرداد معلومات الوكيل باستخدام المعرّف الفريد الخاص به (name).

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

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

cURL

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

ليس بالضرورة أن يعرف المتصل اسم الوكيل بالكامل، بما في ذلك اسم العلامة التجارية. يجب إدخال معرّف الوكيل فقط (قبل @rbm.goog)، مع ضبط اسم العلامة التجارية على -.

يعرض الرمز التالي معلومات الوكيل:

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

تغيير حالة إطلاق الوكيل

يمكن لمشغّل شبكة الجوّال تعديل حالة إطلاق وكيل وإضافة تعليق يوضّح سبب تغيير الحالة.

يجب تغيير الحالة على النحو التالي:

  • LAUNCH_STATE_PENDING إلى LAUNCH_STATE_LAUNCHED أو LAUNCH_STATE_REJECTED
  • من LAUNCH_STATE_LAUNCHED إلى LAUNCH_STATE_SUSPENDED
  • LAUNCH_STATE_SUSPENDED إلى LAUNCH_STATE_LAUNCHED أو LAUNCH_STATE_UNLAUNCHED

ليس بالضرورة أن يعرف المتصل اسم الوكيل بالكامل، بما في ذلك اسم العلامة التجارية. يجب إدخال معرّف الوكيل فقط (قبل @rbm.goog)، مع ضبط اسم العلامة التجارية على -.

Node.js

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

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

businessCommunicationsApiHelper.initBusinessCommunucationsApi(privateKey);

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

cURL

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

يعرض هذا الرمز معلومات الإطلاق المعدَّلة مع تغيير حالة الإطلاق:

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

إخفاء الوكلاء أو إظهارهم

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

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

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

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

تعديل حالة الإخفاء

لإخفاء أو إظهار عملية تشغيل وكيل خاصة بشركة الاتصالات، استخدِم طريقة setAgentLaunchVisibility في مورد التشغيل. لإخفاء الإعداد، اضبط قيمة isHidden المنطقية على true، ولإظهاره، اضبطها على false.

الطريقة: POST /v1/brands/{brandId}/agents/{agentId}/launch:setAgentLaunchVisibility

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

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

عرض قائمة بالوكلاء مع فلاتر

بشكلٍ تلقائي، تستبعد طريقة list الوكلاء الذين أخفاهم مشغّل شبكة الجوّال. لتضمينها في نتائجك، استخدِم المَعلمة includeHidden.

حذف وكيل

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