SMS migreren van een andere provider

Gebruik deze gids om productie-SMS van een andere provider naar Bird te verplaatsen. Twee zaken blokkeren een eerste verzending die je huidige provider anders afhandelt, dus die komen vóór de code: de landen waarnaar je verzendt en de afzender van wie je verzendt. Daarna porteer je de verzendaanroep, neem je je opt-outlijst over, richt je afleverrapporten opnieuw in via webhooks en test je tegen gesimuleerde bestemmingen voordat je echt verkeer verplaatst.

De migratiechecklist:

Schakel je bestemmingslanden in
Stel een afzender in
Vertaal de verzendaanroep naar POST /v1/sms/messages
Neem je opt-outlijst over
Schakel afleverrapporten over naar webhooks
Test tegen gesimuleerde bestemmingen vóór de cutover

Stappen 3, 4 en 5 hangen af van welke provider je verlaat. Je providergids bevat de veld-voor-veld payloadvertaling, de status- en eventvertaling en waar je je opt-outlijst kunt exporteren.

Begin met stappen 1 en 2. Afzenderregistratie is het langste traject in een SMS-migratie: carrier- en registerbeoordeling kan langer duren dan de codewijziging. Breng beide in kaart voordat je een cutoverdatum vaststelt.

1. Schakel je bestemmingslanden in

Je werkruimte heeft een standaard-weiger bestemmingslijst die begint met alleen het thuisland van je organisatie ingeschakeld. Een verzending naar een ander land retourneert 422 SMSDestinationNotEnabled voordat Bird een afzender bepaalt, dus een integratie die je nauwkeurig hebt geporteerd faalt alsnog bij het eerste internationale bericht totdat je het land openstelt.

Schakel elk land waarnaar je verzendt in onder SMS > Destinations. Haal de lijst uit de berichtlogboeken van je huidige provider in plaats van uit je geheugen: een land dat je vergeet is een stille leemte op de cutoverdag, en een land dat je inschakelt maar nooit gebruikt is blootstelling die je niet nodig hebt. Standaard weigeren beperkt ook de schade van SMS-pumping, waarbij frauduleus verkeer naar premiumreeksen aan jou wordt doorberekend.

2. Stel een afzender in

Bij een vrije-tekstverzending is from de afzender die je ontvanger ziet, en die heeft een van drie vormen: een alfanumeriek afzender-ID, een telefoonnummer in E.164 dat je werkruimte bezit, of een shortcode. Welke vormen werken hangt af van het bestemmingsland, en een afzender die daar niet geldig is wordt geweigerd met een 422 die de reden noemt. SMS verzenden bevat de regels per vorm.

Hoe je elk type krijgt:

Alfanumerieke afzender-ID's maak je zelf aan onder SMS > Senders. Als het bestemmingsland vereist dat het afzender-ID geregistreerd is, dien je de registratie daar in en wacht je op goedkeuring voordat je verkeer ernaartoe routeert.
Amerikaans zakelijk verkeer via lokale long codes vereist de toepasselijke 10DLC-merk- en campagneregistratie, ingesteld onder SMS > 10DLC, terwijl gratisnummers en dedicated shortcodes hun eigen verificatie- of aanvraagprocedures hebben. De VS accepteert helemaal geen alfanumerieke afzender-ID's, dus een Europees afzender-ID dat overal elders werkt heeft geen Amerikaans equivalent.
Nummers doorlopen de Numbers-workflow, waarbij beschikbaarheid en eventuele managed provisioning afhangen van het type en de bestemming. Bekijk SMS numbers voor het juiste pad; het toevoegen van een alfanumerieke afzender levert geen nummer op.
Je huidige nummers behouden is geen selfservice: Bird heeft geen port-in-flow die je vanuit het dashboard kunt starten. Als je abonnees reageren op nummers die je nu bezit, bespreek de portering met support voordat je een cutoverdatum plant, en houd er rekening mee dat de portering en de codewijziging aparte gebeurtenissen zijn.

Een system-template-verzending gebruikt een ander aanvraagformaat. De toepasselijke bestemming en ontvangerstoestemming zijn nog steeds vereist. Het levert de body, de categorie en de afzender, dus from wordt er niet naast geaccepteerd en Bird kiest een afzender die geldig is voor de bestemming.

3. Vertaal de verzendaanroep

Het single-send-endpoint is POST /v1/sms/messages. Bouw een JSON-payload met to, from, text en category, en een succesvolle aanroep retourneert 202 Accepted met een sms_-prefixed bericht-ID. Aflevering vindt plaats na het antwoord en bereikt je via webhookevents en de read-endpoints. De volledige payload staat in SMS verzenden; de veld-voor-veld vertaling van je huidige payload staat in je providergids.

Houd rekening met deze verschillen voordat je code porteert:

Eén ontvanger per request. Bird heeft geen recipients-array. Als je huidige provider één aanroep uitspreidt over meerdere nummers, wordt dat één aanroep per ontvanger, of één batch van onafhankelijke berichten in één request.
category is verplicht bij vrije tekst, en het is transactional, marketing, authentication of service. De meeste providers leiden de intentie af van de campagne of de afzender; hier declareer je het per bericht, en als het bestemmingsland vereist dat de afzender geregistreerd is, is die registratie goedgekeurd voor een categorie en wordt een verzending buiten die categorie geweigerd met 422 SenderCategoryNotPermitted. Let op: de active-status van de afzender kan je dit niet vooraf vertellen, omdat die wordt gerapporteerd zonder verwijzing naar een categorie; lees in plaats daarvan de per-land-vereisten. Zorg dat het klopt bij het porten in plaats van alles op één waarde te zetten.
De body is begrensd op segmenten, en Bird kapt niet af. Een langere body wordt geweigerd met een 422. Niet-GSM-7-tekens halveren ruimschoots wat in een segment past, dus als je huidige provider stilzwijgend slimme aanhalingstekens en streepjes translitereerde, stel dan options.smart_encoding in om de segmentaantallen te behouden die je gewend bent. Het staat standaard uit omdat het de body wijzigt die je hebt opgesteld.
Gebruik tags voor filterdimensies en metadata voor context. Tags zijn {name, value}-paren waarop je analytics kunt filteren en segmenteren; metadata is willekeurige JSON die Bird opslaat, retourneert bij reads en meestuurt bij elk webhookevent. Een enkel client-referentieveld bij je oude provider wordt doorgaans metadata.
Scheduling van individuele verzendingen en uitgaande MMS vragen een apart plan. scheduled_at, media_urls, validity_period en per-ontvanger personalization zijn gereserveerde velden en worden geweigerd met 422 SMSUnsupportedFeature. Die onderdelen van je integratie verhuizen niet met de rest: houd geplande verzendingen in je eigen wachtrij en roep het send-endpoint aan op het beoogde verzendmoment. Evalueer Broadcasts apart voor doelgroepcampagnes; een broadcast is geen hernoeming van een endpointveld.
Gebruik Idempotency-Key voor begrensde retries. Stuur een unieke sleutel per logisch bericht en hergebruik die voor retries van hetzelfde request binnen het replayvenster van drie uur. Replays verminderen dubbele requests, maar zijn geen exact-once aflevergarantie. Zie Idempotency.

4. Neem je opt-outlijst over

Importeer je opt-outs vóór de eerste productieverzending. Iemand een bericht sturen die je oude provider heeft gevraagd te stoppen is de compliancefout die een migratie slecht afsluit, en noch de carrier noch de toezichthouder geeft erom welke leverancier het record kwijtraakte.

Een Bird-onderdrukking dekt een afzender-abonneepaar, wat smaller kan zijn dan de service-, profiel- of accountblokkering van je oude provider. Bewaar de daadwerkelijke intrekking van de persoon over elke relevante afzender en elk programma. Voeg elk paar toe met POST /v1/sms/suppressions:

Codevoorbeeld

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

Dezelfde import werkt vanuit de CLI als bird sms suppressions add --destination +15550001234 --originator +15557654321.

Twee dingen om te weten over de import:

Beide kanten zijn vereist voor afzenderspecifieke onderdrukkingen. Een werkruimtebrede opt-out hoort bij de aparte preference owner. De aanroep is idempotent: 201 registreert een nieuwe onderdrukking, 200 retourneert de handmatige die al bestaat, dus het opnieuw uitvoeren van een gedeeltelijke import is veilig.
Geïmporteerde paren krijgen reason: manual, wat elke categorie blokkeert inclusief transactioneel. Dat is strenger dan een onderdrukking die Bird zelf registreert op basis van een stopwoord. Als een abonnee zich alleen voor marketing heeft afgemeld, beslis bewust of je dat paar importeert.

Controleer het bestaande trefwoord- en voorkeurgedrag voordat je code met pensioen stuurt. Bird beantwoordt ondersteunde trefwoorden en registreert onderdrukkingen waar de landencatalogus van toepassing is. Behoud afhandeling voor niet-ondersteunde verzoeken, bredere voorkeuren en andere contactkanalen. Aangepaste campagnetrefwoorden en antwoorden gebruiken Keyword rules. Zie Opt-outs and keywords voor dekking en reikwijdte.

5. Schakel afleverrapporten over naar webhooks

Registreer één endpoint met POST /v1/webhooks en abonneer het op een expliciete lijst van eventtypen. Dit is de structurele wijziging die de meeste providers vereisen: in plaats van een callback-URL per bericht of per nummer heeft je werkruimte endpoints, en elk endpoint abonneert zich op de events die het wil ontvangen.

De eventnamen van Bird volgen resource.action. Het succespad is sms.accepted, dan sms.sent, dan sms.delivered, met sms.undelivered, sms.failed, sms.expired en sms.rejected voor de rest, en sms.received voor antwoorden op je nummers. De vertaling van de statuswoordenschat van je huidige provider staat in je providergids, en de per-event payloads staan in SMS events.

