Hoe verstuur ik een bericht naar de Swispshone pagers via de API? – Brandweerrooster.nl

📟 FAQ: Hoe stuur ik een bericht naar een Swissphone pager via de Brandweerrooster API?

Deze handleiding legt stap voor stap uit hoe je een bericht kunt sturen naar een Swissphone pager via de Brandweerrooster API.

✅ Voorwaarden

Zorg dat je het volgende hebt:

Een gebruikersaccount op Brandweerrooster
Toegang tot een geldige OAuth2 access token
Minstens één gekoppelde pager (bijv. Swissphone s.QUAD)
Optioneel: een webhook-URL voor automatische terugkoppeling

🔑 Stap 1: Verkrijg je API key via OAuth2

Brandweerrooster gebruikt OAuth2 authenticatie. Je kunt een access token ophalen via een password grant.

Token opvragen:

POST https://www.brandweerrooster.nl/oauth/token

Body (x-www-form-urlencoded):

grant_type=password
username=jouw@email.com
password=jouwWachtwoord

Voorbeeld met curl:

curl -X POST https://www.brandweerrooster.nl/oauth/token \
  -d "grant_type=password" \
  -d "username=jouw@email.com" \
  -d "password=jouwWachtwoord"

Gebruik de verkregen access_token in alle API-aanroepen:

Authorization: Bearer <access_token>

🔍 Stap 2: Zoek de ID van jouw pager

Gebruik deze API-call om je gekoppelde pagers op te vragen:

GET https://www.brandweerrooster.nl/api/v2/pagers?user_id=12345

Voorbeeld response:

[
  {
    "id": 6789,
    "user_id": 12345,
    "serial_number": "C202309.12345",
    "type": "Swissphone s.QUAD C35"
  }
]

De id (bijvoorbeeld 6789) heb je nodig in de volgende stap.

✉️ Stap 3: Verstuur een bericht naar de pager

Stuur het bericht via:

POST https://www.brandweerrooster.nl/api/v2/pagers/6789/messages

Voorbeeld body (JSON):

{
  "body": "Demo alarm",
  "address": 1234567,
  "webhook_url": "https://jouw-domein.nl/pager_webhook"
}

Toelichting velden:

body: de tekst die op de pager verschijnt
address: de capcode (adres) van de pager – hiermee wordt de juiste ontvanger aangesproken
webhook_url (optioneel): ontvang automatische terugkoppeling over de status van het bericht

Let op: de capcode (address) is specifiek per pager. Vraag deze op bij je systeembeheerder of via je organisatie-instellingen binnen Brandweerrooster.

📊 Stap 4a: Handmatig status ophalen (polling)

Als je geen webhook gebruikt, kun je de status van het verzonden bericht handmatig ophalen:

GET https://www.brandweerrooster.nl/api/v2/pagers/6789/messages/<MESSAGE_ID>

Voorbeeld response:

{
  "id": 1946615,
  "body": "Demo alarm",
  "pager_id": 6789,
  "acknowledgment_state": "automatic"
}

Mogelijke waardes van acknowledgment_state:

sent – bericht verzonden
automatic – ontvangen door pager
manual_acceptance – geaccepteerd door gebruiker
manual_rejection – geweigerd door gebruiker
failed_not_connected – niet afgeleverd (pager offline)

Je moet deze call periodiek herhalen totdat de status verandert (polling).

🌐 Stap 4b: Automatische statusupdates via webhook

Als je bij het versturen van het bericht een webhook_url meegeeft, wordt de status automatisch naar deze URL gepusht zodra er een wijziging optreedt.

Voorbeeld webhook payload:

{
  "id": 1946615,
  "acknowledgment_state": "automatic",
  "pager_id": 6789,
  "received_at": "2025-04-17T22:49:10+02:00"
}