Numéros de téléphone

Ce guide explique comment vérifier votre numéro de téléphone et quel doit être son formatage pour l’API Cloud.

Il indique les critères à respecter pour ajouter des numéros de téléphone à votre compte WhatsApp Business (WABA). Pour en savoir plus, consultez la section Numéros de téléphone.

Certains appels d’API vous obligent à connaître l’ID de votre numéro de téléphone. Pour savoir comment obtenir les numéros de téléphone associés à votre compte WhatsApp Business, consultez la section Obtenir tous les numéros de téléphone. La réponse à cet appel d’API inclut les ID de tous les numéros de téléphone connectés à votre compte WhatsApp Business. Enregistrez l’ID du numéro de téléphone que vous voulez utiliser avec les appels /PHONE_NUMBER_ID.

Vérifier les numéros de téléphone

Vous devez vérifier le numéro de téléphone que vous souhaitez utiliser pour envoyer des messages à votre clientèle. Cette vérification s’effectue grâce à un code envoyé par texto ou appel vocal. Le processus de vérification s’effectue via les appels d’API Graph indiqués ci-dessous.

Pour vérifier un numéro de téléphone avec l’API Graph, effectuez une requête POST sur PHONE_NUMBER_ID/request_code. Dans l’appel, insérez la méthode de vérification choisie et la langue.

Paramètres

Exemple

Exemple de requête :

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/request_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'locale=en_US'

Après l’appel d’API, vous recevrez votre code de vérification via la méthode sélectionnée. Pour terminer le processus de vérification, insérez votre code dans une demande POST sur PHONE_NUMBER_ID/verify_code.

Paramètres

Exemple

Exemple de requête :

curl -X POST \
  'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/verify_code' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

Une réponse positive ressemble à ce qui suit :

{
  "success": true
}

Vérification des changements d’identité

Vous pouvez faire en sorte que nous vérifiions l’identité d’un·e client·e avant de lui distribuer votre message. Pour ce faire, vous devez activer le paramètre de vérification des changements d’identité sur votre numéro de téléphone professionnel.

Lorsqu’un·e client·e effectue une action que nous considérons comme un changement d’identité sur WhatsApp, nous générons un nouveau hash de son identité d’utilisateur·ice. Pour récupérer ce hash à chaque message que vous lui envoyez, activez le paramètre de vérification des changements d’identité sur votre numéro de téléphone professionnel. Quand ce paramètre est activé, chaque fois que le client ou la cliente vous envoie un message ou que vous lui envoyez un message sans hash d’identité, nous incluons son hash d’identité dans les webhooks de message entrant ou de statut de distribution. Vous pouvez alors récupérer ce hash et le stocker pour une utilisation ultérieure.

Pour utiliser le hash, vous devez l’inclure dans une requête d’envoi de message. Nous comparons alors le hash inclus dans la requête au hash actuel du client ou de la cliente. S’ils sont identiques, le message est distribué. Dans le cas contraire, cela signifie que le client ou la cliente a modifié son identité depuis le dernier message que vous lui avez envoyé, et nous ne lui délivrons pas le message. En revanche, nous vous envoyons un webhook de statut de message contenant le code d’erreur 137000 qui vous notifie l’échec de l’envoi et de la comparaison.

Lorsque vous recevez un webhook de non-correspondance des hash, partez du principe que le numéro de téléphone du client ou de la cliente n’est plus fiable. Pour rétablir la confiance, vérifiez l’identité du client ou de la cliente par le biais de canaux autres que WhatsApp. Une fois la confiance rétablie, renvoyez le message précédemment non distribué à la nouvelle identité (le cas échéant), sans hash. Ensuite, récupérez le nouveau hash du client ou de la cliente, qui est inclus dans le webhook de statut de distribution du message.

Syntaxe de la requête

Envoyez une requête POST au point de terminaison Numéro de téléphone WhatsApp Business > Paramètres pour activer ou désactiver le paramètre de vérification des changements d’identité.

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/settings

Corps de la requête

{
  "user_identity_change" : {
    "enable_identity_key_check": <ENABLE_IDENTITY_KEY_CHECK>
}

Définissez <ENABLE_IDENTITY_KEY_CHECK> sur true pour activer la vérification d’identité ou sur false pour la désactiver.

Exemple de requête d’activation

curl 'https://graph.facebook.com/v21.0/106850078877666/settings' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "user_identity_change": {
    "enable_identity_key_check": true
  }
}'

Exemple de réponse d’activation

{
  "success": true
}

Exemple d’envoi de message avec vérification

Cet exemple de message sera distribué uniquement si la valeur du hash recipient_identity_key_hash correspond au hash actuel du client ou de la cliente.

curl 'https://graph.facebook.com/v21.0/106850078877666/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+16505551234",
    "recipient_identity_key_hash": "DF2lS5v2W6x=",
    "type": "text",
    "text": {
        "preview_url": false,
        "body": "Your latest statement is attached. See... "
    }
}'

Exemple de webhook de message entrant

Dans les webhooks de message entrant, le hash du client ou de la cliente est affecté à la propriété identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo Morales"
                },
                "wa_id": "16505551234",
                "identity_key_hash": "DF2lS5v2W6x="
              }
            ],
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUMyNTA4M0VGN0Q4RjdDNDVCMAA=",
                "timestamp": "1686591695",
                "text": {
                  "body": "Your latest statement is attached. See... "
                },
                "type": "text"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Exemple de webhook de statut de distribution

Dans les webhooks de statut de distribution, le hash du client ou de la cliente est affecté à la propriété recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJGODlDQjZBNjUxMUQ5NEU0MEUA",
                "status": "delivered",
                "timestamp": "1686591922",
                "recipient_id": "16505551234",
                "recipient_identity_key_hash": "DF2lS5v2W6x=",
                "conversation": {
                  "id": "6c84493f3de086c7c68d5a39248f72c0",
                  "origin": {
                    "type": "service"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "CBP",
                  "category": "service"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Exemple de webhook de statut d’échec de la distribution

Dans les webhooks de statut de distribution, le hash du client ou de la cliente est affecté à la propriété recipient_identity_key_hash.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550051310",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQzA0OEU4OTdEQUE5REVCQTgA",
                "status": "failed",
                "timestamp": "1686594665",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 137000,
                    "title": "Confirm the correct Recipient Identity Key Hash or send without any identity key hash"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Déterminer le débit

Utilisez le point de terminaison numéro de téléphone WhatsApp Business afin de déterminer le débit actuel pour un numéro de téléphone spécifique :

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput