Sign inGet Started

Verstuur je eerste SMS

Verstuur een tekstbericht naar je eigen telefoon met Bird SMS en lees het bericht daarna terug om te zien of het bezorgd is. Deze quickstart gebruikt een ingebouwd sjabloon dat de tekst, de categorie en een gedeelde afzender levert die Bird selecteert voor de bestemming. Je hebt er geen afzender-ID of afzenderregistratie voor nodig.

Controleer voordat je begint of de wallet van je organisatie saldo heeft. SMS-verzendingen worden van de wallet afgeschreven, en Bird weigert een verzending die het saldo niet kan dekken met 402 WalletInsufficientBalance. Betaalmethoden en wallet beschrijft hoe je saldo opwaardeert.

Als je nog geen account hebt, maakt self-serve signup er een aan vanuit een terminal met de CLI of curl, zonder browser. Als je code de MessageBird API op rest.messagebird.com aanroept, staan die API en de bijbehorende toegangssleutels los van de API in deze quickstart. Overstappen van MessageBird legt uit hoe de accounts zich tot elkaar verhouden, en SMS migreren van Bird Connectivity Platform koppelt elk veld van de oude verzendaanroep.

1. Maak een API-sleutel aan

Ga in het dashboard naar Platform tools > API keys en maak een sleutel aan met het sms:write-bereik, dat verzenden en lezen van berichten omvat. Een sleutel met alleen dat bereik kan geen SMS-bestemmingslanden inschakelen, geen dagelijkse SMS-bestedingslimieten wijzigen en geen saldo toevoegen: Agent controls beschrijft wat een verzendsleutel begrenst. Sleutels zijn gekoppeld aan een regio en zien eruit als bk_us1_... of bk_eu1_.... De regio in het voorvoegsel geeft aan welke API-host je moet aanroepen: https://us1.platform.bird.com of https://eu1.platform.bird.com.

De API-sleutelpagina in het Bird-dashboard, met sleutels en hun gemaskeerde voorvoegsel, bereiken en laatste gebruikstijd

Vanuit een terminal geeft bird api-keys create in de Bird CLI dezelfde sleutel uit. Voor het uitgeven van een sleutel is het api_keys:write-bereik nodig, en een CLI-login kan op een sleutel alleen de bereiken zetten die hij zelf heeft. Deze login vraagt ook om sms_management:write, dat je in stap 2 nodig hebt. Als je het account vanuit een terminal met bird auth create-org hebt aangemaakt, sla je de loginregel over: de inloggegevens die bij het aanmelden zijn opgeslagen hebben deze bereiken al, en een nieuwe login vervangt ze door beperktere.

Codevoorbeeld
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:write

De volledige sleutel wordt eenmalig getoond, op het moment van aanmaken. Kopieer hem naar een veilige plek en exporteer hem voor de cURL-voorbeelden:

Codevoorbeeld
export BIRD_API_KEY="bk_us1_..."

Zolang BIRD_API_KEY is ingesteld, gebruikt de CLI de sleutel in plaats van je login. Deze sleutel kan geen SMS-bestemmingen wijzigen, dus voer het CLI-commando in stap 2 uit in een shell waarin de variabele niet is ingesteld.

2. Schakel het bestemmingsland in

Bird verzendt SMS alleen naar de landen die voor je werkruimte zijn ingeschakeld. Een verzending naar een ander land mislukt met 422 SMSDestinationNotEnabled. Schakel het land van je telefoonnummer in onder SMS > Destinations. Als het al als ingeschakeld wordt weergegeven, ga dan verder met stap 3.

Vanuit een terminal brengt de Bird CLI dezelfde wijziging aan. Geef de tweeletterige ISO-code van het land door, bijvoorbeeld US voor de Verenigde Staten. Als je CLI-login geen toegang heeft tot SMS-instellingen, toont het commando het bird auth login-commando dat deze toevoegt:

Codevoorbeeld
bird sms destinations update --destination US=true

Agents die verbonden zijn met de MCP-server gebruiken de sms_destinations_update-tool. De publieke API heeft geen operatie voor bestemmingen. Het kan tot een minuut duren voordat een wijziging van toepassing is op verzendingen.

3. Verstuur het bericht

Verstuur het ingebouwde bird_otp_verification-sjabloon naar je telefoon. Het wordt weergegeven als "493021 is your verification code. Do not share it." met de code-waarde die je meegeeft. Installeer de Bird SDK voor je taal door de SDK-quickstart te volgen.

Vervang in de SDK-tabs de voorbeeld-API-sleutel en vervang +14155550100 door je mobiele nummer in E.164-formaat. De CLI gebruikt je login, of BIRD_API_KEY zolang die variabele is ingesteld, en het cURL-tabblad gebruikt BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

console.log(msg.id, msg.status);

Als je sleutel begint met bk_eu1_, roep dan https://eu1.platform.bird.com aan.

De API antwoordt met 202 Accepted en het bericht. De id begint met sms_ en de status is accepted: Bird heeft het bericht en bezorgt het asynchroon. Bewaar de id voor de volgende stap. Het bericht komt binnen via de gedeelde afzender die Bird voor jouw land heeft geselecteerd.

4. Controleer de bezorgstatus

Haal het bericht op aan de hand van zijn ID. Een leesverzoek direct na het verzenden kan 404 teruggeven totdat het bericht zichtbaar wordt op het leesendpoint, wat kort na de 202 gebeurt. Probeer het even later opnieuw. Vervang SMS_MESSAGE_ID door de id uit stap 3, en de voorbeeld-API-sleutel in de SDK-tabs door je eigen sleutel. De Go-SDK heeft geen getypeerde methode om een SMS-bericht te lezen, dus het Go-tabblad roept het API-pad aan via de client.Get-requestmethode van de SDK.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.get("SMS_MESSAGE_ID");

console.log(msg.id, msg.status);

Het veld status geeft aan waar het bericht zich bevindt:

  • accepted: Bird heeft het bericht en heeft het nog niet aan een carrier overgedragen.
  • sent: de carrier heeft het bericht en sent_at registreert wanneer Bird het heeft overgedragen.
  • delivered: de carrier heeft de aflevering bevestigd, en delivered_at registreert wanneer.
  • undelivered, failed, rejected of expired: het bericht heeft de telefoon niet bereikt. last_error geeft de reden, en Afleverfouten licht elke fout toe.

Poll totdat de status accepted en sent verlaat, of abonneer je op de SMS-events om elke wijziging per webhook te ontvangen. Elk bericht verschijnt ook op de Messages-pagina met zijn eventtijdlijn.

Een mislukte verzending oplossen

  • 422 SMSDestinationNotEnabled: het land van de ontvanger is niet ingeschakeld voor je werkruimte. Schakel het in zoals in stap 2, wacht maximaal een minuut en verstuur opnieuw.
  • 402 WalletInsufficientBalance: de wallet kan het bericht niet dekken. Vul de wallet aan en verstuur opnieuw.
  • 403 InsufficientScope: de API-sleutel mist het sms-bereik. Bewerk de bereiken van de sleutel of maak een sleutel aan met sms:write.

Volgende stappen

  • SMS versturen: verstuur je eigen tekst met een afzender en categorie, in batches en met veilige nieuwe pogingen.
  • SMS-afzender-ID's: kies een afzender per land en registreer deze waar het land dat vereist.
  • SMS-sjablonen: de ingebouwde sjablooncatalogus en de bijbehorende variabelen.
  • SMS-events: de eventtypen en webhookaflevering voor elke statuswijziging.
  • SMS API-referentie: het volledige request- en responseschema.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.