Hromadné odesílání zpráv — endpoint /messages a nahrání JSONL souboru

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 pro zvýšení propustnosti odesílání. Pokud potřebujete odeslat tisíce až statisíce zpráv, můžete místo mnoha HTTP požadavků nahrát jeden JSONL soubor — viz Hromadné nahrání souboru přes REST API níže.

Dvě cesty hromadného odesílání

	`POST /messages` (JSON API v2)	Nahrání souboru (`POST /messaging/url`, REST API)
Vhodné pro	jednotky až stovky příjemců, transakční a real-time odesílání	tisíce až statisíce zpráv, kampaně
Na jedno volání	10 objektů zpráv × 10 příjemců	jeden soubor, jeden objekt zprávy na řádek
Odpověď	synchronně `accepted` / `rejected` s `message_id`	potvrzení nahrání; výsledek každé zprávy přes webhooky
Plánování	`datetime` u každé zprávy	`datetime` pro celý soubor (a volitelně u každé zprávy); zrušení přes `/messaging/cancel`

Potřebujete odeslat více než 100 příjemců najednou? Použijte hromadné nahrání JSONL souboru přes REST API (POST /messaging/url, viz REST API). Skill smsmanager-bulk-messaging z balíčku SmsManager skills umí soubor vygenerovat, nahrát a naplánovat za vás.

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

Kampaně — odesílejte marketingový 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.
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"}
    ]
  }
]

Tento příklad odešle 3 zprávy (zpráva “Ahoj Alice!” bude doručena na 2 telefonní čísla, zpráva “Ahoj Bobe!” bude doručena na jedno telefonní číslo).

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 (dva požadavky zařazené k doručení) a rejected (požadavky, které selhaly při validaci). Každý přijatý požadavek 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 selžou 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

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, u message_id e27ff0ac-87b5-4e1d-b644-5fc6029e2a11 požadavku, který 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 propojit 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. U tisíců a více zpráv je jednodušší nahrát jeden JSONL soubor — nemusíte řešit tisíce HTTP požadavků, jejich rychlost, opakování ani návratové kódy.

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"
          }
        }
      ]
    }
  ]'

Hromadné nahrání souboru přes REST API

Když odesíláte tisíce až statisíce zpráv, je volání /messages po stovkách příjemců nepraktické: musíte řídit souběžnost a rychlost požadavků, ošetřit návratový kód každého z nich a opakovat neúspěšná volání. REST API endpoint POST /messaging/url vám místo toho vrátí předpodepsanou URL, na kterou nahrajete celý seznam zpráv jako jeden JSONL soubor (JSON Lines — jeden objekt zprávy na řádek) jediným file uploadem. Zpracování zpráv pak probíhá na straně SmsManager.

Endpoint /messaging/url patří do REST API, nikoli do JSON API v2. Základní URL je https://rest-api.smsmngr.com/v1, autentizace je stejná — hlavička x-api-key se stejným API klíčem.

Připravte JSONL soubor

Každý řádek souboru je jeden objekt zprávy ve stejném formátu jako u JSON API v2 — tedy stejný objekt, jaký posíláte na POST /message nebo jako prvek pole na POST /messages. Používejte kódování UTF-8, jeden JSON objekt na řádek, bez obalujícího pole a bez čárek mezi řádky.

messages.jsonl

{"body": "Ahoj Alice! Vaše objednávka je na cestě.", "to": [{"phone_number": "420777123456"}], "tag": "transactional", "callback": "https://yourapp.com/webhooks/bulk"}
{"body": "Ahoj Bobe! Vaše objednávka je na cestě.", "to": [{"phone_number": "420777654321"}], "tag": "transactional", "callback": "https://yourapp.com/webhooks/bulk"}
{"body": "Flash sleva končí dnes! Navštivte example.com/sale", "to": [{"phone_number": "420777111111"}, {"phone_number": "420777222222"}], "tag": "promotional", "flow": [{"sms": {"sender": "MujObchod", "gateway": "high"}}]}

Na každém řádku můžete použít všechna pole objektu zprávy — to s až 10 příjemci, flow se smíšenými kanály, tag, callback, payload, datetime i delivery_time. Pro velké soubory doporučujeme gzip kompresi:

gzip

gzip messages.jsonl   # vytvoří messages.jsonl.gz

Získejte URL pro nahrání

Zavolejte POST /messaging/url s vlastním identifikátorem dávky a typem souboru.

cURL

curl -X POST https://rest-api.smsmngr.com/v1/messaging/url \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bulk_id": "kampan-2026-09-20", "filetype": "jsonl"}'

Odpověď

{
  "success": true,
  "url": "https://smsmngr-bulk-uploads.s3.amazonaws.com/...&X-Amz-Expires=60..."
}

