Création d'une marque RCS et d'un agent à l'aide de l'API du gestionnaire de canaux

Pour utiliser l'offre RCS de Vonage, une marque doit enregistrer certaines métadonnées au niveau de la marque, puis créer un « Agent » qui représente la marque dans RCS, le faire Verify, puis l'utiliser dans la Messages API lors de l'envoi de messages RCS. L'API Channel Manager fournit des points de terminaison permettant de gérer ces entités (marque, agent) par programmation.

Ce guide vous accompagne :

• Quelles sont les conditions préalables à remplir ?
• Les points finaux de la gestion de la marque : ce qu'ils font, quelles sont les données requises.
• Les points d'extrémité de la gestion des agents : ce qu'ils font, quelles sont les données requises.
• Le flux de travail complet de l'accueil : étapes, transitions d'état.

Conditions préalables

Avant de commencer à utiliser les points d'extrémité de l'API, assurez-vous de ce qui suit :

• Vous avez un compte API Vonage.
• Vous êtes autorisé à appeler les API de gestion de la marque et de gestion des agents.
• Vous avez rassemblé toutes les métadonnées requises concernant la marque et l'agent. Les métadonnées relatives à la marque comprennent le nom d'affichage, les coordonnées légales de l'organisation, le pays d'enregistrement, le site web de l'entreprise et son adresse. Les métadonnées relatives à l'agent comprennent le logo, l'image de bannière, la politique de confidentialité, les conditions générales d'utilisation et les coordonnées.
• Vous comprenez les exigences en matière de vérification dans votre territoire cible (par exemple aux États-Unis).

Composants clés de l'API

Il existe deux entités principales :

• Marque : représente votre organisation (entreprise, identité de la marque).
• Agent : incarne l'identité de la marque lors de la diffusion de messages (nom, logo, couleur, etc.).

Points finaux de la gestion de la marque

Ces points de terminaison permettent de répertorier, créer, mettre à jour ou supprimer l'entité « Marque ». La création d'une marque nécessite un nom d'affichage et les informations relatives à l'entité juridique, notamment la dénomination sociale et la forme juridique, le type d'entité, le pays d'enregistrement, le site web de l'entreprise et l'adresse sociale. Un numéro d'identification fiscale fédéral est également requis pour les entités enregistrées aux États-Unis.

Points finaux de gestion des agents

Ces points d'extrémité sont utilisés pour créer des agents sous une marque. Un agent est ce qui est nécessaire pour envoyer le RCS en tant que marque.

Mise à jour des agents : PUT ou PATCH ?

Les deux PUT et PATCH peuvent mettre à jour un agent, mais leur comportement diffère :

• PUT Il s'agit d'un remplacement complet. Vous devez remplir tous les champs — basic_info, visual_design, application_settings, representative, carrier_requirementset carriers. Tout champ non renseigné est effacé.
• PATCH remplace intégralement chaque champ de niveau supérieur que vous fournissez. Il n'y a pas de fusion en profondeur. Par exemple, si vous envoyez visual_design, l'ensemble de la visual_design l'objet est remplacé — incluez tous les sous-champs que vous souhaitez conserver, et pas seulement ceux que vous modifiez.

Mise en ligne de fichiers multimédias

L'agent visual_design champs logo_image et banner_image Acceptez les URL accessibles au public. Si vos images sont déjà hébergées sur un CDN ou un serveur public, vous pouvez les référencer directement à l'aide de ces URL.

Si vous préférez héberger les fichiers via Vonage, utilisez le point de terminaison de téléchargement de fichiers multimédias :

POST https://api.nexmo.com/v1/channel-manager/rcs/media?type={logo|banner}
Content-Type: multipart/form-data

file: <binary file>

La réponse renvoie l'URL à utiliser dans visual_design:

{ "public_url": "https://..." }

Utilisez l'URL renvoyée comme valeur pour visual_design.logo_image ou visual_design.banner_image dans votre demande de création ou de mise à jour d'agent.

Notes :

• Les type Le paramètre de requête est obligatoire : logo ou banner.
• Formats pris en charge : PNG, JPEG.
• Limites de taille : logo ~50 Ko, bannière ~200 Ko. Les fichiers dépassant ces limites sont rejetés. 413 Payload Too Large.
• Ce point de terminaison est accessible à l'adresse suivante : /v1/ et est commun aux flux de travail des agents v1 et v2.

Processus d'intégration

Il existe deux approches courantes en matière d'intégration, selon la quantité d'informations dont vous disposez dès le départ.

Processus 1 : Démarrage rapide — Toutes les informations sont prêtes

