Batch sending

Endpoint /messages vám umožňuje sbalit až 10 objektů zpráv, každý s až 10 příjemci, do jednoho API volání — to je až 100 doručení příjemcům na požadavek. Je to nejefektivnější způsob, jak spustit kampaň, odeslat dávku transakčních oznámení nebo kombinovat SMS a Viber odeslání v jednom kole.

Kdy použít hromadné odesílání

Kampaně — odesílejte propagační obsah seznamu odběratelů v co nejmenším počtu API volání.
Skupinová oznámení — informujte tým, třídu nebo zákaznický segment jediným požadavkem.
Odeslání smíšených kanálů — odesílejte SMS jedným příjemcům a Viber jiným, vše v jednom volání.
Personalizované zprávy — dejte každému objektu zprávy vlastní body nebo flow pro přizpůsobení na příjemce, bez API volání na osobu.

Jak hromadné odesílání funguje

Místo odeslání jednoho objektu zprávy na POST /message odešlete pole objektů zpráv na POST /messages. Každý prvek pole je nezávislá zpráva s vlastním body, to, flow, tag, callback a payload.

Tělo požadavku

[
  {
    "body": "Ahoj Alice!",
    "to": [
      {"phone_number": "420777123456"},
      {"phone_number": "420777654321"}
    ]
  },
  {
    "body": "Ahoj Bobe!",
    "to": [
      {"phone_number": "420777111111"}
    ]
  }
]

cURL

curl -X POST https://api.smsmngr.com/v2/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "body": "Ahoj Alice!",
      "to": [
        {"phone_number": "420777123456"},
        {"phone_number": "420777654321"}
      ]
    },
    {
      "body": "Ahoj Bobe!",
      "to": [{"phone_number": "420777111111"}]
    }
  ]'

Formát odpovědi

Odpověď obsahuje request_id na nejvyšší úrovni a dvě pole — accepted (zprávy zařazené k doručení) a rejected (zprávy, které selhaly při validaci). Každý přijatý záznam obsahuje key (index objektu zprávy v poli) a message_id pro sledování.

Odpověď

{
  "request_id": "bc36f3d1-d284-463a-921b-a3560c154649",
  "accepted": [
    {
      "key": 0,
      "message_id": "e27ff0ac-87b5-4e1d-b644-5fc6029e2a11"
    },
    {
      "key": 1,
      "message_id": "f39ab1bd-98c6-4f2e-c755-6gd7130f3b22"
    }
  ],
  "rejected": []
}

Pokud objekty zpráv seleží při validaci (například chybný formát telefonního čísla), objeví se v rejected s key odpovídajícím jejich pozici v poli a popisem chyby. Platné objekty zpráv ve stejném požadavku jsou i tak přijaty a zařazeny.

Získání message ID pro jednotlivé příjemce

Když objekt zprávy má více příjemců, každý příjemce dostane vlastní message_id odvozené z dávkového message_id pomocí přípony indexu od nuly: -0, -1, -2 atd. Například, pokud je přijaté message_id e27ff0ac-87b5-4e1d-b644-5fc6029e2a11 a zpráva má dva příjemce:

Příjemce	message_id
První (`420777123456`)	`e27ff0ac-87b5-4e1d-b644-5fc6029e2a11-0`
Druhý (`420777654321`)	`e27ff0ac-87b5-4e1d-b644-5fc6029e2a11-1`

Doručovací webhooky obsahují tato ID s příponou, takže můžete korelovat každou událost doručení zpět na konkrétního příjemce.

Smíšené kanály v dávce

Každý objekt zprávy v poli má vlastní nezávislé flow. To znamená, že můžete odeslat SMS jedné skupině a Viber zprávu (s SMS zálohou) jiné skupině ve stejném API volání.

Dávka smíšených kanálů

[
  {
    "body": "Flash sleva končí dnes! Navštivte example.com/sale",
    "to": [
      {"phone_number": "420777123456"},
      {"phone_number": "420777654321"}
    ],
    "tag": "promotional",
    "flow": [
      {
        "sms": {
          "sender": "MujObchod",
          "gateway": "high"
        }
      }
    ]
  },
  {
    "body": "Flash sleva končí dnes! Navštivte example.com/sale",
    "to": [
      {"phone_number": "420777111111"},
      {"phone_number": "420777222222"}
    ],
    "tag": "promotional",
    "flow": [
      {
        "viber": {
          "sender": "MujSender",
          "body": "Flash sleva končí dnes!",
          "buttons": [
            {
              "title": "Nakupovat teď",
              "url": "https://example.com/sale"
            }
          ],
          "ttl": 60
        }
      },
      {
        "sms": {
          "sender": "MujObchod",
          "gateway": "high"
        }
      }
    ]
  }
]

Limity

Dimenze	Limit
Objektů zpráv na volání `/messages`	10
Příjemců na objekt zprávy	10
Celkem příjemců na volání `/messages`	100

Pokud potřebujete oslovit více než 100 příjemců, rozdělte seznam a odešlete více volání /messages. Není penalizání rate limitu za bezprostřední návaznost dávkových požadavků — stačí dodržovat propustnost vašeho účtu za sekundu.

Kompletní cURL příklad

cURL

curl -X POST https://api.smsmngr.com/v2/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "body": "Vaše schůzka je potvrzena na pondělí v 10:00.",
      "to": [
        {"phone_number": "420777100001"},
        {"phone_number": "420777100002"},
        {"phone_number": "420777100003"}
      ],
      "tag": "transactional",
      "callback": "https://yourapp.com/webhooks/batch",
      "payload": {"campaign": "appointment-reminders"},
      "flow": [
        {
          "sms": {
            "sender": "MojeKlinika",
            "gateway": "high",
            "ttl": 1440
          }
        }
      ]
    },
    {
      "body": "Ahoj! Váš recept je připraven k vyzvednutí.",
      "to": [
        {"phone_number": "420777200001"},
        {"phone_number": "420777200002"}
      ],
      "tag": "transactional",
      "callback": "https://yourapp.com/webhooks/batch",
      "payload": {"campaign": "prescription-ready"},
      "flow": [
        {
          "sms": {
            "sender": "MojeKlinika",
            "gateway": "high"
          }
        }
      ]
    }
  ]'

Další kroky

Webhooky

Přijímejte stav doručení pro každého příjemce ve vaší dávce přes webhooky.

Odeslat Viber

Zjistěte, jak nakonfigurovat Viber flow pro použití v dávkových požadavcích.

Odeslat WhatsApp

Přidejte WhatsApp šablonové zprávy do svých dávek se smíšenými kanály.

Odeslat SMS

Zkontrolujte všechny možnosti SMS flow dostupné v dávkových zprávách.

Odesílání zpráv

Příjem a ověření

Přístup a klíče

Kdy použít hromadné odesílání

Jak hromadné odesílání funguje

Formát odpovědi

Získání message ID pro jednotlivé příjemce

Smíšené kanály v dávce

Limity

Kompletní cURL příklad

Další kroky

Webhooky

Odeslat Viber

Odeslat WhatsApp

Odeslat SMS

​Kdy použít hromadné odesílání

​Jak hromadné odesílání funguje

​Formát odpovědi

​Získání message ID pro jednotlivé příjemce

​Smíšené kanály v dávce

​Limity

​Kompletní cURL příklad

​Další kroky

Webhooky

Odeslat Viber

Odeslat WhatsApp

Odeslat SMS

Kdy použít hromadné odesílání

Jak hromadné odesílání funguje

Formát odpovědi

Získání message ID pro jednotlivé příjemce

Smíšené kanály v dávce

Limity

Kompletní cURL příklad

Další kroky