Pole	Povinné	Popis
`bulk_id`	ano	Váš identifikátor hromadného nahrání. Použijte unikátní, popisný řetězec (např. název kampaně a datum) — slouží ke zrušení naplánovaného nahrání.
`filetype`	ano	`jsonl` pro nekomprimovaný soubor, `gz` pro gzipovaný JSONL.
`datetime`	ne	Naplánovaný čas zpracování souboru v UTC (ISO 8601). Bez tohoto pole se soubor zpracuje ihned po nahrání.

Nahrajte soubor

Na vrácenou URL odešlete soubor metodou PUT. Hlavička Content-Type musí odpovídat zvolenému filetype: application/jsonl pro jsonl, application/gzip pro gz.

cURL (JSONL)

curl -X PUT "https://smsmngr-bulk-uploads.s3.amazonaws.com/...&X-Amz-Expires=60..." \
  -H "Content-Type: application/jsonl" \
  --data-binary @messages.jsonl

cURL (gzip)

curl -X PUT "https://smsmngr-bulk-uploads.s3.amazonaws.com/...&X-Amz-Expires=60..." \
  -H "Content-Type: application/gzip" \
  --data-binary @messages.jsonl.gz

Předpodepsaná URL platí jen 60 sekund. Vyžádejte si ji až těsně před nahráním a soubor mějte připravený předem. Nahrávejte metodou PUT s tělem tvořeným přímo obsahem souboru — ne přes POST ani multipart/form-data. Do samotného PUT požadavku neposílejte x-api-key; oprávnění je součástí URL.

Sledujte doručení přes webhooky

Nahraný soubor se zpracovává asynchronně — úspěšný PUT znamená pouze, že soubor byl přijat. Výsledek každé zprávy (přijetí, odeslání, doručení nebo odmítnutí) dostanete jako sentMessage webhook na callback uvedený u zprávy, případně na výchozí callback URL vašeho účtu. Žádný samostatný endpoint pro stav celé dávky neexistuje.Každý příjemce má vlastní message_id; u řádků s více příjemci se message_id odvozuje stejně jako u /messages — příponou indexu -0, -1 atd. Podrobnosti najdete v průvodci Webhooky a v konceptu Přijetí požadavku.

Plánování a zrušení

Pole datetime v těle POST /messaging/url naplánuje zpracování celého souboru na zadaný čas v UTC. Platí stejná pravidla jako pro plánování jednotlivých zpráv.

cURL

curl -X POST https://rest-api.smsmngr.com/v1/messaging/url \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bulk_id": "kampan-2026-09-21", "filetype": "gz", "datetime": "2026-09-21T08:00:00Z"}'

Naplánované nahrání zrušíte voláním POST /messaging/cancel s jeho bulk_id:

cURL

curl -X POST https://rest-api.smsmngr.com/v1/messaging/cancel \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bulk_id": "kampan-2026-09-21"}'

Pole datetime uvnitř jednotlivých řádků souboru se vztahuje k dané zprávě a uplatní se při jejím zpracování. Zpracování souboru samotného řídí jen datetime z požadavku na URL.

Chyby

Kód	Zpráva	Příčina
`400`	`Missing 'bulk_id' or 'filetype' or 'datetime' in request data`	Chybí povinné pole nebo má `datetime` neplatný formát.
`400`	`Unsupported filetype`	`filetype` není `jsonl` ani `gz`.
`500`	`Failed to generate upload URL`	URL se nepodařilo vygenerovat — požadavek zopakujte.

Chyby při samotném PUT (například vypršelá URL nebo neodpovídající Content-Type) vrací úložiště přímo jako HTTP chybu bez těla ve formátu SmsManager. V takovém případě si vyžádejte novou URL a nahrání zopakujte.

U velkých kampaní použijte gzip (filetype: "gz") — výrazně zmenší přenášený objem. Marketingové zprávy nechte ve výchozí frontě promotional (viz Fronty odesílání); prioritní fronta není pro hromadné odesílání určena.

Další kroky

Webhooky

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

REST API reference

Referenční popis endpointů /messaging/url a /messaging/cancel pro hromadné nahrání souborů.

Plánování

Naplánujte odeslání pomocí datetime a omezte doručení na povolené hodiny přes delivery_time.

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í

Testování

AI asistenti

Přístup a klíče

Hromadné odesílání zpráv — endpoint /messages a nahrání JSONL souboru

Dvě cesty hromadného odesílání

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

Hromadné nahrání souboru přes REST API

Plánování a zrušení

Chyby

Další kroky

Webhooky

REST API reference

Plánování

Odeslat Viber

Odeslat WhatsApp

Odeslat SMS

​Dvě cesty hromadného odesílání

​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

​Hromadné nahrání souboru přes REST API

​Plánování a zrušení

​Chyby

​Další kroky

Webhooky

REST API reference

Plánování

Odeslat Viber

Odeslat WhatsApp

Odeslat SMS

Dvě cesty hromadného odesílání

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

Hromadné nahrání souboru přes REST API

Plánování a zrušení

Chyby

Další kroky