Kommunikationsintegrationer
En bref
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.
Comment ça fonctionne
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.
Capacités clés
- 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
En pratique
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.
Fonctionnalités de ce sous-système
6| ID | Status | Fonctionnalités |
|---|---|---|
| F14.13.01 | Livré | 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 | Livré | 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 | Livré | 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 | Livré | 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 | Livré | 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 | Livré | 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 |