Tildel et nummer til en beskedkampagne

Tildel et afsendernummer til en kampagne

Brug denne operation, når dit beskedbrand og din produktionskampagne er registreret, og kampagnen er aktiv. Den knytter ét SMS-aktiveret nummer på din konto til kampagnen. Den opretter ikke et brand, opretter eller godkender ikke en kampagne, køber ikke et nummer og sender ikke en besked.

Den aktuelle portal bruger denne rute, når en kampagne tildeles et nummer. Det offentlige API accepterer en kampagneidentifikator; det udleder brandet fra den kontoejede kampagne i stedet for at acceptere en separat brandidentifikator.

Forespørgsel

Send en formularkodet POST over HTTPS med din aktiverede API-konto og dens tilladte kilde-IP-adresse. Brug de faktiske nummer- og kampagneidentifikatorer fra din konto. Nummeret i dette eksempel 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'

Parametre for kampagnetildeling
Parameter	Påkrævet	Betydning
action	Ja	Brug add for at tildele eller delete for at fjerne nummerets aktuelle kampagnetilknytning. Store og små bogstaver samt omgivende mellemrum normaliseres.
campaign	Ved add	campaignId for en ACTIVE kampagne, der ejes af den autentificerede konto. Dens brand skal også tilhøre kontoen. En kampagne, der udtrykkeligt er markeret som sandbox, kan ikke tildeles live afsendernumre. Udelad denne parameter ved delete; fjernelsen bruger nummerets eksisterende tilknytning.
number	Ja	Det ejede, aktive, ikke-annullerede, SMS-aktiverede afsendernummer. For et nordamerikansk nummer skal du bruge landekode 1 efterfulgt af nummerets ti cifre uden plustegn. Handleren fjerner tegn, der ikke er cifre, og slår også op på ækvivalenter med plus-præfiks og med ti cifre. Denne normalisering er ikke en generel gyldighedskontrol af telefonnumre.

Operationen ændrer ét nummer. Den har ingen paginering, ingen batchparameter og ingen dry-run-mulighed. Brug ikke et endpoint til oprettelse af kampagner blot for at knytte et nummer til en eksisterende kampagne.

Fjern den aktuelle tilknytning

Brug action=delete med det ejede nummer. Dette fjerner nummerets tilknytning til afsenderkampagnen og rydder de gemte brand-/kampagnefelter for det pågældende nummer. Det sletter ikke kampagnen eller brandet, frigiver ikke telefonnummeret, opsiger ikke nummerets tjeneste og stopper ikke kampagnens tilbagevendende 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 verifikation

Dette fiktive eksempel illustrerer den almindelige API-svarkonvolut og udvalgte resultatfelter. Det returnerede nummer bevarer det format, der er gemt på din konto. brandId og campaignId er tomme strenge efter en vellykket fjernelse.

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

providerStatus er beskedpartnerens HTTP-status. Handleren accepterer et 2xx-transportsvar og opdaterer derefter den lokale nummerpost; den fortolker ikke partnerens svartekst med henblik på et separat acceptresultat på forretningsniveau. Et succes-svar er derfor ikke bevis for, at beskedregistreringen er fuldført, eller at leveringen vil lykkes. Gennemgå nummerets kampagnestatus i portalen, før du sender produktionstrafik.

Betragt ikke en lokal tilknytning alene som leveringsgodkendelse. Godkendelse af kampagne og brand, nummerprovisionering, kontotilladelser, indholdsregler og almindelige beskedgrænser gælder fortsat.

Fejl og delvise resultater

401: der er ingen autentificeret konto tilgængelig for handleren.
400: action eller number mangler eller er ugyldig, eller en add-forespørgsel har ingen kampagneidentifikator.
404: nummeret er ikke et ejet, aktivt, ikke-annulleret SMS-nummer.
409: kampagnen er ikke tilgængelig for kontoen, er ikke ACTIVE, er udtrykkeligt sandbox, eller dens brand er ikke tilgængeligt for kontoen.
503: beskedintegrationen er ikke tilgængelig. Kontakt support i stedet for at ændre kontolegitimationsoplysninger eller opfinde konfigurationsværdier.
502: beskedforespørgslen mislykkedes, fik timeout eller returnerede en HTTP-status, der ikke er 2xx. providerStatus kan blive returneret. En timeout beviser ikke, at partneren ikke foretog nogen ændring.
500 med partial=true: beskedpartneren returnerede en vellykket HTTP-status, men den lokale tilknytning kunne ikke bekræftes. Afstem nummeret i portalen, eller kontakt support, før du prøver igen.

Kontrollér API-statuskoden og svarteksten såvel som HTTP-resultatet. Prøv ikke blindt igen efter en timeout eller et delvist resultat. Denne handler har ingen idempotensnøgle på forespørgselsniveau, ingen transaktionel rollback og ingen kontrol af, at kampagneregistreringen er fuldført. En gentaget, matchende lokal tildeling kan returnere succes, selv når databasen rapporterer ingen ændrede rækker.

Omfang og virkninger

Denne operation ændrer afsendernummerets routing og dets gemte kampagne-/brandtilknytning. Den indeholder ingen direkte kontodebitering, kampagneoprettelse, køb eller beskedafsendelse i den gennemgåede handler. Dette er ikke et pristilbud eller et løfte om gratis service: eksisterende gebyrer for nummer, kampagne og beskeder fortsætter i henhold til dine kontovilkår.

I portalen fjerner et skift til en anden kampagne først den tidligere tilknytning og tilføjer derefter den nye. Det er separate forespørgsler. Hvis den anden forespørgsel mislykkes, kan den tidligere tilknytning allerede være fjernet. Gå ikke ud fra, at de to forespørgsler rulles tilbage sammen.