WhatsApp Template API

API dla deweloperów

Wysyłaj zatwierdzone szablony WhatsApp z własnych systemów jednym wywołaniem API; rozmowa toczy się dalej w MonoChat.

• WhatsApp
• REST API
• Tylko API

Zainstaluj z MonoStoreZobacz na monochat.ai

Przegląd

WhatsApp Template API pozwala Twojemu CRM, ERP, sklepowi internetowemu lub dowolnemu backendowi wysłać przez MonoChat zatwierdzoną wiadomość szablonową WhatsApp do klienta. Jedno żądanie wskazuje numer WhatsApp, z którego wysyłasz, numer telefonu klienta, szablon i jego zmienne.

Gdy klient odpowie, rozmowa trafia do Twojej skrzynki MonoChat jak każda inna. Aplikacja nie ma własnych ekranów: wszystko odbywa się przez trzy endpointy API.

Najważniejsze cechy

• Jedno wywołanie API. Wyślij szablon według nazwy i języka, ze zmiennymi nagłówka, treści, przycisków i karuzeli uzupełnionymi z Twoich danych.
• Prosto do czatu. Każda wysyłka zwraca identyfikator rozmowy i bezpośredni link do niej w MonoChat.
• Nowi klienci mile widziani. Jeśli numer telefonu nie jest jeszcze klientem, klient zostaje utworzony z podaną przez Ciebie nazwą.

Instalacja i konfiguracja

1. Podłącz swój numer WhatsApp Business do MonoChat i upewnij się, że jest zweryfikowany i ma szablony zatwierdzone przez Meta.
2. Zainstaluj WhatsApp Template API w Ustawienia › MonoStore › Aplikacje lub otwórz link instalacyjny app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Jeśli nie masz konta MonoChat, link pozwoli Ci najpierw się zarejestrować i zainstaluje aplikację za Ciebie.
3. Utwórz token API w Profil › Tokeny API. Token jest wyświetlany tylko raz, więc skopiuj go od razu.
4. Wywołaj template/list.js, aby zobaczyć zatwierdzone szablony i ich zmienne.
5. Wywołaj template/send.js z numerem klienta i wartościami zmiennych, aby wysłać pierwszy szablon.

notatka

• Każda wiadomość jest rozliczana jak każda wiadomość szablonowa wysłana z MonoChat.
• Adresy URL multimediów muszą pozostać dostępne, dopóki WhatsApp nie pobierze pliku.
• Wysyłaj do klientów, którzy wyrazili zgodę na kontakt: WhatsApp może ograniczyć numery, których wiadomości są blokowane lub zgłaszane.

Funkcje

Wyświetlanie szablonów

Zatwierdzone szablony numeru WhatsApp wraz z językiem, kategorią, statusem i zmiennymi, aby Twój system wiedział, co może wysłać.

Wysyłanie szablonu

Według nazwy szablonu i języka, ze zmiennymi nagłówka, treści, przycisków i karuzeli. Brakująca wartość zatrzymuje wysyłkę, więc do klienta nie trafi nic wypełnionego w połowie.

Przypisz do konsultanta

Podaj adres e-mail konsultanta, a rozmowa zostanie otwarta na jego nazwisko.

Nagłówki multimedialne

Pobierz krótkotrwałe dane do przesyłania, umieść obraz, wideo lub dokument w magazynie MonoChat i użyj jego adresu URL jako nagłówka szablonu.

Link do rozmowy

Każda wysyłka zwraca identyfikator sesji, identyfikator wiadomości i link otwierający rozmowę w MonoChat.

Czytelne błędy

Nieudane wywołanie podaje, co poszło nie tak, na przykład „Channel not found” lub „Variable missing”.

Zanim zaczniesz

• Twój numer WhatsApp Business jest połączony z MonoChat i zweryfikowany. Zobacz Kanały.
• Szablony, które chcesz wysyłać, są zatwierdzone przez Meta. Szablony pozwalają napisać jako pierwszy lub dotrzeć do klienta poza 24-godzinnym oknem. Zobacz Szablony wiadomości.
• Masz token API z Profil › Tokeny API. Zobacz Tokeny API.
• Znasz swój slug organizacji: część po /tenants/ w Twoim adresie MonoChat. W https://app.monochat.ai/tenants/mybusiness slugiem jest mybusiness.

Dokumentacja API

Aplikacja nie ma własnych ekranów. Wszystko odbywa się przez trzy endpointy, każdy jako POST z treścią JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Co robi
template/list.js	Wyświetla szablony jednego z Twoich numerów WhatsApp wraz z ich zmiennymi.
template/send.js	Wysyła szablon do klienta i zwraca link do rozmowy.
upload/get-token.js	Zwraca krótkotrwałe dane do przesyłania obrazu, wideo lub dokumentu nagłówka.

Numery telefonów zawsze zapisuje się z numerem kierunkowym kraju i bez +, na przykład 905334445566. Pomyślne wywołanie zwraca 200 z danymi endpointu w result.

1. Wyświetlanie szablonów

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Wyświetla wszystkie szablony danego numeru WhatsApp Business: nazwę, kod języka, kategorię, komponenty (nagłówek, treść, stopka, przyciski), typy zmiennych i status zatwierdzenia.

