Atribuirea unui număr unei campanii de mesagerie

Atribuirea unui număr de expediere unei campanii

Folosiți această operație după ce marca de mesagerie și campania de producție sunt înregistrate, iar campania este activă. Operația asociază un număr cu SMS activat din contul dvs. cu campania. Nu creează o marcă, nu creează și nu aprobă o campanie, nu cumpără un număr și nu trimite un mesaj.

Portalul curent folosește această rută la atribuirea unei campanii unui număr. API-ul public acceptă un identificator de campanie; deduce marca din campania deținută de cont, în loc să accepte un identificator separat de marcă.

Cerere

Trimiteți o cerere POST codificată ca formular prin HTTPS, folosind contul API activat și adresa IP sursă permisă a acestuia. Folosiți identificatorii reali ai numărului și campaniei din contul dvs. Numărul din acest exemplu este fictiv.

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'

Parametrii atribuirii campaniei
Parametru	Obligatoriu	Semnificație
action	Da	Folosiți add pentru a atribui sau delete pentru a elimina asocierea curentă a numărului cu o campanie. Majusculele și spațiile din jur sunt normalizate.
campaign	Pentru add	campaignId al unei campanii cu starea ACTIVE deținute de contul autentificat. Marca acesteia trebuie să aparțină, de asemenea, contului. O campanie marcată explicit ca sandbox nu poate fi atribuită numerelor de expediere de producție. Omiteți acest parametru pentru delete; eliminarea folosește asocierea existentă a numărului.
number	Da	Numărul de expediere deținut, activ, neanulat, cu SMS activat. Pentru un număr nord-american, folosiți codul de țară 1 urmat de cele zece cifre ale numărului, fără semnul plus. Handlerul elimină caracterele care nu sunt cifre și caută, de asemenea, echivalentele cu prefix plus și cu zece cifre. Această normalizare nu este o verificare generală a validității numărului de telefon.

Operația modifică un singur număr. Nu are paginare, parametru de lot sau opțiune de rulare de probă. Nu folosiți un endpoint de creare a campaniei doar pentru a atașa un număr unei campanii existente.

Eliminarea asocierii curente

Folosiți action=delete cu numărul deținut. Aceasta elimină asocierea sa cu campania de expediere și golește câmpurile salvate de marcă/campanie pentru acel număr. Nu șterge campania sau marca, nu eliberează numărul de telefon, nu anulează serviciul numărului și nu oprește facturarea recurentă a campaniei.

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

Răspuns și verificare

Acest exemplu fictiv ilustrează anvelopa obișnuită a răspunsului API și câmpurile de rezultat selectate. Numărul returnat păstrează formatul stocat în contul dvs. brandId și campaignId sunt șiruri goale după o eliminare reușită.

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

providerStatus este starea HTTP a partenerului de mesagerie. Handlerul acceptă un răspuns de transport 2xx și apoi actualizează înregistrarea locală a numărului; nu interpretează corpul răspunsului partenerului pentru un rezultat separat de acceptare la nivel comercial. Un răspuns de succes nu este, prin urmare, o dovadă că înregistrarea mesageriei este finalizată sau că livrarea va reuși. Verificați starea campaniei numărului în portal înainte de a trimite trafic de producție.

Nu tratați o asociere locală în sine ca aprobare a livrării. Aprobarea campaniei și a mărcii, provizionarea numărului, permisiunile contului, regulile de conținut și limitele obișnuite de mesagerie se aplică în continuare.

Erori și rezultate parțiale

401: handlerul nu are la dispoziție niciun cont autentificat.
400: action sau number lipsește sau este nevalid, ori o cerere add nu are identificator de campanie.
404: numărul nu este un număr SMS deținut, activ și neanulat.
409: campania nu este disponibilă contului, nu are starea ACTIVE, este marcată explicit ca sandbox sau marca sa nu este disponibilă contului.
503: integrarea de mesagerie nu este disponibilă. Contactați asistența în loc să modificați datele de autentificare ale contului sau să inventați valori de configurare.
502: cererea de mesagerie a eșuat, a expirat sau a returnat o stare HTTP diferită de 2xx. providerStatus poate fi returnat. O expirare nu dovedește că partenerul nu a făcut nicio modificare.
500 cu partial=true: partenerul de mesagerie a returnat o stare HTTP de succes, dar asocierea locală nu a putut fi confirmată. Reconciliați numărul în portal sau contactați asistența înainte de a reîncerca.

Verificați codul de stare al API-ului și corpul răspunsului, precum și rezultatul HTTP. Nu reîncercați orbește după o expirare sau un rezultat parțial. Acest handler nu are cheie de idempotență la nivel de cerere, revenire tranzacțională sau verificare a finalizării înregistrării campaniei. O atribuire locală repetată și identică poate returna succes chiar și atunci când baza de date nu raportează niciun rând modificat.

Domeniu și efecte

Această operație modifică rutarea numărului de expediere și asocierea sa salvată cu campania/marca. În handlerul revizuit nu conține nicio debitare directă a contului, creare de campanie, achiziție sau trimitere de mesaj. Aceasta nu este o ofertă de preț și nici o promisiune de serviciu gratuit: taxele existente pentru număr, campanie și mesagerie continuă conform condițiilor contului dvs.

În portal, schimbarea la o altă campanie elimină mai întâi asocierea anterioară și apoi o adaugă pe cea nouă. Acestea sunt cereri separate. Dacă a doua cerere eșuează, asocierea anterioară poate fi deja eliminată. Nu presupuneți că cele două cereri sunt anulate împreună.