Utilisez ce processus lorsque toutes les informations requises (y compris carrier_requirements (version 2 et informations sur le représentant) est disponible dès le départ et vous souhaitez que l'agent soit opérationnel le plus rapidement possible.

1. Créer une marque

Commencez par créer une marque avec le POST /v2/channel-manager/rcs/brands point de terminaison. Indiquez un display_name et un details objet contenant la dénomination sociale et la forme juridique de l'organisation, son type d'entité, son pays d'enregistrement, son site web professionnel et son siège social. Veuillez inclure federal_tax_id pour une entité enregistrée aux États-Unis et stock_symbol lorsque l'entreprise est cotée en bourse. Une fois la marque créée, l'API renvoie un id que vous utilisez comme brand_id au cours des étapes suivantes.

Exemple de corps de requête :

{
  "display_name": "Acme Bank",
  "details": {
    "organization_name": "Acme Corporation",
    "legal_form": "Limited liability company (LLC)",
    "legal_entity_type": "Private",
    "country_of_registration": "DE",
    "business_website_url": "https://www.example.com",
    "address_line1": "One Main Street",
    "city": "Berlin",
    "state_or_province": "Berlin",
    "zip_or_post_code": "10115"
  }
}

2. Créer un agent

Créer un agent en appelant POST /v2/channel-manager/rcs/agents. Remplissez tous les champs dès le départ : basic_info, visual_design, application_settings, representative, carrier_requirementset carriers.

Les basic_info L'objet doit comporter les champs suivants :

Utilisez le format v2 pour carrier_requirements, ce qui nécessite consent_management et engagement_flows. Le format v1 est obsolète.

Vous devez indiquer au moins un transporteur dans le carriers de la gamme.

Exemple de corps de requête :

{
  "basic_info": {
    "display_name": "Acme Bank",
    "sender_id": "acme-bank",
    "brand_id": "0198ecd4-da21-7f8b-91d8-ccfbaec485a7",
    "hosting_region": "EUROPE",
    "agent_purpose": "TRANSACTIONAL",
    "billing_category": "SINGLE_MESSAGE"
  },
  "visual_design": {
    "tagline": "Your trusted banking assistant",
    "brand_color": "#FF5733",
    "logo_image": "https://cdn.example.com/logo.png",
    "banner_image": "https://cdn.example.com/banner.png",
    "phone": [],
    "email": [],
    "website": []
  },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "representative": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com"
  },
  "carrier_requirements": {
    "version": "v2",
    "agent_preview": {
      "agent_access_instructions": "Visit https://example.com/rcs-agent ...",
      "urls": [{ "media_type": "image", "url": "https://cdn.example.com/preview.png" }]
    },
    "consent_management": {
      "user_messaging_consent_methods": { "selection": ["BY_CREATING_ACCOUNT"] },
      "users_opt_in_process": { "selection": ["WEBSITE_URL"], "links": ["https://www.example.com/subscribe"] },
      "first_opt_in_message": "Welcome! You have opted in to receive updates from Acme Bank.",
      "users_opt_out_methods": { "selection": ["BY_STOP_OR_UNSUBSCRIBE_MESSAGE"] },
      "opt_out_processing_time": { "selection": "WITHIN_5_MINUTES" },
      "opt_out_confirmation_message": { "selection": "SUCCESSFULLY_UNSUBSCRIBED" }
    },
    "engagement_flows": {
      "agent_description": "Acme Bank RCS agent for transactional alerts.",
      "reasons_messages_sent": { "selection": ["ORDER_CONFIRMATION", "PAYMENT_REMINDERS"] },
      "monthly_user_message_count": "THREE_FIVE_MESSAGES",
      "rcs_user_interaction_types": { "selection": ["SIMPLE_REPLIES"] }
    }
  },
  "carriers": ["orange-spain", "vodafone-france"]
}

L'API renvoie une agent_id et un état initial de DRAFT. L'agent passe à CREATED dans un délai d'environ 3 à 5 minutes, après quoi il est possible d'ajouter des appareils de test.

3. Ajouter des numéros de test

Ajouter des numéros de test à l'aide de POST /v2/channel-manager/rcs/agents/:agent_id/test-devices. Ces Numbers vous permettent de tester l'expérience des agents avant la mise en service.

{
  "phone": "+14155552671"
}

La réponse renvoie un AgentTester avec l'objet id, phoneet status. Pour les intégrations d'opérateurs entièrement automatisées, l'appareil est généralement prêt en 2 à 3 minutes. Les opérateurs nécessitant un traitement manuel peuvent prendre plus de temps.

Pour vérifier à tout moment l'état de préparation de tous les appareils de test enregistrés, utilisez :

GET /v2/channel-manager/rcs/agents/:agent_id/test-devices

Retours 403 si l'appareil ne prend pas en charge le RCS, ou 503 si l'agent n'est pas encore configuré.

4. Envoyer des messages d'essai

Envoyez des messages de test depuis l'interface utilisateur de RCS Agent Builder afin de vérifier le bon fonctionnement de l'agent sur vos appareils de test. Cette fonctionnalité n'est actuellement pas disponible via l'API.

5. Soumettre l'agent pour le lancement

Soumettez l'agent pour son lancement à l'aide de POST /v2/channel-manager/rcs/agents/:agent_id/launch.

