Een nummer aan een berichtencampagne toewijzen

Een verzendnummer aan een campagne toewijzen

Gebruik deze bewerking nadat uw berichtenmerk en productiecampagne zijn geregistreerd en de campagne actief is. Ze koppelt één SMS-geschikt nummer van uw account aan de campagne. Ze maakt geen merk aan, maakt of keurt geen campagne goed, koopt geen nummer en verzendt geen bericht.

De huidige portal gebruikt deze route bij het toewijzen van een campagne aan een nummer. De publieke API accepteert een campagne-identificatie; ze leidt het merk af uit de campagne die eigendom is van het account, in plaats van een afzonderlijke merkidentificatie te accepteren.

Verzoek

Verstuur een form-encoded POST via HTTPS met uw ingeschakelde API-account en het daarvoor toegestane bron-IP-adres. Gebruik de werkelijke nummer- en campagne-identificaties uit uw account. Het nummer in dit voorbeeld is fictief.

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'

De bewerking wijzigt één nummer. Ze heeft geen paginering, batchparameter of dry-run-optie. Gebruik geen eindpunt voor het aanmaken van campagnes enkel om een nummer aan een bestaande campagne te koppelen.

De huidige koppeling verwijderen

Gebruik action=delete met het eigen nummer. Dit verwijdert de verzendcampagnekoppeling van het nummer en wist de opgeslagen merk-/campagnevelden voor dat nummer. Het verwijdert de campagne of het merk niet, geeft het telefoonnummer niet vrij, zegt de dienst van het nummer niet op en stopt de terugkerende facturering van de campagne niet.

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

Antwoord en verificatie

Dit fictieve voorbeeld illustreert de gebruikelijke API-antwoordenvelop en een selectie van resultaatvelden. Het geretourneerde nummer behoudt de indeling die in uw account is opgeslagen. brandId en campaignId zijn lege tekenreeksen na een geslaagde verwijdering.

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

providerStatus is de HTTP-status van de berichtenpartner. De handler accepteert een 2xx-transportantwoord en werkt vervolgens het lokale nummerrecord bij; hij interpreteert de antwoordtekst van de partner niet voor een afzonderlijk acceptatieresultaat op bedrijfsniveau. Een succesantwoord is daarom geen bewijs dat de berichtenregistratie voltooid is of dat de bezorging zal slagen. Controleer de campagnestatus van het nummer in de portal voordat u productieverkeer verstuurt.

Beschouw een lokale koppeling op zichzelf niet als goedkeuring voor bezorging. Goedkeuring van campagne en merk, nummerprovisionering, accountrechten, inhoudsregels en de gebruikelijke berichtenlimieten blijven van toepassing.

Fouten en gedeeltelijke resultaten

• 401: er is geen geauthenticeerd account beschikbaar voor de handler.
• 400: action of number ontbreekt of is ongeldig, of een add-verzoek heeft geen campagne-identificatie.
• 404: het nummer is geen eigen, actief, niet-vervallen SMS-nummer.
• 409: de campagne is niet beschikbaar voor het account, is niet ACTIVE, is expliciet sandbox, of het merk ervan is niet beschikbaar voor het account.
• 503: de berichtenintegratie is niet beschikbaar. Neem contact op met de ondersteuning in plaats van accountgegevens te wijzigen of configuratiewaarden te verzinnen.
• 502: het berichtenverzoek is mislukt, heeft een time-out gekregen of heeft een HTTP-status geretourneerd die niet 2xx is. providerStatus kan worden geretourneerd. Een time-out bewijst niet dat de partner geen wijziging heeft aangebracht.
• 500 met partial=true: de berichtenpartner heeft een geslaagde HTTP-status geretourneerd, maar de lokale koppeling kon niet worden bevestigd. Stem het nummer af in de portal of neem contact op met de ondersteuning voordat u het opnieuw probeert.

Controleer naast het HTTP-resultaat ook de API-statuscode en de antwoordtekst. Probeer een time-out of een gedeeltelijk resultaat niet blindelings opnieuw. Deze handler heeft geen idempotentiesleutel op verzoekniveau, geen transactionele rollback en geen controle op voltooiing van de campagneregistratie. Een herhaalde, overeenkomende lokale toewijzing kan succes retourneren, zelfs wanneer de database geen gewijzigde rijen meldt.

Reikwijdte en effecten

Deze bewerking wijzigt de routering van het verzendnummer en de opgeslagen campagne-/merkkoppeling ervan. Ze bevat in de beoordeelde handler geen directe accountafschrijving, campagneaanmaak, aankoop of berichtverzending. Dit is geen prijsopgave en geen belofte van gratis dienstverlening: bestaande kosten voor nummer, campagne en berichten blijven gelden onder uw accountvoorwaarden.

In de portal wordt bij het overstappen naar een andere campagne eerst de vorige koppeling verwijderd en daarna de nieuwe toegevoegd. Dat zijn afzonderlijke verzoeken. Als het tweede verzoek mislukt, is de eerdere koppeling mogelijk al verwijderd. Ga er niet van uit dat de twee verzoeken samen worden teruggedraaid.