Correlatie porteert naadloos. Elk event bevat sms_id, workspace_id, to en from, en echoot de tags en metadata van de verzending, zodat je handler je eigen identifiers rechtstreeks van het event afleest in plaats van het bericht op te zoeken.

Twee mechanismen om mee te porten naar de handler:

Afleveringen worden ondertekend volgens Standard Webhooks, met de webhook-id-, webhook-timestamp- en webhook-signature-headers en een HMAC-SHA256 over {id}.{timestamp}.{raw body}. Providers die met een eigen schema ondertekenen vereisen dat je de verificatie vervangt; het recept staat in Webhooks & events.
Aflevering is at-least-once en ongeordend. Dedupliceer op webhook-id en sorteer op de payload timestamp, nooit op aankomstvolgorde.

Inkomende berichten volgen hetzelfde model. Abonneer je op sms.received één keer voor de werkruimte in plaats van een inkomende URL per nummer in te stellen, en onthoud dat Bird nog steeds sms.received verstuurt voor een antwoord dat overeenkwam met een stoptrefwoord, na het registreren van de onderdrukking.

6. Test tegen gesimuleerde bestemmingen

Bird simuleert afleverresultaten voor een set testbestemmingen, zodat je je geporteerde verzendpad en je webhookhandler kunt testen tegen echte API-responses en echt ondertekende afleveringen zonder een toestel. Dit zijn dezelfde nummers die verschillende providers gebruiken voor testcredentials, en een bericht naar een van deze nummers bereikt nooit een carrier.

Bestemming	Wat je integratie ziet
+15005550001	Geweigerd bij verzending met invalid_destination
+15005550002	sms.sent, dan sms.undelivered met unreachable
+15005550003	sms.sent, dan sms.failed met provider_unavailable
+15005550004	sms.sent, dan sms.failed met blocked_by_carrier
+15005550006	sms.sent, dan sms.delivered
+15005550009	sms.sent, dan sms.failed met recipient_opted_out

Er gelden drie voorwaarden, en de eerste twee verrassen mensen bij een nieuwe werkruimte:

Dit zijn Amerikaanse nummers, dus de Verenigde Staten moeten ingeschakeld zijn onder Destinations, en from moet een afzender zijn die geldig is voor de VS. Een alfanumeriek afzender-ID wordt daar geweigerd.
Een gesimuleerde verzending wordt gefactureerd tegen het normale tarief van de bestemming. Er bereikt niets een toestel, maar de walletkosten zijn echt, dus pas de omvang van je smoketest daarop aan.
Het resultaat wordt bepaald door de bestemming alleen. Er is geen apart testcredential en geen testmodus om uit te schakelen.

Een werkbare smoketest verzendt naar +15005550006 en controleert of je handler sms.accepted naar sms.sent naar sms.delivered doorloopt; verzendt naar +15005550002 en +15005550009 en controleert of je fout- en opt-outafhandeling afgaat op de juiste error-code; en verzendt één echt bericht naar een toestel dat je beheert om te bevestigen dat de afzender en de body worden weergegeven zoals je verwacht.

Schakel daarna over per verkeersaandeel in plaats van in één keer. Verplaats een klein percentage productieverzendingen naar Bird, bekijk het SMS-logboek en de metrics op afleverpercentages en foutcodes vergeleken met wat je oude provider rapporteerde voor dezelfde routes, en verhoog het aandeel naarmate de cijfers standhouden. Houd de oude integratie uitrolbaar totdat de eerste volledige factureringsperiode er goed uitziet.

Migreren van een specifieke provider

Twilio: form-encoded PascalCase naar JSON, Messaging Services naar afzenders, StatusCallback naar geabonneerde webhooks
Plivo: src en dst naar from en to, Powerpacks naar afzenders, DND-paren naar onderdrukkingen
Telnyx: de meest vergelijkbare verzending met die van Bird, messaging profiles opgesplitst in afzenders en abonnementen, profielbrede opt-outs naar paren
Bandwidth: twee hosts naar één, applicationId-callbacks naar werkruimtewebhooks, en een opt-outlijst die je eigen applicatie al beheert
Sinch: batches naar enkele verzendingen, body naar text, groepslidmaatschap herbouwd als onderdrukkingen
Infobip: een drielaagse payload platgeslagen, een per-account basis-URL naar een regionale host, een Blocklist uitgebreid naar paren
Bird Connectivity Platform: de rest.messagebird.com API, originator en recipients naar from en to, reportUrl GET-callbacks naar ondertekende webhooks

Volgende stappen

SMS-providers vergelijken: evalueer de productworkflow en migratieoverwegingen
SMS verzenden: de volledige verzendpayload, afzenders, segmenten en het asynchrone 202-model
Opt-outs and keywords: wat Bird voor je beantwoordt en hoe je onderdrukkingen beheert
SMS events: de eventwoordenschat en per-event payloads
Webhooks & events: endpointinrichting, handtekeningverificatie, retries en replay

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptChoose a sender for your markets Gebruik de toolCheck your message segments