· 2 min · TextMeFlow Team

Éviter l'erreur 400 invalid_recipient : valider les numéros

Une réponse 400 invalid_recipient paraît anodine : un envoi échoué, on réessaie avec un numéro corrigé et on passe à autre chose. Mais chaque envoi rejeté ajoute aussi des points au score de risque de votre compte, et si les mauvais numéros proviennent d'un import désordonné (un export de CRM, un tableur saisi à la main), vous pouvez en accumuler des dizaines dans un seul traitement par lots sans vous en apercevoir. La solution est peu coûteuse : validez le format du numéro dans votre propre code avant qu'il n'atteigne l'API.

Ce que TextMeFlow exige exactement

Le pipeline anti-spam impose un format E.164 strict sur chaque champ to. Une seule forme est acceptée :

  • +32472932208 — valide : indicatif du pays, sans espaces, sans zéro initial, sans séparateurs.
  • 0472932208 — invalide : indicatif du pays manquant.
  • 32472932208 — invalide : le + initial est manquant.
  • +32-472-93-22-08 — invalide : les tirets ne sont pas autorisés.

Les numéros courts, les numéros surtaxés et les numéros gratuits sont refusés d'office, quel que soit le format — WhatsApp Web ne fonctionne pas sur ces types de numéros, il n'y a donc rien à associer de l'autre côté. Tout numéro qui échoue à ces contrôles renvoie un 400 invalid_recipient depuis POST /v1/messages et ajoute +10 au score de risque de votre compte à chaque fois (voir la décomposition du score de risque pour comprendre comment ce total mène à la suspension).

Validez avant d'appeler l'API, pas après

L'endroit le moins coûteux pour intercepter un numéro mal formé est le moment où il entre dans votre système — un formulaire d'inscription, un import CSV, une synchronisation CRM — et non au moment de l'envoi. Une simple expression régulière détecte la grande majorité des erreurs de format :

// Node.js
const E164_RE = /^\+[1-9]\d{7,14}$/;

function isValidE164(phone) {
  return typeof phone === 'string' && E164_RE.test(phone.trim());
}

function normalizeToE164(raw, defaultCountryCode) {
  const digits = raw.replace(/[^\d+]/g, '');
  if (digits.startsWith('+')) return digits;
  if (digits.startsWith('00')) return '+' + digits.slice(2);
  if (digits.startsWith('0')) return `+${defaultCountryCode}${digits.slice(1)}`;
  return `+${defaultCountryCode}${digits}`;
}
<?php
function isValidE164(string $phone): bool
{
    return (bool) preg_match('/^\+[1-9]\d{7,14}$/', trim($phone));
}

function normalizeToE164(string $raw, string $defaultCountryCode): string
{
    $digits = preg_replace('/[^\d+]/', '', $raw);
    if (str_starts_with($digits, '+')) {
        return $digits;
    }
    if (str_starts_with($digits, '00')) {
        return '+' . substr($digits, 2);
    }
    if (str_starts_with($digits, '0')) {
        return '+' . $defaultCountryCode . substr($digits, 1);
    }
    return '+' . $defaultCountryCode . $digits;
}

Le normaliseur gère les deux désordres les plus courants dans la réalité — un numéro national avec un zéro initial (0472932208) et le préfixe d'appel international à la place du + (0032472932208) — mais il ne peut pas deviner un indicatif de pays qui ne figurait jamais dans les données. Stockez le pays avec le numéro brut partout où vous le collectez (une liste déroulante de pays à côté d'un champ de téléphone vaut bien le clic supplémentaire), et rejetez tout le reste comme irrésolvable plutôt que de continuer à deviner.

Ne vous contentez pas d'ignorer : journalisez et signalez

Lorsqu'un import par lots échoue à la validation, résistez à l'envie de supprimer silencieusement la ligne. Rassemblez les rejets et rendez-les visibles :

const results = contacts.map((c) => ({
  ...c,
  e164: isValidE164(c.phone) ? c.phone : normalizeToE164(c.phone, defaultCc),
}));

const rejected = results.filter((r) => !isValidE164(r.e164));
if (rejected.length) {
  console.warn(`${rejected.length} contacts could not be normalized to E.164`, rejected);
}

Cette ligne de journal vous signale que l'export du CRM a un problème de qualité des données avant qu'il n'épuise votre budget de score de risque, un 400 à la fois.

À combiner avec la vérification des désinscriptions

Le format du numéro n'est que la moitié du contrôle préalable. Si un destinataire a déjà répondu STOP, TextMeFlow rejette l'envoi avec recipient_opted_out et ajoute +50 à votre score de risque — cinq fois la pénalité d'un mauvais numéro. Abonnez-vous à l'événement webhook opt_out et tenez une table locale des destinataires désinscrits afin que votre propre code les ignore avant de tenter un envoi, plutôt que de compter sur l'API pour le rattraper après coup à chaque fois.

Le schéma à retenir

Deux contrôles peu coûteux, exécutés avant chaque POST /v1/messages : s'agit-il d'un numéro E.164 bien formé, et ce destinataire s'est-il désinscrit. Les deux prennent quelques microsecondes en local et ne coûtent rien ; les deux vous évitent une hausse du score de risque et un aller-retour d'API inutile lorsqu'ils détectent quelque chose. Pour tout ce que vous ne pouvez pas résoudre — un numéro sans indicatif de pays et sans moyen d'en deviner un — signalez-le à une personne plutôt que de l'envoyer en espérant que tout se passe bien.

Envie de voir les erreurs de validation par vous-même avant de brancher cela en production ? Inscrivez-vous à l'offre gratuite — 50 messages par mois, sans carte bancaire — et envoyez volontairement un numéro mal formé pour voir la forme exacte de la réponse 400 invalid_recipient.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours