Přiřazení čísla ke kampani pro zasílání zpráv

Přiřazení odesílacího čísla ke kampani

Tuto operaci použijte poté, co je vaše značka pro zasílání zpráv a produkční kampaň zaregistrována a kampaň je aktivní. Operace přiřadí jedno číslo s podporou SMS na vašem účtu ke kampani. Nevytváří značku, nevytváří ani neschvaluje kampaň, nekupuje číslo a neodesílá zprávu.

Aktuální portál používá tuto cestu při přiřazování kampaně k číslu. Veřejné API přijímá identifikátor kampaně; značku odvozuje z kampaně vlastněné účtem, místo aby přijímalo samostatný identifikátor značky.

Požadavek

Odešlete požadavek POST kódovaný jako formulář přes HTTPS pomocí svého povoleného účtu API a jeho povolené zdrojové IP adresy. Použijte skutečné identifikátory čísla a kampaně ze svého účtu. Číslo v tomto příkladu je smyšlené.

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'

Parametry přiřazení kampaně
Parametr	Povinný	Význam
action	Ano	Použijte add pro přiřazení nebo delete pro odebrání aktuálního přiřazení kampaně k číslu. Velikost písmen a okolní mezery jsou normalizovány.
campaign	Pro add	Hodnota campaignId kampaně ve stavu ACTIVE vlastněné autentizovaným účtem. Její značka musí rovněž patřit účtu. Kampaň výslovně označenou jako sandbox nelze přiřadit k živým odesílacím číslům. Pro delete tento parametr vynechejte; odebrání použije stávající přiřazení čísla.
number	Ano	Vlastněné, aktivní, nezneplatněné odesílací číslo s podporou SMS. U severoamerického čísla použijte kód země 1 následovaný jeho deseti číslicemi, bez znaménka plus. Obslužná rutina odstraní nečíselné znaky a vyhledá také ekvivalenty s předponou plus a desetimístné ekvivalenty. Tato normalizace není obecnou kontrolou platnosti telefonního čísla.

Operace mění jedno číslo. Nemá stránkování, dávkový parametr ani možnost zkušebního spuštění. Nepoužívejte koncový bod pro vytvoření kampaně pouze k připojení čísla k existující kampani.

Odebrání aktuálního přiřazení

Použijte action=delete s vlastněným číslem. Tím se odebere přiřazení odesílací kampaně k číslu a vymažou se uložená pole značky/kampaně pro toto číslo. Nesmaže se kampaň ani značka, neuvolní se telefonní číslo, nezruší se služba čísla a nezastaví se opakovaná fakturace kampaně.

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

Odpověď a ověření

Tento smyšlený příklad znázorňuje běžnou obálku odpovědi API a vybraná pole výsledku. Vrácené číslo zachovává formát uložený ve vašem účtu. Po úspěšném odebrání jsou brandId a campaignId prázdné řetězce.

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

providerStatus je stav HTTP partnera pro zasílání zpráv. Obslužná rutina přijme transportní odpověď 2xx a poté aktualizuje místní záznam čísla; neinterpretuje tělo odpovědi partnera kvůli samostatnému výsledku obchodního přijetí. Úspěšná odpověď proto není důkazem, že registrace pro zasílání zpráv je dokončena nebo že doručení uspěje. Před odesláním produkčního provozu zkontrolujte stav kampaně daného čísla v portálu.

Nepovažujte samotné místní přiřazení za schválení doručování. Schválení kampaně a značky, zřízení čísla, oprávnění účtu, pravidla pro obsah a běžné limity zasílání zpráv nadále platí.

Chyby a částečné výsledky

401: obslužné rutině není k dispozici žádný autentizovaný účet.
400: action nebo number chybí nebo je neplatné, nebo požadavek add nemá identifikátor kampaně.
404: číslo není vlastněné, aktivní, nezneplatněné číslo SMS.
409: kampaň není účtu dostupná, není ve stavu ACTIVE, je výslovně označena jako sandbox, nebo její značka není účtu dostupná.
503: integrace pro zasílání zpráv není dostupná. Kontaktujte podporu, místo abyste měnili přihlašovací údaje účtu nebo vymýšleli konfigurační hodnoty.
502: požadavek na zasílání zpráv selhal, vypršel jeho časový limit nebo vrátil stav HTTP jiný než 2xx. Může být vrácen providerStatus. Vypršení časového limitu nedokazuje, že partner neprovedl žádnou změnu.
500 s partial=true: partner pro zasílání zpráv vrátil úspěšný stav HTTP, ale místní přiřazení se nepodařilo potvrdit. Před opakováním pokusu srovnejte stav čísla v portálu nebo kontaktujte podporu.

Kromě výsledku HTTP zkontrolujte také stavový kód API a tělo odpovědi. Neopakujte slepě požadavek po vypršení časového limitu ani po částečném výsledku. Tato obslužná rutina nemá klíč idempotence na úrovni požadavku, transakční vrácení změn ani kontrolu dokončení registrace kampaně. Opakované shodné místní přiřazení může vrátit úspěch, i když databáze nehlásí žádné změněné řádky.

Rozsah a účinky

Tato operace mění směrování odesílacího čísla a jeho uložené přiřazení kampaně/značky. V kontrolované obslužné rutině neobsahuje žádné přímé stržení částky z účtu, vytvoření kampaně, nákup ani odeslání zprávy. Nejde o cenovou nabídku ani příslib bezplatné služby: stávající poplatky za číslo, kampaň a zasílání zpráv pokračují podle podmínek vašeho účtu.

V portálu změna na jinou kampaň nejprve odebere předchozí přiřazení a poté přidá nové. Jde o samostatné požadavky. Pokud druhý požadavek selže, dřívější přiřazení již může být odebráno. Nepředpokládejte, že se oba požadavky vrátí zpět společně.