Skip to main content
Version: 0.17

Configure the WhatsApp provider

This guide is for the system administrator who operates Core or Enterprise. Workspace managers select recipients and channels in Contact groups after this deployment setup works.

1. Connect Twilio​

Use a Twilio account with an approved WhatsApp sender. In System Settings, set the account SID, auth token, and WhatsApp sender, or supply their deployment environment variables. Environment-set fields are locked in the UI. See the Twilio variable reference for exact names and Secret wiring.

Keep credentials in the deployment's secret store. After changing environment values, restart the API and delivery workers that consume them; see Configuration basics.

2. Configure templates​

Template contracts​

This section is the exact setup contract between TokenTimer and Twilio Content Templates. If a template uses placeholders that TokenTimer does not send, Twilio rejects delivery.

Step 1: Create templates in Twilio​

  • Twilio Console > Messaging > Content Template Builder > Create template.
  • Content type: Text.
  • Channel: WhatsApp.
  • Category: Utility (recommended for alerts and digests).
  • Create one template per use case below. Save and submit for approval. Copy the generated HX... SID.

Step 2: Map each SID​

  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_EXPIRES: template used for upcoming expirations. Configured in System Settings.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_EXPIRED: template used for already expired items. Configured in System Settings.
  • TWILIO_WHATSAPP_TEST_CONTENT_SID: template used by System Settings test send and contact test send. Configured in System Settings.
  • TWILIO_WHATSAPP_WEEKLY_DIGEST_CONTENT_SID: template used for the weekly digest channel. Configured in System Settings.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_ENDPOINT_DOWN: deployment-level template used for endpoint down alerts. Configured as an environment variable; see Configuration reference.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_ENDPOINT_RECOVERED: deployment-level template used for endpoint recovered alerts. Configured as an environment variable; see Configuration reference.

Endpoint health WhatsApp template SIDs are configured at deployment level and require a delivery worker restart after changes.

Placeholder contracts by template​

  • EXPIRES template: recipient_name, token_type, token_name, days_text, expiration_date, details.
  • EXPIRED template: recipient_name, token_type, token_name, days_text, expiration_date, details.
  • TEST template: no placeholders required.
  • WEEKLY_DIGEST template: recipient_name, workspace_name, contact_group_name, tokens_count, tokens_list.
  • ENDPOINT_DOWN template: recipient_name, endpoint_name, endpoint_url, token_name, detected_at.
  • ENDPOINT_RECOVERED template: recipient_name, endpoint_name, endpoint_url, token_name, detected_at.

Rule: only use placeholders listed for that template. Extra placeholders are not populated by TokenTimer.

Copy-ready template examples​

EXPIRES​

Template body

ALERT: Token Expiring Soon

Hello {{recipient_name}}, your {{token_type}} token "{{token_name}}" is expiring in {{days_text}} day(s) on {{expiration_date}}.

Details: {{details}}

Please plan the renewal to avoid service disruption.

TokenTimer Expiration Management

Example sample values

recipient_name = Operations Team
token_type = Certificate
token_name = production-api-cert
days_text = 7
expiration_date = 2025-10-10
details = DigiCert, Location: eu-west-1 (AWS), Used By: API Gateway, Domains: api.example.com, www.example.com, Algorithm: RSA, Key Size: 2048 bits

EXPIRED​

Template body

URGENT: Token Expired

Hello {{recipient_name}}, your {{token_type}} token "{{token_name}}" expired {{days_text}} day(s) ago on {{expiration_date}}.

Details: {{details}}

This token has expired and may cause service outages. Please renew immediately.

TokenTimer Expiration Management

Example sample values

recipient_name = Operations Team
token_type = Certificate
token_name = production-api-cert
days_text = 3
expiration_date = 2025-10-10
details = DigiCert, Location: eu-west-1 (AWS), Used By: API Gateway, Domains: api.example.com, www.example.com, Algorithm: RSA, Key Size: 2048 bits

TEST​

Template body

TokenTimer WhatsApp Test

Hello, this is a test to confirm WhatsApp alerts are working for your workspace.

If you receive this, WhatsApp delivery is configured correctly.

TokenTimer Expiration Management

No sample values required. This template is static.

WEEKLY_DIGEST​

Template body

📊 Weekly Digest: {{tokens_count}} token(s) Expiring Soon

Hello {{recipient_name}},

Your workspace "{{workspace_name}}" has {{tokens_count}} token(s) expiring soon in the contact group "{{contact_group_name}}".

Expiring tokens
{{tokens_list}}

Please review and renew these tokens to avoid service disruptions.

TokenTimer Expiration Management

Example sample values

tokens_count = 10
recipient_name = On-call Team
workspace_name = Production
contact_group_name = Primary On-call
tokens_list = SSL Certificate: 2025-10-10 (90d); API Key: 2025-11-29 (75d); Database Password: 2025-11-19 (71d)

ENDPOINT_DOWN​

Template body

⚠️ Endpoint Down

Hello {{recipient_name}},

TokenTimer detected that endpoint "{{endpoint_name}}" is DOWN.
URL: {{endpoint_url}}
Linked token: {{token_name}}
Detected at: {{detected_at}}

Please check the affected service.

TokenTimer Endpoint Monitoring

Example sample values

recipient_name = On-call Team
endpoint_name = staging-api
endpoint_url = https://staging.example.com/health
token_name = staging-api-cert
detected_at = Mar 16, 2026, 18:00 UTC

ENDPOINT_RECOVERED​

Template body

✅ Endpoint Recovered

Hello {{recipient_name}},

TokenTimer detected that endpoint "{{endpoint_name}}" has RECOVERED.
URL: {{endpoint_url}}
Linked token: {{token_name}}
Detected at: {{detected_at}}

The endpoint is responding normally again.

TokenTimer Endpoint Monitoring

Example sample values

recipient_name = On-call Team
endpoint_name = staging-api
endpoint_url = https://staging.example.com/health
token_name = staging-api-cert
detected_at = Mar 16, 2026, 18:12 UTC

3. Test transport, then workspace routing​

Use the System Settings test action and confirm receipt on a test phone number. Then add a workspace contact with an E.164 number, select WhatsApp in its contact group, and use the contact test. Test sends have a cooldown; repeated retries do not bypass provider throttling.

A successful test proves transport. To check real asset routing, assign that group to a harmless sample and inspect delivery history, the provider result, and the receiving phone. Check the configured template SID and placeholder contract first when Twilio rejects a message.