Kommunikationsintegrationer
I korthet
Kommunikationsintegrationer wires Petanque Life into SendGrid and Mailgun for transactional email with engagement tracking, 46elks for Swedish SMS and Twilio for international SMS fallback, Firebase Cloud Messaging for cross-platform push, and the WhatsApp Business Cloud API for conversational notifications — each behind a typed tenant-scoped config, idempotent send endpoint, message-level audit collection with engagement metrics, and signature-verified inbound webhook handler that updates delivery state automatically.
Så fungerar det
Email goes through SendGridConfig (with a Mailgun fallback) holding from/reply-to addresses, open/click/unsubscribe tracking flags, an optional ip_pool_name, sandbox_mode, and Key Vault refs for api_key and webhook_signing_key. EmailMessage records every send with config_id, provider, to[EmailRecipient], subject, template_id and template_data (or body_text/body_html), status, EmailEngagementMetrics (open/click/bounce counts), bounce_type, and idempotency_key; POST /communication/sendgrid/emails/ ships via SendGrid v3 API. SMS uses ElksConfig for Swedish numbers (api_username_ref, api_password_ref, sender_id capped at 11 GSM chars, default_country_code +46) and TwilioConfig for international fallback (account_sid_ref, auth_token_ref, messaging_service_sid, E.164 from_number, supported_countries[]); SmsMessage is shared across providers with direction (outbound/inbound), from_number, to (SmsRecipient), body up to 1600 chars, segment count, and cost in SEK or local currency.
Push notifications run through FcmConfig with FcmCredentialRefs (service_account_json_ref, project_id), default_ttl_seconds, and default_priority; PushNotification records target (PushTarget device_token, platform, player_id) or topic, title/body/image_url/data, priority, ttl_seconds, collapse_key, badge_count, sound, click_action, and idempotency_key, sending via FCM v1 API. WhatsApp is handled by WhatsAppConfig (access_token_ref, phone_number_id, business_account_id, webhook_verify_token_ref, display_phone_number, default_language_code as BCP 47); WhatsAppMessage supports template and free-text messages with template_name, template_language, template_parameters[], body_text, media_url, and read_at, posted via WhatsApp Cloud API v18.0. Inbound CommunicationWebhookEvent verifies HMAC-SHA256 (or SHA1 for legacy providers) against the configured webhook_signing_key, enforces idempotency by event id, and dispatches to email, sms, and whatsapp handlers that update engagement metrics, bounce_type, read_at, and delivery state on the originating message — keeping a single source of truth across providers.
Centrala funktioner
- SendGrid email with engagement tracking (opens, clicks, bounces) and Mailgun fallback
- 46elks SMS for Swedish numbers and Twilio for international fallback, sharing SmsMessage
- Firebase Cloud Messaging push with target/topic, priority, TTL, badge, and collapse_key
- WhatsApp Business API with template + free-text, BCP 47 languages, media attachments
- Idempotency_key on every outbound message to absorb safe retries
- CommunicationWebhookEvent with HMAC-SHA256/SHA1 signature verification
- Per-config UsageMetrics so tenants see send volume, error rate, and quota burn
I praktiken
A federation wants to send tournament reminders 24 hours before throw-off. The integrator creates a SendGridConfig with the federation's verified domain, an ElksConfig for Swedish phone numbers, and an FcmConfig wired to the Petanque Life mobile app. They build a reminder template that emits one EmailMessage, one SmsMessage, and one PushNotification per registered player, each with an idempotency_key derived from competition_id+player_id+24h-marker so the cron can safely re-run.
SendGrid open-tracking webhooks update EmailEngagementMetrics; an SMS bounce arrives via 46elks DLR and flags the SmsMessage as undelivered; the player taps the push, which fires click_action and brings them to the live bracket. The integrator opens the SendGridConfig usage panel and sees 4 200 sends, 38% open rate, and a green error budget.
Features i detta subsystem
6| ID | Status | Funktioner |
|---|---|---|
| F14.13.01 | Levererad | SendGrid transactional email — SendGridConfig-samling tenant-scopad med display_name/credentials (SendGridCredentialRefs api_key_ref/webhook_signing_key_ref)/from_email/from_name/reply_to_email/enable_open_tracking/enable_click_tracking/enable_unsubscribe_tracking/ip_pool_name/sandbox_mode/usage (UsageMetrics); CRUD /communication/sendgrid/configs/ med livscykel (draft→active→paused→error→decommissioned); EmailMessage-samling med config_id/provider/to[EmailRecipient]/subject/template_id/template_data/body_text/body_html/status/engagement (EmailEngagementMetrics)/bounce_type/idempotency_key; POST /communication/sendgrid/emails/ skickar via SendGrid v3 API ✅ PL-F1413 |
| F14.13.02 | Levererad | ELKS SMS för svenska nummer — ElksConfig-samling tenant-scopad med display_name/credentials (ElksCredentialRefs api_username_ref/api_password_ref)/sender_id (max 11 tecken GSM)/default_country_code (+46)/dlr_callback_url/usage; SmsMessage-samling med direction (outbound/inbound)/from_number/to (SmsRecipient)/body (max 1600)/segments/cost_amount/cost_currency SEK/idempotency_key; POST /communication/elks/sms/ skickar via 46elks API ✅ PL-F1413 |
| F14.13.03 | Levererad | Firebase Cloud Messaging för push — FcmConfig-samling tenant-scopad med credentials (FcmCredentialRefs service_account_json_ref/project_id)/default_ttl_seconds/default_priority/usage; PushNotification-samling med target (PushTarget device_token/platform/player_id)/topic/title/body/image_url/data/priority/ttl_seconds/collapse_key/badge_count/sound/click_action/idempotency_key; POST /communication/fcm/push/ skickar via FCM v1 API ✅ PL-F1413 |
| F14.13.04 | Levererad | Twilio SMS som international fallback — TwilioConfig-samling tenant-scopad med credentials (TwilioCredentialRefs account_sid_ref/auth_token_ref/messaging_service_sid)/from_number E.164/status_callback_url/supported_countries[]/usage; SmsMessage (delad med ELKS) med provider=twilio; POST /communication/twilio/sms/ skickar via Twilio Messages API ✅ PL-F1413 |
| F14.13.05 | Levererad | Mailgun som backup till SendGrid — MailgunConfig-samling tenant-scopad med credentials (MailgunCredentialRefs api_key_ref/webhook_signing_key_ref/domain/region eu us)/from_email/from_name/enable_tracking/enable_click_tracking/test_mode/usage; EmailMessage (delad med SendGrid) med provider=mailgun; POST /communication/mailgun/emails/ skickar via Mailgun v3 API | ✅ PL-F1413 |
| F14.13.06 | Levererad | WhatsApp Business API för notiser — WhatsAppConfig-samling tenant-scopad med credentials (WhatsAppCredentialRefs access_token_ref/phone_number_id/business_account_id/webhook_verify_token_ref)/display_phone_number/business_name/default_language_code BCP 47/usage; WhatsAppMessage-samling med to (WhatsAppRecipient)/message_type (template/text)/template_name/template_language/template_parameters[]/body_text/media_url/read_at/idempotency_key; POST /communication/whatsapp/messages/template och /text skickar via WhatsApp Cloud API v18.0; CommunicationWebhookEvent med signaturverifiering (HMAC-SHA256/SHA1), idempotens-kontroll, dispatch till email/sms/whatsapp-handlers ✅ PL-F1413 |