‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

ניהול סוכנים

נציג של RCS for Business הוא ישות שיחה שמייצגת את המותג שלכם ומקיימת אינטראקציה עם משתמשים. אתם יכולים להשתמש ב-RBM Management API כדי ליצור נציגים, לשלוח אותם לאימות ולהפעיל אותם, ולנהל את מחזור החיים הכולל שלהם. כל סוכן חייב להשתייך למותג בעלות, ולכן צריך ליצור מותג לפני שיוצרים סוכן.

קטעי הקוד בדף הזה נלקחו מדוגמאות 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);
});

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

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

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/"
  },
  "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);
});

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

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 עם אובייקט שמכיל מפה של מפתחות בלבד לכל האזורים שבהם רוצים להפעיל את הסוכן. שימוש במפה ריקה מאפשר לשמור על עקביות פנימית של ה-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': {}
    }
  }
}"

אם סוכן קורא ל-method 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);

אם ההשקה נדחית על ידי הספק, השותף יכול לבקש שוב השקה אצל הספק (הבקשה נמצאת במצב 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 הוצא משימוש ויוסר בקרוב.

הוספת ספקים נוספים להשקה של סוכן

אחרי שמקבלים את פרטי ההשקה הנוכחיים של הסוכן באמצעות קריאת ה-API‏ 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]
    }
  ]
}

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

כברירת מחדל, רשימת כל הסוכנים לא כוללת סוכנים שהשותף העביר לארכיון. כדי לכלול בתוצאות סוכנים שהועברו לארכיון, צריך להגדיר את הפרמטר 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);
});

Java

השיטה 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.

העברה לארכיון או אחזור מהארכיון של סוכנים

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

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

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

זכאות: אפשר להעביר לארכיון רק סוכנים שנמצאים במצב לא פעיל: 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.

Method: ‏ GET /v1/brands/{brandId}/agents?include_archived=true

ניהול המותגים

ניהול בודקים

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

יצירה והגדרה של סוכנים

יצירת סוכן

cURL

Node.js

Java

חיפוש הגדרה של סוכן

Node.js

Java

אימות והפעלה

שליחת פרטי אימות

cURL

Node.js

Java

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

Node.js

Java

עדכון ומחיקה של טוקנים לאימות

cURL

cURL

פתרון בעיות שקשורות לטוקן אימות

שליחת סוכן להשקה

cURL

Node.js

Java

הפעלת סוכן באזור אחד או יותר

חיפוש סטטוס ההפעלה של נציג

Node.js

Java

הוספת ספקים נוספים להשקה של סוכן

Node.js

לאחר ההשקה ותחזוקה

רשימה של כל הסוכנים שנוצרו למותג

Node.js

Java

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

Node.js

Java

ביטול ההשקה של סוכן

מחיקת סוכן

העברה לארכיון או אחזור מהארכיון של סוכנים

עדכון סטטוס הארכיון

הצגת רשימת סוכנים עם מסננים

ניהול סוכנים