Plateforme WhatsApp Business > API Cloud > Guides

Migrer de l’API On-Premises vers l’API Cloud

Ce document explique comment migrer un numéro de téléphone professionnel de l’API On-Premises vers l’API Cloud.

Notez que la migration d’un numéro de téléphone professionnel d’une API à une autre diffère de sa migration d’un compte WhatsApp Business (WABA) à un autre.

Pour migrer de l’API Cloud vers l’API On-Premises, consultez la page Migrer de l’API Cloud vers l’API On-Premises.

Fonctionnement

La migration implique de générer les métadonnées relatives au numéro de téléphone professionnel, puis d’enregistrer le numéro à utiliser avec l’API Cloud à l’aide de ces données. Dans la mesure où un numéro ne peut être enregistré et utilisé qu’avec une seule API à la fois, ce processus annule l’enregistrement du numéro dans l’API On-Premises.

La migration N’A PAS d’incidence sur les éléments suivants :

le nom à l’écran, le statut de vérification ou l’évaluation de qualité du numéro de téléphone professionnel
les modèles utilisés par le numéro de téléphone professionnel ou leurs statuts
le compte WhatsApp Business détenteur, son statut de compte business officiel ou sa limite en matière de messages

Avant d’effectuer une migration, toutefois, vous devez connaître les éventuelles différences entre les API et prendre les mesures qui s’imposent avant de passer à la procédure de migration décrite dans ce document.

Conditions requises

Application Meta

Vous devez disposer d’une application Business Meta pouvant utiliser les API Cloud et Business Management avec les données clientèle intégrées, et capable de gérer les webhooks de ces API. L’application doit également être associée à votre compte Business Meta vérifié, ou être revendiquée par ce dernier.

Si vous n’avez pas d’application Business Meta, ou si vous n’y avez pas configuré le produit WhatsApp, suivez les étapes de notre guide Premiers pas avec l’API Cloud. Ces étapes permettent de générer tous les éléments dont vous avez besoin pour tester les API Cloud et Business Management.

Contrôle app

Votre application Meta doit passer le Contrôle app et être approuvée (c’est-à-dire, recevoir un accès Avancé) pour les autorisations whatsapp_business_messaging et whatsapp_business_management.

Recommandations

Une fois que vous vous êtes assuré·e que votre application peut gérer toutes les différences entre les API, il est recommandé de commencer par migrer un numéro de téléphone professionnel peu utilisé et de vérifier que toutes les fonctionnalités que vous comptez proposer avec l’API Cloud fonctionnent correctement. Cela fait, vous pourrez migrer d’autres numéros.

Nous vous recommandons également de migrer vos numéros de téléphone lorsque le trafic vers votre API On-Premises est faible.

Différences entre les API

Les fonctionnalités suivantes de l’API On-Premises ne sont pas prises en charge, ou sont traitées différemment par l’API Cloud. Vérifiez que votre application peut gérer ces différences avant de commencer le processus de migration.

Webhooks

Les structures de charge utile des webhooks des API Cloud et Business Management diffèrent de celles de l’API On-Premises. Il est recommandé de créer un point de terminaison webhook permettant de gérer uniquement les API Cloud et Business Management.

Pour appréhender les différences en termes de charge utile et savoir comment configurer les webhooks sur votre application à l’aide de l’Espace App, reportez-vous aux documents suivants :

Configuration : Webhooks pour WhatsApp
Charges utiles des webhooks de l’API Cloud : Référence sur les charges utiles des notifications de webhook
Charges utiles des webhooks de l’API Business Management : Configuration des webhooks

Notez qu’après avoir effectué la migration d’un numéro de téléphone professionnel vers l’API Cloud, vous devez utiliser le point de terminaison Compte WhatsApp Business > Subscribed Apps (Applications abonnées) pour abonner votre application Meta aux webhooks du compte WhatsApp Business (WABA) associé au numéro de téléphone professionnel :

Syntaxe de la requête

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

Notez qu’une fois la migration vers l’API Cloud terminée, les webhooks de l’API On-Premises correspondant au numéro de téléphone professionnel ne seront plus diffusés et la livraison des webhooks de l’API Cloud commencera.

Contenu multimédia

Vous ne pouvez pas utiliser les ID des contenus multimédias importés dans l’API On-Premises lors de l’envoi de messages avec l’API Cloud. Vous devez donc réimporter le contenu à l’aide de l’API Cloud pour générer les nouveaux ID, ou utiliser l’URL des contenus si ces derniers sont hébergés sur un serveur public. Consultez Messages multimédias et Modèles de message multimédia.

Notez que pour garantir l’intégrité des messages, certains domaines d’hébergement des contenus multimédias autorisés par l’API On-Premises ne sont pas autorisés par l’API Cloud. Si vous recourez à un service d’hébergement pour votre contenu multimédia, nous vous recommandons de tester les URL de vos contenus dans des messages au format libre et des modèles de message avant de procéder à la migration. Si vous pensez que votre hébergeur a été bloqué par erreur, contactez l’assistance.

Codes d’erreur

Les codes d’erreur des API Cloud et Business Management diffèrent de ceux de l’API On-Premises. Reportez-vous aux documents suivants :

Validation des propriétés

