Rozpocznij

Szybki start: wyślij pierwszą wiadomość SMS przez API

Wyświetl jako Markdown Specyfikacja OpenAPI

Ten przewodnik przeprowadzi Cię od braku konta do dostarczonej wiadomości i podpisanego zdarzenia dostarczenia. Potrzebujesz terminala i pięciu minut.

1. Utwórz konto i doładuj saldo

Otwórz Pobierz klucz API. Twoja przeglądarka generuje klucz konta zaczynający się od acct_; skopiuj go lub zapisz jako plik, a następnie potwierdź. Ten klucz jest Twoim loginem do konsoli. Dodaj środki na stronie Rozliczenia: hostowana kasa otwiera się w konsoli, a saldo jest wyświetlane na górze każdej strony konsoli.

2. Utwórz klucz API

Na stronie kluczy API nadaj kluczowi nazwę (na przykład production lub staging) i utwórz go. Klucz zaczyna się od bsa_live_ i jest wyświetlany tylko raz: skopiuj go do swojego magazynu tajemnic lub zmiennej środowiskowej.

export BULKSMSAPI_KEY="bsa_live_..."

3. Wyślij wiadomość

Wyślij tekst na swój własny telefon. Numery są zapisywane w formacie międzynarodowym z znakiem plus.

curl https://bulksmsapi.cc/v1/messages \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "text": "Your Northwind code is 482913. It expires in 10 minutes.",
    "reference": "login-7781"
  }'

// Node.js 18 or newer (built-in fetch)
const res = await fetch("https://bulksmsapi.cc/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155550123",
    text: "Your Northwind code is 482913. It expires in 10 minutes.",
    reference: "login-7781",
  }),
});
const message = await res.json();
console.log(res.status, message.id, message.status, message.price);

# Python 3, standard library only
import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/messages",
    data=json.dumps({
        "to": "+14155550123",
        "text": "Your Northwind code is 482913. It expires in 10 minutes.",
        "reference": "login-7781",
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
        "Content-Type": "application/json",
        "User-Agent": "northwind-app/1.0",
    },
    method="POST",
)
with urllib.request.urlopen(req) as res:
    message = json.load(res)
print(res.status, message["id"], message["status"], message["price"])

<?php
// PHP 7.4 or newer with the curl extension
$ch = curl_init("https://bulksmsapi.cc/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => "+14155550123",
        "text" => "Your Northwind code is 482913. It expires in 10 minutes.",
        "reference" => "login-7781",
    ]),
]);
$message = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $message["id"], " ", $message["status"], "\n";

// Go 1.20 or newer, standard library only
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"to":        "+14155550123",
		"text":      "Your Northwind code is 482913. It expires in 10 minutes.",
		"reference": "login-7781",
	})
	req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/messages", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var message map[string]any
	json.NewDecoder(res.Body).Decode(&message)
	fmt.Println(res.StatusCode, message["id"], message["status"], message["price"])
}

Odpowiedź to 202 Accepted z identyfikatorem wiadomości, ceną i statusem queued. W ciągu kilku sekund status zmienia się na sent, a następnie delivered.

4. Sprawdź status

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

const res = await fetch("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", {
  headers: { Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}` },
});
const message = await res.json();
console.log(message.status, message.error);

import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX",
    headers={"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"], "User-Agent": "northwind-app/1.0"},
)
with urllib.request.urlopen(req) as res:
    message = json.load(res)
print(message["status"], message["error"])

<?php
$ch = curl_init("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BULKSMSAPI_KEY")],
]);
$message = json_decode(curl_exec($ch), true);
echo $message["status"], "\n";

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var message map[string]any
	json.NewDecoder(res.Body).Decode(&message)
	fmt.Println(message["status"], message["error"])
}

5. Wyślij partię

Partia wysyła jeden tekst do maksymalnie 10 000 numerów. Duplikaty i numery, których nie można odczytać, są wymienione w set_aside i nie są naliczane.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'

const res = await fetch("https://bulksmsapi.cc/v1/batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "spring-sale-0412",
  },
  body: JSON.stringify({
    name: "Spring sale",
    text: "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    to: ["+14155550123", "+447400123456", "+4915123456789"],
  }),
});
const batch = await res.json();
console.log(res.status, batch.id, batch.recipients, batch.cost);

import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/batches",
    data=json.dumps({
        "name": "Spring sale",
        "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
        "to": ["+14155550123", "+447400123456", "+4915123456789"],
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": "spring-sale-0412",
        "User-Agent": "northwind-app/1.0",
    },
    method="POST",
)
with urllib.request.urlopen(req) as res:
    batch = json.load(res)
print(res.status, batch["id"], batch["recipients"], batch["cost"])

<?php
$ch = curl_init("https://bulksmsapi.cc/v1/batches");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: spring-sale-0412",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Spring sale",
        "text" => "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
        "to" => ["+14155550123", "+447400123456", "+4915123456789"],
    ]),
]);
$batch = json_decode(curl_exec($ch), true);
echo $batch["id"], " ", $batch["recipients"], " ", $batch["cost"], "\n";

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"name": "Spring sale",
		"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
		"to":   []string{"+14155550123", "+447400123456", "+4915123456789"},
	})
	req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/batches", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "spring-sale-0412")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var batch map[string]any
	json.NewDecoder(res.Body).Decode(&batch)
	fmt.Println(res.StatusCode, batch["id"], batch["recipients"], batch["cost"])
}

6. Odbierz zdarzenia dostarczenia

Na stronie Webhooks dodaj punkt końcowy HTTPS. Każda dostarczona lub nieudana wiadomość wywołuje go z podpisanym zdarzeniem JSON; sprawdź podpis za pomocą kodu na stronie Webhooks i odpowiedz z dowolnym statusem 2xx.

Następnie przeczytaj Partie dotyczące spersonalizowanego tekstu dla każdego numeru i planowania, oraz Błędy dotyczące każdego kodu błędu i jego wpływu na Twoje saldo.

PoprzedniePrzegląd API DalejUwierzytelnianie