Tildel et nummer til en meldingskampanje

Tildel et avsendernummer til en kampanje

Bruk denne operasjonen etter at meldingsmerket (brand) og produksjonskampanjen din er registrert og kampanjen er aktiv. Den knytter ett SMS-aktivert nummer på kontoen din til kampanjen. Den oppretter ikke et merke, oppretter eller godkjenner ikke en kampanje, kjøper ikke et nummer og sender ikke en melding.

Den gjeldende portalen bruker denne ruten når en kampanje tildeles et nummer. Det offentlige API-et godtar en kampanjeidentifikator; det utleder merket fra kampanjen som eies av kontoen, i stedet for å godta en separat merkeidentifikator.

Forespørsel

Send en skjemakodet POST over HTTPS med din aktiverte API-konto og dens tillatte kilde-IP-adresse. Bruk de faktiske nummer- og kampanjeidentifikatorene fra kontoen din. Nummeret i dette eksempelet er fiktivt.

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'

Parametere for kampanjetildeling
Parameter	Påkrevd	Betydning
action	Ja	Bruk add for å tildele eller delete for å fjerne nummerets gjeldende kampanjetilknytning. Store/små bokstaver og omkringliggende mellomrom normaliseres.
campaign	For add	campaignId for en ACTIVE-kampanje som eies av den autentiserte kontoen. Merket må også tilhøre kontoen. En kampanje som er eksplisitt merket som sandkasse (sandbox), kan ikke tildeles aktive avsendernumre. Utelat denne parameteren for delete; fjerning bruker nummerets eksisterende tilknytning.
number	Ja	Det eide, aktive, ikke-annullerte, SMS-aktiverte avsendernummeret. For et nordamerikansk nummer bruker du landkode 1 etterfulgt av de ti sifrene, uten plusstegn. Handleren fjerner tegn som ikke er sifre, og slår også opp ekvivalenter med plussprefiks og med ti sifre. Denne normaliseringen er ikke en generell gyldighetskontroll av telefonnumre.

Operasjonen endrer ett nummer. Den har ingen paginering, ingen batch-parameter og ingen tørrkjøringsmulighet. Ikke bruk et endepunkt for kampanjeopprettelse bare for å knytte et nummer til en eksisterende kampanje.

Fjern den gjeldende tilknytningen

Bruk action=delete med det eide nummeret. Dette fjerner nummerets tilknytning til avsenderkampanjen og tømmer de lagrede merke-/kampanjefeltene for det nummeret. Det sletter ikke kampanjen eller merket, frigir ikke telefonnummeret, sier ikke opp nummerets tjeneste og stopper ikke kampanjens løpende fakturering.

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

Svar og verifisering

Dette fiktive eksempelet illustrerer den ordinære API-svarkonvolutten og utvalgte resultatfelt. Det returnerte nummeret beholder formatet som er lagret i kontoen din. brandId og campaignId er tomme strenger etter en vellykket fjerning.

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

providerStatus er meldingspartnerens HTTP-status. Handleren godtar et 2xx-transportsvar og oppdaterer deretter den lokale nummeroppføringen; den tolker ikke partnerens svartekst for et separat forretningsmessig aksepteringsresultat. Et vellykket svar er derfor ikke bevis på at meldingsregistreringen er fullført, eller at levering vil lykkes. Kontroller nummerets kampanjestatus i portalen før du sender produksjonstrafikk.

Ikke betrakt en lokal tilknytning alene som leveringsgodkjenning. Godkjenning av kampanje og merke, nummerklargjøring, kontotillatelser, innholdsregler og ordinære meldingsgrenser gjelder fortsatt.

Feil og delvise resultater

401: ingen autentisert konto er tilgjengelig for handleren.
400: action eller number mangler eller er ugyldig, eller en add-forespørsel har ingen kampanjeidentifikator.
404: nummeret er ikke et eid, aktivt, ikke-annullert SMS-nummer.
409: kampanjen er utilgjengelig for kontoen, er ikke ACTIVE, er eksplisitt sandkasse, eller merket er utilgjengelig for kontoen.
503: meldingsintegrasjonen er utilgjengelig. Kontakt kundestøtte i stedet for å endre kontolegitimasjon eller finne på konfigurasjonsverdier.
502: meldingsforespørselen mislyktes, fikk tidsavbrudd eller returnerte en HTTP-status som ikke er 2xx. providerStatus kan bli returnert. Et tidsavbrudd beviser ikke at partneren ikke gjorde noen endring.
500 med partial=true: meldingspartneren returnerte en vellykket HTTP-status, men den lokale tilknytningen kunne ikke bekreftes. Avstem nummeret i portalen eller kontakt kundestøtte før du prøver på nytt.

Kontroller API-statuskoden og svarteksten i tillegg til HTTP-resultatet. Ikke prøv blindt på nytt etter et tidsavbrudd eller et delvis resultat. Denne handleren har ingen idempotensnøkkel på forespørselsnivå, ingen transaksjonell tilbakerulling og ingen kontroll av fullført kampanjeregistrering. En gjentatt, identisk lokal tildeling kan returnere suksess selv når databasen rapporterer ingen endrede rader.

Omfang og virkninger

Denne operasjonen endrer rutingen av avsendernummeret og dets lagrede kampanje-/merketilknytning. Den inneholder ingen direkte kontobelastning, kampanjeopprettelse, kjøp eller meldingssending i den gjennomgåtte handleren. Dette er ikke et pristilbud eller et løfte om gratis tjeneste: eksisterende kostnader for nummer, kampanje og meldinger fortsetter i henhold til kontovilkårene dine.

I portalen fjerner et bytte til en annen kampanje først den forrige tilknytningen og legger deretter til den nye. Dette er separate forespørsler. Hvis den andre forespørselen mislykkes, kan den tidligere tilknytningen allerede være fjernet. Ikke anta at de to forespørslene rulles tilbake sammen.