RCS API

RCS API umożliwia wysyłanie wiadomości RCS z zewnętrznych systemów, zarządzanie agentami i szablonami, planowanie kampanii oraz pobieranie raportów.

Spis treści

• Dostęp i autoryzacja
• Endpointy
• Agenci
• Treść wiadomości
• Szablony
• Wiadomości transakcyjne
• Wiadomości testowe
• Kampanie
• Raporty
• Błędy
• Dobre praktyki

Dostęp i autoryzacja

Bazowy adres API:

https://api.sare.pl/ext/rcs/v1

Do każdego żądania należy dodać nagłówek autoryzacyjny:

Authorization: Bearer <integrationKey>:<secret>

Uwaga

Klucza integracji ani sekretu nie należy umieszczać w kodzie aplikacji frontendowej, w parametrach URL ani w logach. Wygenerowanie nowego sekretu unieważnia poprzedni.

Limity

• POST /messages: 35 żądań na sekundę
• pozostałe endpointy: 30 żądań na minutę
• limity są liczone dla kombinacji adresu IP oraz danych dostępowych
• po przekroczeniu limitu API zwraca kod 429

Endpointy

Metoda	Ścieżka	Zastosowanie
GET	/agents	Lista dostępnych agentów
PATCH	/agents/{agentId}	Aktualizacja agenta
POST	/templates	Utworzenie szablonu
GET	/templates	Lista szablonów
GET	/templates/{id}	Szczegóły szablonu
PUT	/templates/{id}	Aktualizacja całego szablonu
DELETE	/templates/{id}	Usunięcie szablonu
POST	/messages	Wiadomość transakcyjna
POST	/messages/test	Wiadomość testowa
GET	/messages/{messageId}	Status wiadomości
POST	/campaigns	Zaplanowanie kampanii
GET	/campaigns/{id}	Status kampanii
GET	/reports/campaigns/{id}/summary	Podsumowanie kampanii
GET	/reports/campaigns/{id}/aggregations	Wyniki kampanii w czasie
GET	/reports/campaigns/{id}/action-details	Akcje odbiorców
GET	/reports/campaigns/{id}/recipients/{eventType}	Odbiorcy według zdarzenia
GET	/reports/campaigns/{id}/all-data-export	Pełny raport kampanii w ZIP
GET	/reports/messages/summary	Podsumowanie wiadomości
GET	/reports/messages/aggregations	Wyniki wiadomości w czasie
GET	/reports/messages/export	Eksport wiadomości do CSV

Agenci

Endpoint GET /agents zwraca listę aktywnych agentów przypisanych do konta.

curl 'https://api.sare.pl/ext/rcs/v1/agents' \
  -H 'Authorization: Bearer <integrationKey>:<secret>'

Przykładowa odpowiedź:

{
  "items": [
    {
      "agentId": "google-rbm-agent-id",
      "name": "Agent PL",
      "displayName": "Marka",
      "billingType": "single",
      "active": true
    }
  ]
}

• agentId to identyfikator Google RBM Agent ID i należy przekazywać go bez zmian w wiadomościach oraz kampaniach
• name to nazwa techniczna agenta
• displayName to nazwa widoczna w SARE
• billingType określa model rozliczeń: single, conversational lub basic

Nazwę wyświetlaną oraz aktywność agenta można zaktualizować przez PATCH /agents/{agentId}.

curl -X PATCH 'https://api.sare.pl/ext/rcs/v1/agents/google-rbm-agent-id' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "Nowa nazwa marki",
    "active": false
  }'

• displayName jest opcjonalne i może mieć maksymalnie 31 znaków
• pusty ciąg usuwa nazwę wyświetlaną
• active w publicznym API przyjmuje wyłącznie wartość false
• żądanie musi zawierać co najmniej jedno z pól: displayName lub active

Treść wiadomości

Treść wiadomości można przekazać na dwa sposoby:

• przez istniejący szablon:

{ "templateId": 55 }

• bezpośrednio w żądaniu jako wiadomość inline:

{
  "inline": {
    "type": "CARD",
    "content": "Sprawdź szczegóły oferty tygodnia.",
    "buttons": [
      {
        "id": "offer-link",
        "type": "url",
        "text": "Zobacz ofertę",
        "url": "https://example.com/oferta"
      },
      {
        "id": "offer-interest",
        "type": "quick_reply",
        "text": "Jestem zainteresowany",
        "payload": "OFFER_INTERESTED"
      }
    ],
    "data": {
      "title": "Oferta tygodnia",
      "imageUrl": "https://example.com/images/offer.jpg",
      "orientation": "VERTICAL",
      "height": "TALL"
    }
  }
}

