Business SMS and WhatsApp setup

# Business SMS and WhatsApp setup — server 0.24.10

Go to Administration → SMS & WhatsApp. Create a directory provider account for each channel, then use Connect a messaging provider.

## Choose the actual business messaging service
Record Vodafone, EE / BT, O2, Three or Other / mixed networks as the company phone network. This is reference information, not a sending connector. A normal mobile contract, account login or SIM allowance is insufficient. IT must obtain business messaging/API access, approved sender details and API credentials under its supplier contract. The recipient handset network is independent of the sending gateway.

Implemented connector choices: SMS — Twilio, Vonage Messages API (global endpoint), Infobip SMS API, or an IT-managed company gateway implementing the Nuntivra HTTPS contract below. WhatsApp — Twilio or Meta WhatsApp Cloud API. A provider brand is not evidence that its API matches one of these connectors. Network-specific services must be integrated by IT through the documented gateway contract unless they supply a compatible service.

## Configure, test, then enable
1. Select a saved, enabled directory provider account and its channel. Select the company phone network and actual messaging connector.
2. Supply the approved sender and required API identifiers. Save the API secret/token once. It is encrypted using Windows machine protection in the server database and is not returned to the browser or written into directory JSON or its backups. Restrict access to server data and database backups; same-machine administrators are trusted. API credentials are separate from dashboard credentials. Blank secret on an existing connection retains the current secret for that connector.
3. Test connection. This performs real authenticated HTTPS API checks and keeps sending disabled. API key permissions must cover the check endpoint as well as message sending. No certificate validation bypass, redirects, custom ports or arbitrary script execution are supported. The initial Infobip check reads account balance; Vonage reads the application list; Twilio reads message metadata; Meta reads phone and template metadata.
4. Send a setup test to an authorised handset in international +country-code format. This is a real message with provider charges. Enter the six-digit code received within ten minutes. The provider reference is retained; the test number and message body are not written to the audit record. A new test has a 30-second minimum interval.
5. Explicitly enable the channel. Exercises are real mobile messages, clearly labelled EXERCISE. Live incident and stand-down sending requires selecting Allow live…, enabling the channel, server live policy and the operator’s live/channel permissions. Accounts lacking SMS or WhatsApp permission cannot send through those channels. Assign each recipient to the correct tested provider account.

Changing provider directory details or connection settings disables sending and requires testing again. Restoring or enabling a directory entry does not bypass the connection workflow. Fresh installations have no provider connections and never send mobile messages by default. Older pending mock jobs are never converted into real sends when a connector is enabled.

## Guided WhatsApp templates and rich content

In Administration → SMS & WhatsApp, select the WhatsApp provider account. The guide provides a copyable example body and a link to your provider's template builder. Submit the template there for WhatsApp approval; Nuntivra cannot approve it. Keep exactly two message-body placeholders: {{1}} is the EXERCISE, LIVE ALERT, STAND-DOWN or SETUP TEST label and title; {{2}} is the message. Add realistic samples when submitting for approval. Body whitespace is flattened for template parameters.

Twilio needs the approved Content SID. Meta needs the template name, language and an IT-selected supported Graph API version. Test connection loads the actual approved layout. For Twilio cards, the title field is the WhatsApp message body; card.body is for RCS. Use separate placeholder numbers from {{3}} upwards for Twilio attachment or website suffix values. Meta text headers and website buttons each have their own local placeholder {{1}}.

Supported approved layouts include a Meta text heading (fixed or one changing value), one JPEG/PNG image, PDF document or MP4 video, a fixed footer, and up to three website, phone-call or quick-reply buttons. Twilio supports text, media, call-to-action, quick-reply and card Content Templates; a fixed heading may be included in its body, while a separate native text header is supported through Meta. Unsupported components are rejected. Button labels, fixed headings, call numbers and fixed links come from the approved template and cannot be freely changed.