• Retours 202 Accepted lorsque la soumission est acceptée.
• Retours 422 si l'agent n'est pas prêt à être lancé.
• L'agent passe à PENDING une fois la demande acceptée, les transporteurs entament la procédure d'approbation.
• LAUNCHED Le statut est accordé par transporteur, sous réserve de l'accord de chacun d'entre eux. L'agent peut être LAUNCHED sur certains opérateurs, tout en continuant à PENDING sur les autres.

Une fois approuvé, l'agent n'est pas immédiatement disponible en production. Un examen interne par l'équipe opérationnelle de Vonage est nécessaire pour finaliser le lancement. Ce processus prend généralement entre 4 et 8 semaines, après quoi vous pouvez commencer à utiliser l'agent comme expéditeur dans la Messages API.

6. Ajoutez d'autres opérateurs si nécessaire

Vous pouvez étendre la couverture de l'opérateur à tout moment après la création de l'agent :

POST /v2/channel-manager/rcs/agents/:agent_id/carriers

{
  "carriers": ["dt-germany", "tmobile-us"]
}

Retours 202 Accepted. Retours 409 si un transporteur a déjà été ajouté à l'agent.

Processus 2 : itératif — Tester d'abord la conception visuelle

Utilisez ce workflow lorsque vous souhaitez peaufiner la conception visuelle de l'agent avant de vous engager à respecter l'ensemble des exigences de l'opérateur. Créez l'agent avec un minimum de paramètres, testez la conception sur un appareil réel, effectuez les modifications nécessaires, puis complétez les champs restants avant de valider le lancement.

1. Créer ou mettre à jour la marque en précisant les détails

Suivez l'étape 1 du workflow 1. La marque doit disposer de la details Ce champ doit être renseigné avant que l'agent puisse être lancé.

2. Créer un agent avec un minimum de paramètres

Créez l'agent avec uniquement basic_info, visual_design, application_settingset carriers. Les carrier_requirements et representative Les champs sont facultatifs lors de la création et peuvent être ajoutés ultérieurement.

{
  "basic_info": {
    "display_name": "Acme Bank",
    "sender_id": "acme-bank",
    "brand_id": "0198ecd4-da21-7f8b-91d8-ccfbaec485a7",
    "hosting_region": "EUROPE",
    "agent_purpose": "TRANSACTIONAL",
    "billing_category": "SINGLE_MESSAGE"
  },
  "visual_design": {
    "tagline": "Your trusted banking assistant",
    "brand_color": "#FF5733",
    "phone": [],
    "email": [],
    "website": []
  },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "carriers": ["orange-spain"]
}

L'agent renvoie un agent_id avec l'État DRAFT, pour passer à CREATED dans environ 3 à 5 minutes.

3. Ajouter un appareil de test

POST /v2/channel-manager/rcs/agents/:agent_id/test-devices

{
  "phone": "+34613994828"
}

4. Envoyer un message test

Envoyez un message test via l'interface utilisateur de RCS Agent Builder et observez comment la conception visuelle de l'agent s'affiche sur l'appareil réel.

5. Mettre à jour la conception graphique si nécessaire

Si des modifications s'avèrent nécessaires, effectuez une mise à jour partielle de l'agent :

PATCH /v2/channel-manager/rcs/agents/:agent_id

{
  "visual_design": {
    "tagline": "Updated tagline",
    "brand_color": "#0033CC",
    "phone": [],
    "email": [],
    "website": []
  }
}

Pour les intégrations de transporteurs entièrement automatisées, les modifications sont généralement effectives en 2 à 3 minutes. Pour les transporteurs nécessitant un traitement manuel, cela peut prendre plus de temps.

Répétez les étapes 4 à 5 jusqu’à ce que le motif soit finalisé.

6. Remplissez tous les champs et préparez-vous au lancement

Répétez les étapes 4 et 5 jusqu’à ce que le motif soit finalisé.

6. Remplissez tous les champs et préparez-vous au lancement

Une fois la conception finalisée, utilisez PUT pour remplir tous les champs restants :

{
  "basic_info": { "..." : "..." },
  "visual_design": { "..." : "..." },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "representative": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com"
  },
  "carrier_requirements": {
    "version": "v2",
    "agent_preview": { "..." : "..." },
    "consent_management": { "..." : "..." },
    "engagement_flows": { "..." : "..." }
  },
  "carriers": ["orange-spain", "vodafone-france"]
}

7. Soumettre l'agent pour le lancement

POST /v2/channel-manager/rcs/agents/:agent_id/launch

Pour plus de détails sur le comportement au démarrage et les transitions d'état, reportez-vous à l'étape 5 du workflow 1.

8. Ajoutez d'autres opérateurs si nécessaire

POST /v2/channel-manager/rcs/agents/:agent_id/carriers

{
  "carriers": ["dt-germany"]
}

Maintenance continue

Si certaines métadonnées doivent être mises à jour (logo, description), vérifiez quels champs sont modifiables après la vérification ou contactez votre Account Manager. Certains peuvent être verrouillés.

Statut des agents

Pour en savoir plus

Guide de l'agent RCS
Référence API du gestionnaire de canaux