W pojedynczym żądaniu należy użyć tylko jednego wariantu. Wysyłka przez templateId wymaga szablonu ze statusem APPROVED.

Obsługiwane typy wiadomości:

• MESSAGE
• AUDIO
• VIDEO
• FILE
• CARD
• CONTACT
• CAROUSEL
• LOCATION

Publiczne typy przycisków:

• url
• quick_reply
• call
• calendar
• location
• trigger_template

Każdy przycisk musi mieć unikalne id w obrębie całej wiadomości. W karuzeli ta zasada obejmuje wszystkie karty. Pliki multimedialne oraz obrazy muszą być dostępne pod publicznym adresem HTTPS.

RCS Basic

Tryb RCS Basic włącza się polem basic: true.

• dozwolony jest wyłącznie tekst typu MESSAGE
• wiadomość nie może zawierać przycisków ani multimediów
• maksymalna długość wynosi 160 bajtów UTF-8
• przy użyciu szablonu wartość basic musi być zgodna w szablonie i w zleceniu

Szablony

Nowy szablon domyślnie otrzymuje status DRAFT. Do wysyłki można używać wyłącznie szablonów ze statusem APPROVED.

curl -X POST 'https://api.sare.pl/ext/rcs/v1/templates' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Status zamówienia",
    "description": "Informacja o wysyłce paczki",
    "basic": false,
    "status": "APPROVED",
    "message": {
      "type": "MESSAGE",
      "content": "Twoja paczka została wysłana.",
      "buttons": [],
      "data": {}
    }
  }'

• name to nazwa szablonu
• description jest opcjonalnym opisem
• basic wybiera tryb RCS Basic
• status określa gotowość do wysyłki
• message zawiera treść wiadomości

Endpoint PUT /templates/{id} zastępuje cały szablon, dlatego należy przesłać komplet danych. Szablonu nie można usunąć, jeżeli jest wykorzystywany przez przycisk trigger_template albo konfigurację automatycznej odpowiedzi.

Lista szablonów obsługuje paginację oraz filtrowanie po statusie, typie i dacie utworzenia.

Wiadomości transakcyjne

Żądanie POST /messages wymaga unikalnego nagłówka Idempotency-Key. Ponowienie identycznego żądania z tym samym kluczem nie utworzy drugiej wiadomości. Użycie tego samego klucza z inną treścią zwróci kod 409.

curl -X POST 'https://api.sare.pl/ext/rcs/v1/messages' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -H 'Idempotency-Key: order-2026-000123' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientReferenceId": "order-2026-000123",
    "agentId": "google-rbm-agent-id",
    "recipient": "+48500100200",
    "expiresAt": "2030-07-28T10:00:00.000Z",
    "basic": false,
    "message": { "templateId": 55 }
  }'

API zwraca kod 202 i identyfikator messageId. Aktualny stan wiadomości można pobrać przez GET /messages/{messageId}.

Typowe statusy wiadomości:

• ACCEPTED
• SENDING
• SENT
• DELIVERED
• READ
• FAILED
• EXPIRED

SMS fallback

Opcjonalne pole smsFallback umożliwia wysłanie SMS-a, gdy RCS nie jest dostępny dla danego numeru. Pole smsFallbackAfterExpiry pozwala zaplanować SMS po wygaśnięciu wiadomości RCS.

{
  "smsFallback": {
    "planParams": {
      "sender": "Marka",
      "mode": "cut",
      "campaign": "Fallback zamówienia 2026-000123",
      "smsShipmentType": 1,
      "sendTime": "2030-07-27T09:05:00.000Z",
      "testNumbers": [],
      "controlGroup": false,
      "quarantine": false,
      "useTestNumbers": false,
      "consentIDS": [],
      "ignoreStatus": false,
      "delay": 0
    },
    "smsMessagesPlan": [
      {
        "content": "RCS jest niedostępny. Sprawdź status zamówienia online.",
        "multipart": false,
        "diacriticalSigns": true,
        "urlShortening": false,
        "abTestDivision": 0
      }
    ]
  },
  "smsFallbackAfterExpiry": {
    "sendTime": "2030-07-28T10:30:00.000Z",
    "delay": 0
  }
}

