Numeron määrittäminen viestikampanjalle

Lähetysnumeron määrittäminen kampanjalle

Käytä tätä toimintoa sen jälkeen, kun viestibrändisi ja tuotantokampanjasi on rekisteröity ja kampanja on aktiivinen. Se liittää yhden tilisi SMS-käyttöisen numeron kampanjaan. Se ei luo brändiä, luo tai hyväksy kampanjaa, osta numeroa eikä lähetä viestiä.

Nykyinen portaali käyttää tätä reittiä, kun kampanja määritetään numerolle. Julkinen API hyväksyy kampanjatunnisteen; se johtaa brändin tilin omistamasta kampanjasta sen sijaan, että se hyväksyisi erillisen bränditunnisteen.

Pyyntö

Lähetä lomakekoodattu POST-pyyntö HTTPS-yhteydellä käyttäen käyttöön otettua API-tiliäsi ja sen sallittua lähde-IP-osoitetta. Käytä tilisi todellisia numero- ja kampanjatunnisteita. Tämän esimerkin numero on kuvitteellinen.

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'

Kampanjan määritysparametrit
Parametri	Pakollinen	Merkitys
action	Kyllä	Käytä arvoa add määrittääksesi tai arvoa delete poistaaksesi numeron nykyisen kampanjaliitoksen. Kirjainkoko ja ympäröivät välilyönnit normalisoidaan.
campaign	Arvolle add	Sen kampanjan campaignId, jonka tila on ACTIVE ja jonka todennettu tili omistaa. Myös sen brändin on kuuluttava tilille. Nimenomaisesti sandbox-kampanjaksi merkittyä kampanjaa ei voi määrittää live-lähetysnumeroille. Jätä tämä parametri pois, kun arvo on delete; poisto käyttää numeron olemassa olevaa liitosta.
number	Kyllä	Omistettu, aktiivinen, mitätöimätön, SMS-käyttöinen lähetysnumero. Pohjoisamerikkalaiselle numerolle käytä maakoodia 1 ja sen perässä numeron kymmentä numeromerkkiä ilman plusmerkkiä. Käsittelijä poistaa muut kuin numeromerkit ja hakee myös plus-etuliitteiset ja kymmennumeroiset vastineet. Tämä normalisointi ei ole yleinen puhelinnumeron kelpoisuustarkistus.

Toiminto muuttaa yhtä numeroa. Siinä ei ole sivutusta, eräparametria eikä kuivaharjoitusvaihtoehtoa. Älä käytä kampanjan luontipäätepistettä pelkästään numeron liittämiseen olemassa olevaan kampanjaan.

Nykyisen liitoksen poistaminen

Käytä arvoa action=delete omistetun numeron kanssa. Tämä poistaa numeron lähetyskampanjaliitoksen ja tyhjentää kyseisen numeron tallennetut brändi-/kampanjakentät. Se ei poista kampanjaa tai brändiä, vapauta puhelinnumeroa, peruuta numeron palvelua eikä lopeta kampanjan toistuvaa laskutusta.

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

Vastaus ja tarkistus

Tämä kuvitteellinen esimerkki havainnollistaa tavallista API-vastauskehystä ja valittuja tuloskenttiä. Palautettu numero säilyttää tilillesi tallennetun muodon. brandId ja campaignId ovat tyhjiä merkkijonoja onnistuneen poiston jälkeen.

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

providerStatus on viestikumppanin HTTP-tila. Käsittelijä hyväksyy 2xx-siirtovastauksen ja päivittää sen jälkeen paikallisen numerotietueen; se ei tulkitse kumppanin vastauksen sisältöä erillisen liiketoimintatason hyväksyntätuloksen saamiseksi. Onnistumisvastaus ei siksi ole todiste siitä, että viestirekisteröinti on valmis tai että toimitus onnistuu. Tarkista numeron kampanjatila portaalissa ennen tuotantoliikenteen lähettämistä.

Älä pidä pelkkää paikallista liitosta toimitushyväksyntänä. Kampanjan ja brändin hyväksyntä, numeron provisiointi, tilin käyttöoikeudet, sisältösäännöt ja tavalliset viestirajoitukset ovat edelleen voimassa.

Virheet ja osittaiset tulokset

401: käsittelijällä ei ole käytettävissä todennettua tiliä.
400: action tai number puuttuu tai on virheellinen, tai add-pyynnöllä ei ole kampanjatunnistetta.
404: numero ei ole omistettu, aktiivinen, mitätöimätön SMS-numero.
409: kampanja ei ole tilin käytettävissä, sen tila ei ole ACTIVE, se on nimenomaisesti sandbox-kampanja, tai sen brändi ei ole tilin käytettävissä.
503: viesti-integraatio ei ole käytettävissä. Ota yhteyttä tukeen sen sijaan, että muuttaisit tilin tunnistetietoja tai keksisit määritysarvoja.
502: viestipyyntö epäonnistui, aikakatkaistiin tai palautti muun kuin 2xx-luokan HTTP-tilan. providerStatus voidaan palauttaa. Aikakatkaisu ei todista, ettei kumppani tehnyt muutosta.
500 ja partial=true: viestikumppani palautti onnistuneen HTTP-tilan, mutta paikallista liitosta ei voitu vahvistaa. Täsmäytä numero portaalissa tai ota yhteyttä tukeen ennen uudelleenyritystä.

Tarkista API:n tilakoodi ja vastauksen sisältö HTTP-tuloksen lisäksi. Älä yritä aikakatkaisua tai osittaista tulosta sokeasti uudelleen. Tällä käsittelijällä ei ole pyyntötason idempotenssiavainta, transaktionaalista peruutusta eikä kampanjarekisteröinnin valmistumistarkistusta. Toistettu, vastaava paikallinen määritys voi palauttaa onnistumisen, vaikka tietokanta ilmoittaisi, ettei rivejä muutettu.

Laajuus ja vaikutukset

Tämä toiminto muuttaa lähetysnumeron reititystä ja sen tallennettua kampanja-/brändiliitosta. Tarkistetussa käsittelijässä se ei sisällä suoraa tiliveloitusta, kampanjan luontia, ostoa eikä viestin lähetystä. Tämä ei ole hintatarjous eikä lupaus ilmaisesta palvelusta: olemassa olevat numero-, kampanja- ja viestimaksut jatkuvat tilisi ehtojen mukaisesti.

Portaalissa toiseen kampanjaan vaihtaminen poistaa ensin aiemman liitoksen ja lisää sitten uuden. Ne ovat erillisiä pyyntöjä. Jos toinen pyyntö epäonnistuu, aiempi liitos on voitu jo poistaa. Älä oleta, että nämä kaksi pyyntöä peruuntuvat yhdessä.