Mengelola agen dengan RBM Operations API

Alur kerja RBM inti untuk operator mencakup peninjauan informasi tentang agen baru dan menyetujui atau menolak izin mereka untuk diluncurkan di jaringan operator dan mengirim pesan kepada pelanggan mereka.

Cuplikan kode di halaman ini diambil dari contoh Javascript dan Curl kami.

Mencantumkan semua agen yang dikirimkan ke operator

Operator dapat memperoleh daftar semua agen yang telah dikirimkan developer untuk diluncurkan di jaringan operator.

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`"

Merek ditetapkan ke - karena tidak diperlukan saat mengambil daftar semua agen.

Kode ini menampilkan daftar semua agen yang dikirimkan untuk diluncurkan di operator:

{
  "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": "[phone]"
            },
            "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": "[phone]"
            },
            "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"
        }
      }
    }
  ]
}

Hasil dapat diambil satu halaman dalam satu waktu. Lihat referensi API untuk mengetahui detailnya.

Mendapatkan info verifikasi agen

Operator dapat memperoleh status verifikasi merek agen. Untuk mengetahui detail selengkapnya, lihat 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`"
  

Pemanggil tidak harus memiliki nama agen lengkap, termasuk nama merek. Hanya ID agen (sebelum @rbm.goog) yang diperlukan, dengan nama merek ditetapkan ke -.

Kode ini menampilkan status verifikasi dan info partner:

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

Mendapatkan status peluncuran dan kuesioner agen

Operator dapat memperoleh status peluncuran agen saat ini dan kuesioner peluncuran developer.

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`"

Pemanggil tidak harus memiliki nama agen lengkap, termasuk nama merek. Hanya ID agen (sebelum @rbm.goog) yang diperlukan, dengan nama merek ditetapkan ke -.

Kode ini menampilkan informasi peluncuran:

{
  "name": "brands/8b5c7f80-b025-486b-bc8a-2d0797559711/agents/my-agent-demo/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Mr",
          "email": "[e-mail]"
        }
      ],
      "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"
      }
    }
  }
}

Mencari definisi agen

Operator dapat mengambil informasi agen menggunakan ID uniknya (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`"

Pemanggil tidak harus memiliki nama agen lengkap, termasuk nama merek. Hanya ID agen (sebelum @rbm.goog) yang diperlukan, dengan nama merek ditetapkan ke -.

Kode ini menampilkan informasi agen:

{
  "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": "[phone]"
        },
        "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"
    }
  }
}

Mengubah status peluncuran agen

Operator dapat memperbarui status peluncuran agen dan menyertakan komentar yang menjelaskan alasan perubahan status.

Catatan: Persyaratan untuk kolom comment bervariasi menurut tindakan:

• Opsional: Persetujuan peluncuran.
• Wajib: Penolakan, penangguhan, dan permintaan pembatalan peluncuran.

Jejak audit: Anda dapat secara opsional menyertakan acting_party parameter kueri untuk menentukan alamat email atau ID orang yang melakukan tindakan. Hal ini memastikan bahwa kolom ID Pengguna dalam log histori mengidentifikasi individu dengan benar, bukan menetapkan "Panggilan API" sebagai nilai default.

Komentar ini dikirimkan kepada developer melalui email, terlihat di Histori agen di konsol Administrasi dan RCS for Business, serta disertakan dalam notifikasi AgentLaunchEvent webhook. Pengiriman ini berlaku untuk semua pembaruan status.

Status harus diubah sebagai berikut:

• LAUNCH_STATE_PENDING menjadi LAUNCH_STATE_LAUNCHED atau LAUNCH_STATE_REJECTED
• LAUNCH_STATE_LAUNCHED menjadi LAUNCH_STATE_SUSPENDED
• LAUNCH_STATE_SUSPENDED menjadi LAUNCH_STATE_LAUNCHED atau LAUNCH_STATE_UNLAUNCHED

Pemanggil tidak harus memiliki nama agen lengkap, termasuk nama merek. Hanya ID agen (sebelum @rbm.goog) yang diperlukan, dengan nama merek ditetapkan ke -.

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?acting_party=[e-mail]" \
  -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',
        }
      }
    }
  }"

Kode ini menampilkan informasi peluncuran yang diperbarui dengan status peluncuran yang diubah:

{
  "name": "brands/40bd963f-ff92-425c-b273-8f0892d2d017/agents/my_new_agent_4fpd1psz_agent/launch",
  "rcsBusinessMessaging": {
    "questionnaire": {
      "contacts": [
        {
          "name": "John Doe",
          "title": "Contact manager",
          "email": "[e-mail]"
        }
      ],
      "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"
      }
    }
  }
}

Menyembunyikan atau menampilkan agen

Untuk mempertahankan ruang kerja yang bersih dan teratur, Anda dapat menyembunyikan agen yang tidak lagi digunakan di jaringan Anda. Menyembunyikan agen akan menghapusnya dari hasil penemuan API default.

Penyembunyian hanya mengubah visibilitas. Tindakan ini hanya memengaruhi tampilan untuk operator tertentu dan tidak memengaruhi status agen untuk partner atau operator lainnya. Anda dapat menampilkan agen kapan saja untuk memulihkan visibilitasnya dan melanjutkan pengelolaan.

Catatan: Untuk menyembunyikan agen menggunakan Konsol Administrasi, lihat Menyembunyikan atau menampilkan agen.

Untuk memastikan bahwa agen aktif tidak sengaja dihapus dari tampilan, aturan berikut berlaku:

• Kelayakan: Anda hanya dapat menyembunyikan agen yang berada dalam status tidak aktif di jaringan Anda: Ditangguhkan atau Ditolak.
• Batasan: Anda tidak dapat menyembunyikan agen jika status peluncurannya di jaringan Anda adalah Diluncurkan atau Tertunda. Jika Anda mencoba menyembunyikan agen tersebut, permintaan akan ditolak dengan error FAILED_PRECONDITION.

Memperbarui status penyembunyian

Untuk menyembunyikan atau menampilkan peluncuran agen untuk operator Anda, gunakan metode setAgentLaunchVisibility pada resource peluncuran. Untuk menyembunyikan, tetapkan boolean isHidden ke true, dan untuk menampilkan, tetapkan ke false.

Metode: 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": "[e-mail]"
        }
      ],
      "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
      }
    }
  }
}

Mencantumkan agen dengan filter

Secara default, metode list mengecualikan agen yang disembunyikan oleh operator Anda. Untuk menyertakannya dalam hasil, gunakan parameter includeHidden.

Menghapus agen

Demi alasan keamanan, agen RBM tidak dapat lagi dihapus. Untuk mendapatkan bantuan, hubungi tim dukungan RCS for Business.