Pole	Wymagane	Opis
phoneNumber	tak	Twój numer WhatsApp Business w MonoChat, z numerem kierunkowym kraju, bez +.
options	nie	Stronicowanie i filtry, na przykład { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Odpowiedź (skrócona):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Jak ją czytać:

• name: nazwa systemowa, pod którą wysyłasz szablon.
• languageCode: język, w którym ma zostać wysłany.
• category: kategoria WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: części, z których zbudowany jest szablon.

Komponent	Zawartość	Opis
HEADER	IMAGE, VIDEO, DOCUMENT lub tekst	Dla multimediów podawany jest format; zmienne znajdują się w variables.
BODY	Tekst ze zmiennymi	Treść wiadomości z symbolami zastępczymi, takimi jak {{1}}, {{2}}.
FOOTER	Tekst	Zwykle bez zmiennych.
BUTTONS	URL, szybka odpowiedź…	Teksty przycisków i ich zmienne, jeśli są.

Powyższy przykładowy szablon wymaga jednego obrazu w nagłówku i dwóch tekstów w treści (imię klienta i nazwa produktu). Stopka jest stała ("Teşekkürler"), a przycisków nie ma.

2. Wysyłanie szablonu

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Wysyła zatwierdzony szablon do klienta. Jeśli numer telefonu nie jest jeszcze klientem, klient zostaje utworzony; rozmowa jest otwierana (lub ponownie używana) i szablon jest w niej wysyłany.

Pole	Wymagane	Opis
phoneNumber	tak	Numer WhatsApp Business, z którego wysyłasz. Musi być połączony z MonoChat i zweryfikowany.
templateMessageName	tak	name szablonu dokładnie w takiej postaci, w jakiej zwraca go lista.
languageCode	tak	Język szablonu w takiej postaci, w jakiej zwraca go lista (na przykład tr-TR).
customerPhoneNumber	tak	Numer WhatsApp klienta.
variables	gdy szablon je ma	Wartości zmiennych szablonu (patrz niżej).
customerFirstName, customerLastName	nie	Używane, gdy klient jest nowy w MonoChat.
agentEmailAddress	nie	Przypisuje rozmowę do konsultanta z tym adresem e-mail.

Zmienne. Każdy element tablicy variables ma type i listę parameters, podawaną w kolejności symboli zastępczych szablonu:

type	parameters
HEADER	Zmienna tekstowa nagłówka lub publiczny adres URL obrazu, wideo lub dokumentu nagłówka.
BODY	{{1}}, {{2}}, … treści, po kolei.
BUTTONS	Jedna wartość dla każdego przycisku, który ma zmienną (na przykład dynamiczna część przycisku URL lub kod kuponu), w kolejności przycisków.
CAROUSEL	Zamiast parameters tablica cards z jednym wpisem na kartę karuzeli, każdy z własnymi components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Brakująca wartość zatrzymuje wysyłkę z błędem Variable missing, więc do klienta nie trafi nic wypełnionego w połowie. FOOTER rzadko ma zmienne.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Odpowiedź:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: otwiera rozmowę w MonoChat, dla osób zalogowanych i uprawnionych do jej wyświetlenia.
• sessionId: identyfikator rozmowy.
• messageId: identyfikator wiadomości w MonoChat. Jej status dostarczenia i odczytu pojawia się na czacie jak w przypadku każdej innej wiadomości.

Multimedia w szablonach. WhatsApp pobiera multimedia nagłówka z podanego przez Ciebie adresu URL, więc adres musi być prawidłowy i publicznie dostępny. Linki wymagające logowania nie działają. Jeśli plik został przesłany przez upload/get-token.js, użyj adresu URL pliku zbudowanego na podstawie tej odpowiedzi.

3. Przesyłanie multimediów do nagłówka

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Gdy nagłówkiem szablonu jest obraz, wideo lub dokument, plik potrzebuje publicznego adresu, z którego WhatsApp może go pobrać. Ten endpoint daje krótkotrwałe uprawnienie do umieszczenia pliku w magazynie MonoChat.

Pole	Wymagane	Opis
fileName	tak	Nazwa pliku z rozszerzeniem, na przykład product.jpg lub promo.pdf.

Pliki są zawsze zapisywane w folderze chat-assets Twojej przestrzeni roboczej; starsze przykłady wysyłające pole key nadal działają, wartość nie jest potrzebna.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

Odpowiedź wskazuje, gdzie umieścić plik, i zawiera dane do jego przesłania:

Pole	Opis
bucket, region, path	Miejsce, gdzie trafia plik.
temporaryCredentials	Dane tylko do przesyłania dla tej jednej ścieżki, ważne przez 15 minut.
baseUrl	Publiczny adres magazynu. Adres URL pliku to baseUrl + / + path.

Prześlij plik od razu za pomocą dowolnego klienta S3 z tymi danymi, a następnie przekaż jego adres URL jako parametr HEADER podczas wysyłania szablonu. Bardzo duże pliki lub formaty nieobsługiwane przez WhatsApp (akceptuje popularne formaty obrazów, wideo i PDF) kończą się błędem.

Przykład: szablon z obrazem w nagłówku

Załóżmy, że masz zatwierdzony szablon new_product_announcement z obrazem w nagłówku i dwiema zmiennymi w treści (imię klienta i nazwa produktu) i chcesz wysłać go do klienta.

1. Wyświetl szablony. Wywołaj template/list.js z numerem WhatsApp i znajdź new_product_announcement. Jego komponenty pokazują jedną zmienną IMAGE w nagłówku i dwie zmienne TEXT w treści.
2. Prześlij obraz. Wywołaj upload/get-token.js z { "fileName": "urun.jpg" }, prześlij plik za pomocą zwróconych danych i zbuduj jego adres URL z baseUrl i path.
3. Wyślij szablon. Wywołaj template/send.js z adresem URL pliku jako parametrem HEADER i ["Ayşe", "XYZ Telefon"] jako parametrami BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Gdyby szablon miał zmienne przycisków, dodałbyś element BUTTONS w ten sam sposób.
4. Otwórz czat. url z odpowiedzi otwiera rozmowę; gdy klient odpowie, rozmowa toczy się dalej w Twojej skrzynce MonoChat.

Błędy

Nieudane wywołanie zwraca status błędu i komunikat informujący, co poszło nie tak. Zapisuj te komunikaty w logach swojego systemu i w razie potrzeby pokazuj użytkownikom zrozumiały komunikat.

Komunikat	Przyczyna
phoneNumber field is required	template/list.js wywołano bez phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Brakuje wymaganego pola template/send.js.
Channel not found	phoneNumber nie jest numerem WhatsApp Twojej przestrzeni roboczej.
Channel is not verified	Numer WhatsApp jest połączony, ale niezweryfikowany.
Template message not found	Brak zatwierdzonego szablonu o tej nazwie i języku na tym numerze. Sprawdź pisownię i languageCode.
Template message is not approved	Szablon istnieje, ale nie jest zatwierdzony przez Meta.
Variable missing: …	variables nie pasuje do szablonu, na przykład szablon wymaga dwóch wartości treści, a wysłano jedną.
Agent user not found	Brak konsultanta z adresem e-mail z agentEmailAddress.
Customer Channel not found	Nie udało się utworzyć ani znaleźć tożsamości klienta w WhatsApp.

Kody statusu HTTP, które możesz zobaczyć:

• 401 Unauthorized: brakuje nagłówka Authorization: Bearer <API_TOKEN> lub token jest nieprawidłowy albo wygasł. Użyj prawidłowego tokenu ze swojego konta.
• 403 Forbidden: token nie ma dostępu do tej przestrzeni roboczej lub aplikacji, na przykład z powodu błędnego sluga organizacji.
• 404 Not Found: adres endpointu jest błędny. Sprawdź pełną ścieżkę /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: nieoczekiwany problem w MonoChat lub u dostawcy WhatsApp albo odmowa po stronie WhatsApp (numer nie jest w WhatsApp, klient Cię zablokował, limity jakości lub liczby wiadomości). Spróbuj ponownie później i skontaktuj się z pomocą techniczną MonoChat, jeśli problem się utrzymuje.

Zrzuty ekranu

Wysyłanie zatwierdzonego szablonu WhatsApp z systemu CRM, ERP lub e-commerce jednym wywołaniem API przez MonoChatLista zatwierdzonych szablonów WhatsApp wraz z ich zmiennymiWysłanie szablonu na nowy numer automatycznie tworzy klientaJeden szablon wysłany w kilku językachSzablony z nagłówkami z obrazem, wideo, dokumentem i plikiem PDF

FAQ

Czy WhatsApp Template API ma interfejs użytkownika?

Nie. To aplikacja wyłącznie API z trzema endpointami: wyświetlanie szablonów, wysyłanie szablonu i pobieranie danych do przesyłania nagłówków multimedialnych.

Czego potrzebuję, zanim zacznę z niej korzystać?

Numer WhatsApp Business połączony z MonoChat i zweryfikowany, szablony zatwierdzone przez Meta oraz token API z sekcji Profil › Tokeny API.

Co się dzieje, gdy klient odpowie?

Rozmowa trafia do Twojej skrzynki MonoChat jak każda inna. Każda wysyłka zwraca też bezpośredni link do rozmowy, a możesz przypisać ją konsultantowi na podstawie adresu e-mail.

Czy mogę wysłać wiadomość na numer, który nie jest jeszcze klientem?

Tak. Jeśli numer telefonu nie jest jeszcze klientem, klient zostaje utworzony z podaną przez Ciebie nazwą.

Ile kosztują wiadomości szablonowe?

Każda wiadomość jest rozliczana jak każda wiadomość szablonowa wysłana z MonoChat. Meta wycenia szablony według kategorii i kraju odbiorcy; skorzystaj z kalkulatora kosztów wysyłki masowej WhatsApp, aby oszacować koszt wysyłki.

Powiązane

• Session Link
• Bulk Template Message API
• Szablony wiadomości
• Aplikacje MonoStore