Parametry WhatsApp textových zpráv

Objekt whatsapp_text odesílá volný obsah přes WhatsApp v otevřeném 24hodinovém zákaznickém okně — od prostého textu přes media až po interaktivní tlačítka. Na rozdíl od šablon není potřeba nic předregistrovat, obsah ale lze doručit jen tehdy, když vám příjemce v posledních 24 hodinách napsal. Pravidla okna vysvětluje koncept Typy WhatsApp zpráv; tato stránka je referenčním přehledem všech polí.

Základní pole

Pole	Typ	Popis
`sender`	string	Phone Number ID vašeho WhatsApp odesílatele (číselné ID, ne telefonní číslo) nebo alias odesílatele. Krok ho potřebuje, ale nemusíte ho uvádět přímo v něm: pokud chybí, použije se `sender` z kořene požadavku a poté výchozí odesílatel vašeho účtu (`default_sender`). Viz Odesílatelé.
`body`	string	Text zprávy. U zprávy s médiem slouží jako popisek (caption) a můžete ho vynechat. U interaktivních zpráv je to text zprávy. Pokud není uveden, použije se `body` z kořene požadavku.
`preview`	boolean	U prostého textu zapíná náhled odkazu (`preview_url`). Výchozí `false`.

Prostý text s náhledem odkazu

{
  "to": [{ "phone_number": "420777123456" }],
  "flow": [
    {
      "whatsapp_text": {
        "sender": "514578330250514",
        "body": "Nová verze je venku: https://example.com/blog",
        "preview": true
      }
    }
  ]
}

Media

Media lze odeslat dvěma způsoby. 1. Zkráceně přes body — pokud je body odkaz (začíná http) s rozpoznanou příponou, SmsManager z něj sám sestaví media zprávu:

Přípona v `body`	Typ
`.png`, `.jpeg`	Obrázek
`.mp4`, `.3gp`	Video
`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.txt`	Dokument
`.mp3`, `.acc`, `.m4a`, `.ogg`, `.amr`	Audio

2. Polem s médiem — předáte pole image, video, document nebo audio. Hodnotou je buď URL souboru jako řetězec, nebo objekt s polem url. Soubor musí být dostupný na veřejné URL.

Pole	Podporované formáty	Popisek (`caption`)
`image`	JPEG, PNG	Ano
`video`	MP4, 3GP	Ano
`document`	Například PDF, DOCX, XLSX	Ano, navíc `filename`
`audio`	Například MP3, OGG	Ne

Objekt média přijímá tato pole:

Pole	Typ	Popis
`url`	string	Veřejná URL souboru. Povinné.
`caption`	string	Popisek zobrazený u média. Pokud ho neuvedete, použije se `body`. Audio popisek nepodporuje.
`filename`	string	Název souboru zobrazený příjemci. Pouze u dokumentů.

V jedné zprávě použijte nejvýše jedno pole s médiem. Pokud zpráva obsahuje médium, body se použije jako popisek a můžete ho vynechat.

Obrázek s popiskem z body

{
  "whatsapp_text": {
    "sender": "514578330250514",
    "body": "Náhled produktu",
    "image": "https://example.com/produkt.jpg"
  }
}

Dokument s popiskem a vlastním názvem souboru

{
  "whatsapp_text": {
    "sender": "514578330250514",
    "document": {
      "url": "https://example.com/faktura.pdf",
      "caption": "Faktura za říjen",
      "filename": "faktura-2026-10.pdf"
    }
  }
}

Tlačítka rychlé odpovědi (`buttons`)

Pole buttons vytvoří interaktivní zprávu s tlačítky rychlé odpovědi — maximálně 3 (další se ořežou). body se zobrazí jako text zprávy.

Pole tlačítka	Typ	Popis
`title`	string	Popisek tlačítka.
`id`	string	Volitelné. Identifikátor vrácený ve webhooku po klepnutí. Výchozí `reply_<index>`.

Volitelně přidejte footer (text pod zprávou) a header (viz Hlavička níže).

{
  "whatsapp_text": {
    "sender": "514578330250514",
    "body": "Chcete pokračovat v objednávce?",
    "footer": "Odpovězte prosím do 24 hodin",
    "buttons": [
      { "id": "yes", "title": "Ano, pokračovat" },
      { "id": "no", "title": "Zrušit" }
    ]
  }
}

CTA tlačítko s odkazem (`url`)

Pole url (spolu s title) vytvoří interaktivní zprávu s jedním tlačítkem, které otevře odkaz. body je text zprávy; volitelně lze přidat footer a header.

Pole	Typ	Popis
`url`	string	Cílová URL tlačítka.
`title`	string	Popisek tlačítka.

{
  "whatsapp_text": {
    "sender": "514578330250514",
    "body": "Vaše objednávka byla odeslána.",
    "url": "https://example.com/track/ORD-123",
    "title": "Sledovat zásilku"
  }
}

Hlavička interaktivních zpráv

U zpráv s buttons nebo url můžete přidat pole header (řetězec). Typ hlavičky se určí podle tvaru hodnoty — odkaz s příponou obrázku/videa/dokumentu se zobrazí jako příslušné media, jinak jako text:

Obrázková hlavička

{ "header": "https://example.com/banner.png" }

Textová hlavička

{ "header": "Potvrzení objednávky" }

Raw průchozí zápis (`raw`)

Pro pokročilé případy, které toto rozhraní nepokrývá, můžete předat objekt raw s klíčem interactive, jehož obsah se odešle na WhatsApp API beze změny.

{
  "whatsapp_text": {
    "sender": "514578330250514",
    "raw": { "interactive": { "type": "list", "body": { "text": "…" }, "action": { "…": "…" } } }
  }
}

Pole se vyhodnocují v pořadí: media v body → pole document/audio/image/video → buttons → url → raw → prostý text. Uplatní se první, které v požadavku najdeme, proto v jedné zprávě kombinujte jen jeden typ obsahu.

Další kroky

Odeslat WhatsApp

Praktický průvodce odesíláním šablon i volného textu.

WhatsApp šablony

Reference parametrů proaktivních šablonových zpráv.

Typy WhatsApp zpráv

Kdy použít šablonu a kdy volný text v 24hodinovém okně.

Webhooky

Příjem odpovědí a klepnutí na tlačítka.

JSON API v2

HTTP/XML API

REST API

Verify API

WhatsApp Partner API

Referenční tabulky

Parametry WhatsApp textových zpráv

Základní pole

Media

Tlačítka rychlé odpovědi (`buttons`)

CTA tlačítko s odkazem (`url`)

Hlavička interaktivních zpráv

Raw průchozí zápis (`raw`)

Další kroky

Odeslat WhatsApp

WhatsApp šablony

Typy WhatsApp zpráv

Webhooky

​Základní pole

​Media

​Tlačítka rychlé odpovědi (buttons)

​CTA tlačítko s odkazem (url)

​Hlavička interaktivních zpráv

​Raw průchozí zápis (raw)

​Další kroky

Odeslat WhatsApp

WhatsApp šablony

Typy WhatsApp zpráv

Webhooky

Základní pole

Media

Tlačítka rychlé odpovědi (`buttons`)

CTA tlačítko s odkazem (`url`)

Hlavička interaktivních zpráv

Raw průchozí zápis (`raw`)

Další kroky