After loading the layout, complete the defaults requested by the guide: heading replacement, attachment URL or changing website-button suffix. Media must use a publicly reachable HTTPS URL matching the approved media type and any approved Twilio URL pattern. Local files cannot be uploaded through this screen. Providers retrieve media from that URL and validate its actual type and size; avoid confidential or short-lived links, and ensure it remains available for delivery. A changing website suffix cannot change the approved website host. Quick-reply buttons send a reply to the messaging provider; they do not record a Nuntivra acknowledgement. Inbound reply processing is not included.

Use Preview to review exercise, live or stand-down wording without sending a message or fetching media. The preview uses the last saved approved layout with the entered values; save any changes and repeat connection and handset tests before enabling. Messaging apps control final appearance. The rendered body must fit 1,024 characters including the approved wording (640 for Twilio call-to-action); changing text headings must fit 60 characters. The interface rejects missing values and unsupported combinations before sending.

Send a real setup test to an authorised handset, enter its code, then explicitly enable sending. Provider charges apply to tests and exercises. In Send an alert, optional WhatsApp details override the saved heading, attachment or changing button values for that alert. Review the resulting layout for each provider account before confirming. Saved exercise/live templates supply the normal alert content; rich values are entered separately. Clear or choose a different saved template to avoid carrying values into another alert.

Queued deliveries retain a snapshot of the rendered WhatsApp content. Monitor response and JSON/CSV history exports include that preview. Stand-down keeps the original rich values and recipients, changing the alert label and message; review whether the original attachment and links remain appropriate. Messages already submitted cannot be recalled.

When upgrading from releases before 0.24.8, existing WhatsApp connections are disabled once so IT can load and verify their approved layout, repeat the handset test and explicitly enable them. Settings and encrypted credentials are retained; SMS connections are unaffected. Re-testing or changing a connection disables sending, changes its route revision and stops older pending submissions rather than silently sending them through a changed template. Business onboarding, opt-in and supplier requirements remain IT's responsibility.

## Status and uncertain results
Provider accepted means the API accepted the request. It is not proof of handset delivery, display, reading or acknowledgement. Automatic provider delivery callbacks and inbound replies are not implemented in this connector release. Review records in the provider portal when needed. Timeouts, uncertain responses and expired in-flight leases go to Manual review and are not automatically resent, avoiding duplicate messages. A fresh setup test is not an operational alert. Disable sending to stop future submissions; messages already submitted cannot be recalled. Stand-down targets the original incident’s recipients and channels; restore any disabled original route before sending it. Maintain independent fallback communications.

The connector request/response contracts are tested using simulated provider responses; no customer credentials or paid messages are used in release verification. IT must perform the real connection and handset tests with its own accounts before enabling.

## Company SMS gateway contract
The connector accepts an HTTPS base hostname (standard port 443, no path/query/user credentials). IT must operate or approve the gateway and implement this precise API; it is not a generic adapter to arbitrary network endpoints. TLS certificates must validate against the server trust store. The token is sent as Authorization: Bearer <token>.

GET /nuntivra/v1/health returns JSON {"status":"ok"} after authenticating the token.

POST /nuntivra/v1/messages receives JSON {"to":"+447700900000","sender":"Nuntivra","text":"EXERCISE — ...","expires_at":1792800000,"request_id":"opaque-stable-key"} and Idempotency-Key: <request_id>. Validate authentication, input and expiry. Deduplicate using request_id and never submit a duplicate upstream. Return JSON {"status":"accepted","message_id":"provider-reference"} only after the upstream gateway accepts the request. Use non-2xx for rejection. Implement delivery tracking, retention, access controls and the supplier’s network-specific API behind the gateway. No secrets belong in URLs or response bodies. No arbitrary Python or JavaScript is loaded into Nuntivra.

## Reference documentation
- Twilio authentication: https://www.twilio.com/docs/usage/requests-to-twilio
- Twilio message resource: https://www.twilio.com/docs/messaging/api/message-resource
- Twilio content/templates: https://www.twilio.com/docs/content/content-api-resources
- Vonage Messages API: https://developer.vonage.com/en/api/messages
- Vonage connection check: https://developer.vonage.com/en/application/code-snippets/application/list-applications
- Infobip SMS API: https://www.infobip.com/docs/api/sms-api
- Meta official API collection: https://www.postman.com/meta/whatsapp-business-platform/