Attribuer un numéro à une campagne de messagerie

Attribuer un numéro d'envoi à une campagne

Utilisez cette opération une fois que votre marque de messagerie et votre campagne de production sont enregistrées et que la campagne est active. Elle associe un numéro compatible SMS de votre compte à la campagne. Elle ne crée pas de marque, ne crée ni n'approuve de campagne, n'achète pas de numéro et n'envoie pas de message.

Le portail actuel utilise cette route lors de l'attribution d'une campagne à un numéro. L'API publique accepte un identifiant de campagne ; elle déduit la marque à partir de la campagne détenue par le compte plutôt que d'accepter un identifiant de marque distinct.

Requête

Envoyez une requête POST encodée en formulaire via HTTPS en utilisant votre compte API activé et son adresse IP source autorisée. Utilisez les identifiants réels de numéro et de campagne de votre compte. Le numéro de cet exemple est fictif.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

L'opération modifie un seul numéro. Elle n'a ni pagination, ni paramètre de lot, ni option de simulation. N'utilisez pas un point de terminaison de création de campagne simplement pour rattacher un numéro à une campagne existante.

Supprimer l'association actuelle

Utilisez action=delete avec le numéro détenu. Cela supprime son association de campagne d'envoi et efface les champs de marque/campagne enregistrés pour ce numéro. Cela ne supprime pas la campagne ni la marque, ne libère pas le numéro de téléphone, n'annule pas le service du numéro et n'arrête pas la facturation récurrente de la campagne.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Réponse et vérification

Cet exemple fictif illustre l'enveloppe de réponse API ordinaire et une sélection de champs de résultat. Le numéro renvoyé conserve le format enregistré dans votre compte. brandId et campaignId sont des chaînes vides après une suppression réussie.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus est le statut HTTP du partenaire de messagerie. Le gestionnaire accepte une réponse de transport 2xx puis met à jour l'enregistrement local du numéro ; il n'interprète pas le corps de la réponse du partenaire pour en tirer un résultat d'acceptation métier distinct. Une réponse de succès ne prouve donc pas que l'enregistrement de messagerie est terminé ni que la livraison réussira. Vérifiez le statut de campagne du numéro dans le portail avant d'envoyer du trafic de production.

Ne considérez pas une association locale seule comme une approbation de livraison. L'approbation de la campagne et de la marque, le provisionnement du numéro, les permissions du compte, les règles de contenu et les limites de messagerie ordinaires s'appliquent toujours.

Erreurs et résultats partiels

• 401 : aucun compte authentifié n'est disponible pour le gestionnaire.
• 400 : action ou number est manquant ou non valide, ou une requête add n'a pas d'identifiant de campagne.
• 404 : le numéro n'est pas un numéro SMS détenu, actif et non annulé.
• 409 : la campagne est indisponible pour le compte, n'est pas ACTIVE, est explicitement sandbox, ou sa marque est indisponible pour le compte.
• 503 : l'intégration de messagerie est indisponible. Contactez le support plutôt que de modifier les identifiants du compte ou d'inventer des valeurs de configuration.
• 502 : la requête de messagerie a échoué, a expiré ou a renvoyé un statut HTTP autre que 2xx. providerStatus peut être renvoyé. Un dépassement de délai ne prouve pas que le partenaire n'a effectué aucune modification.
• 500 avec partial=true : le partenaire de messagerie a renvoyé un statut HTTP de succès, mais l'association locale n'a pas pu être confirmée. Rapprochez le numéro dans le portail ou contactez le support avant de réessayer.

Vérifiez le code de statut de l'API et le corps de la réponse ainsi que le résultat HTTP. Ne réessayez pas aveuglément après un dépassement de délai ou un résultat partiel. Ce gestionnaire n'a pas de clé d'idempotence au niveau de la requête, de restauration transactionnelle ni de vérification de l'achèvement de l'enregistrement de campagne. Une attribution locale répétée et identique peut renvoyer un succès même lorsque la base de données ne signale aucune ligne modifiée.

Portée et effets

Cette opération modifie le routage du numéro d'envoi et son association campagne/marque enregistrée. Elle ne comporte aucun débit direct du compte, aucune création de campagne, aucun achat ni aucun envoi de message dans le gestionnaire examiné. Il ne s'agit ni d'un devis ni d'une promesse de service gratuit : les frais existants de numéro, de campagne et de messagerie continuent de s'appliquer selon les conditions de votre compte.

Dans le portail, le passage à une autre campagne supprime d'abord l'association précédente, puis ajoute la nouvelle. Il s'agit de requêtes distinctes. Si la seconde requête échoue, l'association précédente peut déjà avoir été supprimée. Ne supposez pas que les deux requêtes s'annulent ensemble.