Tilldela ett nummer till en meddelandekampanj

Tilldela ett avsändarnummer till en kampanj

Använd den här åtgärden efter att ditt meddelandevarumärke (brand) och din produktionskampanj har registrerats och kampanjen är aktiv. Den kopplar ett SMS-aktiverat nummer på ditt konto till kampanjen. Den skapar inte ett varumärke, skapar eller godkänner inte en kampanj, köper inte ett nummer och skickar inte ett meddelande.

Den aktuella portalen använder den här rutten när en kampanj tilldelas ett nummer. Det publika API:et tar emot en kampanjidentifierare; det härleder varumärket från den kontoägda kampanjen i stället för att ta emot en separat varumärkesidentifierare.

Begäran

Skicka en formulärkodad POST över HTTPS med ditt aktiverade API-konto och dess tillåtna käll-IP-adress. Använd de faktiska nummer- och kampanjidentifierarna från ditt konto. Numret i det här exemplet är 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'

Parametrar för kampanjtilldelning
Parameter	Obligatorisk	Betydelse
action	Ja	Använd add för att tilldela eller delete för att ta bort numrets aktuella kampanjkoppling. Skiftläge och omgivande blanksteg normaliseras.
campaign	För add	campaignId för en ACTIVE-kampanj som ägs av det autentiserade kontot. Dess varumärke måste också tillhöra kontot. En kampanj som uttryckligen är markerad som sandlåda (sandbox) kan inte tilldelas skarpa avsändarnummer. Utelämna den här parametern för delete; borttagning använder numrets befintliga koppling.
number	Ja	Det ägda, aktiva, icke-annullerade, SMS-aktiverade avsändarnumret. För ett nordamerikanskt nummer använder du landskod 1 följt av dess tio siffror, utan plustecken. Hanteraren tar bort tecken som inte är siffror och slår även upp motsvarigheter med plusprefix och med tio siffror. Den här normaliseringen är inte en allmän giltighetskontroll av telefonnummer.

Åtgärden ändrar ett nummer. Den har ingen paginering, ingen batchparameter och inget alternativ för torrkörning. Använd inte en slutpunkt för kampanjskapande enbart för att koppla ett nummer till en befintlig kampanj.

Ta bort den aktuella kopplingen

Använd action=delete med det ägda numret. Detta tar bort numrets koppling till avsändarkampanjen och rensar de sparade varumärkes-/kampanjfälten för det numret. Det raderar inte kampanjen eller varumärket, frigör inte telefonnumret, säger inte upp numrets tjänst och stoppar inte kampanjens återkommande 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 och verifiering

Det här fiktiva exemplet illustrerar det vanliga API-svarshöljet och utvalda resultatfält. Det returnerade numret behåller det format som är lagrat i ditt konto. brandId och campaignId är tomma strängar efter en lyckad borttagning.

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

providerStatus är meddelandepartnerns HTTP-status. Hanteraren accepterar ett 2xx-transportsvar och uppdaterar därefter den lokala nummerposten; den tolkar inte partnerns svarskropp för ett separat affärsmässigt acceptansresultat. Ett lyckat svar är därför inte bevis på att meddelanderegistreringen är slutförd eller att leveransen kommer att lyckas. Granska numrets kampanjstatus i portalen innan du skickar produktionstrafik.

Betrakta inte en lokal koppling i sig som ett leveransgodkännande. Godkännande av kampanj och varumärke, nummerprovisionering, kontobehörigheter, innehållsregler och vanliga meddelandegränser gäller fortfarande.

Fel och partiella resultat

401: inget autentiserat konto är tillgängligt för hanteraren.
400: action eller number saknas eller är ogiltig, eller en add-begäran saknar kampanjidentifierare.
404: numret är inte ett ägt, aktivt, icke-annullerat SMS-nummer.
409: kampanjen är otillgänglig för kontot, är inte ACTIVE, är uttryckligen sandlåda, eller dess varumärke är otillgängligt för kontot.
503: meddelandeintegrationen är otillgänglig. Kontakta supporten i stället för att ändra kontouppgifter eller hitta på konfigurationsvärden.
502: meddelandebegäran misslyckades, fick timeout eller returnerade en HTTP-status som inte är 2xx. providerStatus kan returneras. En timeout bevisar inte att partnern inte gjorde någon ändring.
500 med partial=true: meddelandepartnern returnerade en lyckad HTTP-status, men den lokala kopplingen kunde inte bekräftas. Stäm av numret i portalen eller kontakta supporten innan du försöker igen.

Kontrollera API:ets statuskod och svarskropp utöver HTTP-resultatet. Försök inte blint igen efter en timeout eller ett partiellt resultat. Den här hanteraren har ingen idempotensnyckel på begärannivå, ingen transaktionell återställning och ingen kontroll av slutförd kampanjregistrering. En upprepad, matchande lokal tilldelning kan returnera lyckat resultat även när databasen rapporterar inga ändrade rader.

Omfattning och effekter

Den här åtgärden ändrar avsändarnumrets routning och dess sparade kampanj-/varumärkeskoppling. Den innehåller ingen direkt kontodebitering, inget kampanjskapande, inget köp och ingen meddelandesändning i den granskade hanteraren. Detta är inte en prisuppgift eller ett löfte om kostnadsfri tjänst: befintliga avgifter för nummer, kampanj och meddelanden fortsätter enligt dina kontovillkor.

I portalen tar ett byte till en annan kampanj först bort den tidigare kopplingen och lägger sedan till den nya. Det är separata begäranden. Om den andra begäran misslyckas kan den tidigare kopplingen redan vara borttagen. Anta inte att de två begärandena återställs tillsammans.