ניהול נציגים באמצעות RBM Operations API

תהליך העבודה העיקרי של 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"
        }
      }
    }
  ]
}

אפשר לאחזר תוצאות בכל פעם מדף אחד. פרטים נוספים זמינים במאמר בנושא הפניית API.

קבלת פרטי האימות של הנציג

הספק יכול לקבל את הסטטוס של אימות המותג של הסוכן. פרטים נוספים זמינים במאמר 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"
      }
    }
  }
}

הסתרה או ביטול הסתרה של סוכנים

כדי לשמור על סביבת עבודה נקייה ומאורגנת, אפשר להסתיר סוכנים שכבר לא נמצאים בשימוש ברשת. הסתרת סוכן מסירה אותו מתוצאות ברירת המחדל של גילוי ה-API.

ההסתרה היא שינוי של הרשאות הגישה בלבד. השינוי משפיע רק על התצוגה של הספק הספציפי שלכם, ולא משפיע על הסטטוס של הנציג אצל השותף או אצל ספקים אחרים. אפשר לבטל את ההסתרה של סוכן בכל שלב כדי להחזיר את החשיפה שלו ולהמשיך לנהל אותו.

כדי לוודא שסוכנים פעילים לא יוסרו בטעות מהתצוגה, חלים הכללים הבאים:

  • דרישות: אפשר להסתיר רק סוכנים שנמצאים במצב לא פעיל ברשת שלכם: מושעה או נדחה.
  • הגבלות: אי אפשר להסתיר סוכן אם סטטוס ההפעלה שלו ברשת הוא הופעל או בהמתנה. אם תנסו להסתיר סוכן כזה, הבקשה תידחה עם שגיאת FAILED_PRECONDITION.

עדכון סטטוס ההסתרה

כדי להסתיר או לבטל הסתרה של הפעלת סוכן אצל הספק, משתמשים ב-method ‏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 לעסקים.