• smsMessagesPlan musi zawierać dokładnie jeden wariant wiadomości
• publiczny fallback obsługuje smsShipmentType: 1
• smsFallbackAfterExpiry wymaga jednoczesnego podania smsFallback oraz expiresAt
• smsFallbackAfterExpiry.sendTime musi być późniejsze niż expiresAt

Wiadomości testowe

Endpoint POST /messages/test wysyła tę samą treść do maksymalnie 5 unikalnych numerów.

• używa pola recipients zamiast recipient
• nie wymaga nagłówka Idempotency-Key
• nie obsługuje SMS fallbacku
• nie jest uwzględniany w raportach transakcyjnych

Kampanie

Kampania korzysta z istniejących segmentów SARE i tak samo jak wiadomość transakcyjna wymaga nagłówka Idempotency-Key.

curl -X POST 'https://api.sare.pl/ext/rcs/v1/campaigns' \
  -H 'Authorization: Bearer <integrationKey>:<secret>' \
  -H 'Idempotency-Key: campaign-2026-07-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientReferenceId": "campaign-2026-07-001",
    "name": "Powiadomienie klientów",
    "agentId": "google-rbm-agent-id",
    "segmentIds": [101, 102],
    "scheduledAt": "2030-07-28T10:00:00.000Z",
    "expiresAt": "2030-07-29T10:00:00.000Z",
    "basic": false,
    "message": { "templateId": 55 }
  }'

Najważniejsze zasady:

• segmentIds to identyfikatory grup SARE widoczne jako config.group, a nie techniczne rekordy Segment.id
• campaignId z odpowiedzi POST /campaigns jest tym samym identyfikatorem, którego należy używać w GET /campaigns/{id} i raportach
• backend zapisuje snapshot treści szablonu podczas przyjęcia kampanii
• usunięcie szablonu nie zmienia ani nie anuluje już zaplanowanej kampanii

Kampania może zawierać pola smsFallback i smsFallbackAfterExpiry o takiej samej strukturze jak wiadomość transakcyjna.

• smsFallback.planParams.sendTime musi być późniejsze niż scheduledAt
• smsFallbackAfterExpiry.sendTime musi być późniejsze niż expiresAt

Raporty

Raporty kampanii udostępniają:

• podsumowanie wysyłki
• wyniki w czasie
• akcje odbiorców
• listy odbiorców według typu zdarzenia
• pełny eksport danych w archiwum ZIP

Raporty wiadomości transakcyjnych obejmują:

• podsumowanie
• agregację dzienną
• eksport CSV

Wiadomości wysłane przez POST /messages/test nie są uwzględniane w raportach.

Zakres raportu można ograniczyć parametrami from i to w formacie YYYY-MM-DD. Endpointy listowe obsługują również paginację i sortowanie.

curl 'https://api.sare.pl/ext/rcs/v1/reports/messages/summary?from=2030-07-01&to=2030-07-31' \
  -H 'Authorization: Bearer <integrationKey>:<secret>'

Webhooki

Zdarzenia webhooków RCS, sposób ich podpisywania oraz przykłady payloadów opisano na osobnej stronie: Webhooki RCS.

Błędy

Błędy API zawierają stały kod biznesowy oraz requestId, który warto zachować na potrzeby wsparcia technicznego.

{
  "statusCode": 400,
  "code": "RCS_INVALID_MESSAGE",
  "message": "RCS_INVALID_MESSAGE",
  "requestId": "req_01J9ZQ6B7S1C2T"
}

Najczęściej spotykane odpowiedzi:

• 400 - niepoprawne dane
• 401 - błędne dane dostępowe
• 403 - moduł nie jest dostępny
• 404 - nie znaleziono zasobu
• 409 - konflikt, na przykład ponowne użycie klucza idempotencji
• 429 - przekroczony limit żądań

Dobre praktyki

• ustawiaj timeout dla każdego żądania
• przy błędach 429 oraz przejściowych 5xx stosuj ponowienia ze stopniowo rosnącym odstępem
• błędów walidacji 4xx nie ponawiaj automatycznie
• przy ponowieniu zachowuj ten sam Idempotency-Key
• zapisuj messageId, campaignId, eventId i requestId
• daty przesyłaj w formacie ISO 8601, najlepiej w UTC (Z)