L’API On-Premises peut accepter des propriétés inconnues dans les charges utiles du corps de message, mais l’API Cloud rejettera ces requêtes. Vos requêtes d’envoi de messages ne doivent donc utiliser que des propriétés acceptées.
L’API On-Premises permet d’omettre les index de bouton lors de l’envoi de messages ne contenant qu’un seul bouton, mais l’API Cloud rejettera ces requêtes. Par conséquent, veillez à ce que vos requêtes d’envoi de message incluant des boutons comportent également leurs index et leurs valeurs.
L’API On-Premises accepte les chaînes de texte contenant des espaces de début et de fin (ou uniquement des espaces) pour les propriétés d’objets de bouton et d’action lors de l’envoi de messages interactifs, mais l’API Cloud rejettera ces requêtes.

Messages Appuyer pour parler

L’API On-Premises identifie les messages Appuyer pour parler (Push-To-Talk, PTT) des webhooks lorsque messages.type est défini sur voice, mais l’API Cloud les identifie lorsque messages.audio.voice est configuré sur true.

Packs de stickers

L’API Cloud ne prend pas en charge les packs de stickers.

Temps d’inactivité

L’inactivité commence dès que vous effectuez la dernière étape (enregistrement du numéro à utiliser avec l’API Cloud) et ne doit durer que quelques secondes. Pendant ce laps de temps, les messages que les utilisateur·ices WhatsApp envoient au numéro sont ignorés en silence.

Nous vous recommandons vivement de planifier la migration durant les heures creuses d’utilisation du numéro afin de minimiser l’impact du temps d’inactivité.

Débit

Si le numéro de téléphone professionnel On-Premises possède plusieurs connexions qui exécutent deux partitions ou plus, il passera automatiquement à un débit élevé sur l’API Cloud.

Comptes business officiels

Si vous migrez un numéro de téléphone professionnel ayant un statut compte business officiel (OBA), son statut sera conservé si vous incluez ses métadonnées (générées à l'étape 2) lors de l'enregistrement du numéro (étape 3). Si vous omettez ces données, le numéro perdra son statut OBA.

Assistance relative à la migration

En cas de questions ou si vous avez besoin d’aide lors de la migration, envoyez une demande d’Assistance directe en indiquant les informations suivantes :

Sujet : WABiz : API Cloud
Type de requête : Problèmes de migration de l’API On-Premises vers l’API Cloud

Étape 1 : désactiver la vérification en deux étapes

Si vous connaissez le code PIN du numéro de téléphone professionnel, vous pouvez ignorer cette étape.

Vous aurez besoin de ce code à l’étape 3. Si vous ne le connaissez pas, vous devez d’abord désactiver la vérification en deux étapes pour le numéro de téléphone professionnel. Si le numéro de téléphone professionnel ne vous appartient pas, demandez à son ou à sa propriétaire de procéder à cette désactivation pour vous.

Étape 2 : générer les métadonnées du numéro de téléphone

Utilisez l’API Backup and Restore pour générer les métadonnées relatives à votre numéro de téléphone professionnel.

Syntaxe de la requête

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> accepte n’importe quelle chaîne. Cette valeur permettra d’encoder les métadonnées. Gardez-la précieusement, car vous en aurez besoin à l’étape suivante.

Réponse

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

L’API retourne une chaîne encodée affectée à la propriété data qui décrit votre numéro de téléphone professionnel et ses paramètres. Conservez cette valeur, car vous en aurez besoin à l’étape suivante.

<METADATA> : chaîne encodée décrivant votre numéro de téléphone professionnel et ses paramètres. Conservez cette valeur, car vous en aurez besoin à l’étape suivante.
<API_STATUS> : statut du déploiement de l’API On-Premises.
<API_VERSION> : numéro de version de l’API On-Premises que vous exécutez.

Exemple de requête

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

Exemple de réponse

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

Étape 3 : enregistrer le numéro

Aucun mot de passe à usage unique n’est requis si les métadonnées de sauvegarde à l’étape 2 ci-dessus ont été correctement transmises et sans modifications à l’API Cloud durant l’étape 3 (la présente étape).

Utilisez le point de terminaison Numéro de téléphone WhatsApp Business > Enregistrer de l’API Cloud pour enregistrer le numéro à utiliser avec l’API Cloud.

Ajoutez la valeur des métadonnées du numéro de téléphone professionnel encodées et le mot de passe de l’étape précédente. Bien que vous puissiez enregistrer le numéro sans ces données, les données de profil du numéro de téléphone professionnel seront perdues si elles ne sont pas incluses, ce qui peut avoir une incidence sur le statut du compte WhatsApp Business en tant que compte business officiel.

Syntaxe de la requête

POST /<BUSINESS_PHONE_NUMBER_ID>/register

Corps de la requête

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> : code PIN existant ou que vous souhaitez définir pour le numéro de téléphone professionnel.
<PASSWORD> : mot de passe utilisé pour générer les métadonnées de votre numéro de téléphone professionnel à l’étape précédente.
<METADATA> : chaîne encodée qui décrit votre numéro de téléphone professionnel et ses paramètres, générée à l’étape précédente.

Réponse

{
  "success": <SUCCESS>
}

success est défini sur true si l’enregistrement a abouti, ou sur false en cas d’erreur.

Exemple de requête

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

Exemple de réponse

{
  "success": true
}

Étape 4 : vérifier l’état du service de messagerie (facultatif)

Demandez le champ health_status pour le numéro de téléphone professionnel et vérifiez qu’il peut être utilisé avec la messagerie avec l’API Cloud. Voir État du service de messagerie.

Plateforme WhatsApp Business | API Cloud | API Business Management