Assegnare un numero a una campagna di messaggistica

Assegnare un numero di invio a una campagna

Usa questa operazione dopo che il tuo brand di messaggistica e la tua campagna di produzione sono stati registrati e la campagna è attiva. Associa alla campagna un numero abilitato agli SMS presente sul tuo account. Non crea un brand, non crea né approva una campagna, non acquista un numero e non invia un messaggio.

Il portale attuale usa questa route quando assegna una campagna a un numero. L'API pubblica accetta un identificatore di campagna; ricava il brand dalla campagna di proprietà dell'account anziché accettare un identificatore di brand separato.

Richiesta

Invia una POST con codifica form tramite HTTPS, usando il tuo account API abilitato e il relativo indirizzo IP di origine consentito. Usa gli identificatori reali di numero e campagna del tuo account. Il numero in questo esempio è fittizio.

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'operazione modifica un solo numero. Non ha paginazione, parametro batch né opzione di prova (dry-run). Non usare un endpoint di creazione campagne solo per collegare un numero a una campagna esistente.

Rimuovere l'associazione attuale

Usa action=delete con il numero di tua proprietà. Questo rimuove l'associazione del numero con la campagna di invio e cancella i campi brand/campagna salvati per quel numero. Non elimina la campagna né il brand, non rilascia il numero di telefono, non annulla il servizio del numero e non interrompe la fatturazione ricorrente della campagna.

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

Risposta e verifica

Questo esempio fittizio illustra il consueto envelope di risposta dell'API e alcuni campi di risultato selezionati. Il numero restituito conserva il formato memorizzato nel tuo account. brandId e campaignId sono stringhe vuote dopo una rimozione riuscita.

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

providerStatus è lo stato HTTP del partner di messaggistica. L'handler accetta una risposta di trasporto 2xx e poi aggiorna il record locale del numero; non interpreta il corpo della risposta del partner per ottenere un esito di accettazione separato a livello commerciale. Una risposta di successo non è quindi prova che la registrazione della messaggistica sia completa o che la consegna andrà a buon fine. Controlla lo stato della campagna del numero nel portale prima di inviare traffico di produzione.

Non considerare la sola associazione locale come approvazione alla consegna. L'approvazione della campagna e del brand, il provisioning del numero, i permessi dell'account, le regole sui contenuti e i normali limiti di messaggistica continuano ad applicarsi.

Errori e risultati parziali

• 401: nessun account autenticato è disponibile per l'handler.
• 400: action o number è mancante o non valido, oppure una richiesta add non ha alcun identificatore di campagna.
• 404: il numero non è un numero SMS di tua proprietà, attivo e non annullato.
• 409: la campagna non è disponibile per l'account, non è ACTIVE, è esplicitamente sandbox oppure il suo brand non è disponibile per l'account.
• 503: l'integrazione di messaggistica non è disponibile. Contatta il supporto anziché modificare le credenziali dell'account o inventare valori di configurazione.
• 502: la richiesta di messaggistica non è riuscita, è scaduta o ha restituito uno stato HTTP diverso da 2xx. providerStatus può essere restituito. Un timeout non dimostra che il partner non abbia apportato alcuna modifica.
• 500 con partial=true: il partner di messaggistica ha restituito uno stato HTTP di successo, ma non è stato possibile confermare l'associazione locale. Riconcilia il numero nel portale o contatta il supporto prima di riprovare.

Controlla il codice di stato dell'API e il corpo della risposta, oltre al risultato HTTP. Non ripetere alla cieca una richiesta dopo un timeout o un risultato parziale. Questo handler non ha una chiave di idempotenza a livello di richiesta, un rollback transazionale né una verifica del completamento della registrazione della campagna. Un'assegnazione locale ripetuta e identica può restituire successo anche quando il database non segnala righe modificate.

Ambito ed effetti

Questa operazione modifica l'instradamento del numero di invio e la relativa associazione campagna/brand salvata. Nell'handler esaminato non contiene alcun addebito diretto sull'account, creazione di campagne, acquisto o invio di messaggi. Non si tratta di un preventivo né di una promessa di servizio gratuito: gli addebiti esistenti per numero, campagna e messaggistica continuano secondo i termini del tuo account.

Nel portale, il passaggio a una campagna diversa rimuove prima l'associazione precedente e poi aggiunge quella nuova. Si tratta di richieste separate. Se la seconda richiesta non riesce, l'associazione precedente potrebbe essere già stata rimossa. Non dare per scontato che le due richieste vengano annullate insieme.