Contacts

/v1/contacts

Utilisez le nœud contacts pour gérer les utilisateur·ices WhatsApp de votre base de données, les valider avant de leur envoyer des messages et vérifier leur identité à l’aide des hachages d’identité.

Avec le nœud contacts, vous pouvez :

• Vérifier qu’un numéro de téléphone figurant dans votre base de données appartient à un compte WhatsApp valide. Vous devez vérifier que le status d’un·e utilisateur·ice est valid avant de lui envoyer un message.
• Obtenir l’ID WhatsApp associé à un numéro de téléphone. Les ID WhatsApp sont nécessaires pour envoyer des messages et des notifications aux utilisateur·ices.

Avant de commencer

Vous devez proposer à votre clientèle de s’inscrire aux communications WhatsApp de votre entreprise. Cette procédure est gérée par votre entreprise. Après l’inscription d’un client ou d’une cliente, utilisez le nœud contacts pour valider le numéro inscrit. Pour plus d’informations, consultez la rubrique Comprendre comment obtenir les inscriptions pour WhatsApp.

Limites

• Utilisez ce point de terminaison pour vérifier qu’un numéro de téléphone figurant dans la base de données d’une entreprise appartient bien à un compte WhatsApp valide.
• Le nombre d’appels ne doit pas dépasser le nombre de messages que ce numéro de téléphone envoie.

Mise en application

Si une entreprise utilise ce point de terminaison de manière détournée, voici les actions qui seront entreprises :

• Tous les admins figurant dans Business Manager recevront un premier avertissement par e-mail si une utilisation à mauvais escient est suspectée.
• L’entreprise aura sept jours après la réception de cet avertissement pour modifier son comportement.
• Si après ce délai de sept jours, les appels n’ont pas été ajustés, le numéro de téléphone sera définitivement désactivé.

Recommandations

Nous vous recommandons de vérifier votre liste de contacts avant d’envoyer des messages. Cependant, vous n’avez pas besoin de vérifier les contacts pour répondre au message d’un client ou d’une cliente. Vous pouvez répondre immédiatement en utilisant l’ID wa_id fourni. Cette opération n’entraîne aucun surcoût, car les résultats sont mis en cache.

Création

Avant d’envoyer des messages aux utilisateurs et utilisatrices qui ont choisi d’en recevoir, envoyez une requête POST au point de terminaison /v1/contacts pour créer une demande de validation de leur compte WhatsApp. Dans votre appel, incluez la liste des numéros de téléphone à valider.

Exemple

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

Vous recevrez une réponse contenant le status actuel des numéros demandés et leur ID WhatsApp (wa_id) :

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

Enregistrez les ID WhatsApp des numéros ayant renvoyé un statusvalid. Les utilisatrices et utilisateurs valides sont celles et ceux qui possèdent un compte WhatsApp. Utilisez les ID WhatsApp pour envoyer des messages et des notifications.

Répétez régulièrement ces étapes pour gérer votre liste d’utilisateur·ices valides. Les résultats sont mis en cache dans la base de données du client de l’API On-Premises WhatsApp Business pendant sept jours.

Paramètres

Les paramètres suivants sont acceptés pour les appels POST au point de terminaison /v1/contacts :

Arêtes

Les arêtes ci-dessous sont connectées à ce nœud :

Blocage

Le paramètre blocking offre deux options : no_wait et wait. Lorsque le paramètre blocking n’est pas spécifié dans un appel, l’état par défaut est no_wait.

Le paramètre blocking détermine si la requête doit attendre la fin du processus de traitement (synchrone) ou ne pas l’attendre (asynchrone).

Formats des numéros de téléphone

Les numéros de téléphone compris dans la requête de contacts peuvent utiliser n’importe quel format accepté.

Voici quelques exemples décrivant ce comportement, en supposant que le client de l’API On-Premises WhatsApp Business est enregistré sous un numéro de téléphone indien (+91) :

Champs renvoyés

La charge utile de la réponse contacts contient le même tableau de numéros de téléphone que dans la requête envoyée avec les propriétés input, status et wa_id :

En plus du statut processing, vous devriez voir apparaître un statut HTTP 200 OK.

Si un modèle de message est envoyé à un numéro de téléphone sans compte WhatsApp, vous recevrez un message d’erreur indiquant un·e utilisateur·ice non valide, ainsi que le code d’erreur 1013.

Si d’autres erreurs sont présentes dans la réponse, consultez la section Messages d’erreur et de statut.

Blocage des contacts

Le blocage peut être considéré comme une fonctionnalité de protection permettant d’empêcher les personnes malveillantes de poursuivre leurs actions nuisibles. Pour bloquer un contact, ce dernier doit vous avoir envoyé un message au cours des dernières 24 heures.

Exemple

Envoyez un appel d’API à /v1/contacts/{phone_number}/block ayant pour motif le blocage d’un autre compte WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

En cas de réussite, la réponse est associée au statut HTTP 200 et ne comporte aucun objet errors.

Exemple de réponse en cas d’échec :

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Paramètres

Les paramètres suivants sont acceptés pour les appels POST à /v1/contacts/{phone_number}/block :

Déblocage des contacts

Passez cet appel pour débloquer un contact

Exemple

Envoyez un appel d’API à /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

En cas de réussite, la réponse est associée au statut HTTP 200 et ne comporte aucun objet errors.

Exemple de réponse en cas d’échec :

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

Paramètres

Les paramètres suivants sont acceptés pour les appels POST à /v1/contacts/{phone_number}/unblock :

Liste d’éléments bloqués

Il s’agit de la façon dont vous obtenez une liste des contacts bloqués.

Exemple

Envoyez un appel d’API à /v1/contacts/blocklist pour recevoir une liste paginée des contacts bloqués.

GET /v1/contacts/blocklist?limit=10&offset=0

Vous recevrez une réponse contenant une page reprenant votre liste d’éléments bloqués, accompagnée d’informations de pagination.

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

Paramètres

Les paramètres suivants sont acceptés pour les appels GET à /v1/contacts/blocklist :

Signalement

Le signalement fournit des indications permettant de se prémunir des personnes malveillantes. Pour signaler un contact, ce dernier doit vous avoir envoyé un message au cours des dernières 24 heures.

Exemple

Envoyez un appel d’API à /v1/contacts/{phone_number}/report accompagné d’un motif si vous bloquez un autre compte WhatsApp.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

En cas de réussite, la réponse est associée au statut HTTP 200 et ne comporte aucun objet errors.

Exemple de réponse en cas d’échec :

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Paramètres

Les paramètres suivants sont acceptés pour les appels POST à /v1/contacts/{phone_number}/report :