Overview
Twilio Messaging Service (RPI v7.8.20261113.1905 and later) sends and receives RPI SMS and RCS through Twilio. It is off by default and runs in the RPI namespace.
A Kubernetes administrator deploys the service. A network administrator publishes its webhook so Twilio can reach it. RPI administrators then set the webhook addresses in Twilio.
Deploy the service (Kubernetes administrators)
Step 1: Have these ready
|
Item |
Notes |
|---|---|
|
Twilio account |
The account SID and auth token. |
|
PostgreSQL |
The operational server when it is PostgreSQL, or your own server. SQL Server is not supported. With |
|
Messaging |
Azure Event Hubs, AWS SQS and SNS, or GCP Pub/Sub. Names are in the values reference. On AWS, subscribe each queue to its topic with raw message delivery on. |
|
Identity |
|
On AKS, add a federated credential for the rpi-twiliomessaging service account. The installer uses the same one. A new credential takes a few minutes to work.
Step 2: Enable the service
Add this to your overrides, then fill in the block for your transport: eventHubs, sqs or pubsub.
twiliomessaging:
enabled: true
accountSid: <twilio-account-sid>
messaging:
provider: <azureeventhubs | amazonsqs | googlepubsub>
ingress:
hosts:
twiliomessaging: <webhook-host>
With your own PostgreSQL server, also set postgres.reuseOperational: false, postgres.host, and postgres.username.
With your own Redis, set redisSettings.type: external and redisSettings.hostname.
Step 3: Add the secrets
With kubernetes or csi secrets, add these keys to the standard RPI Secret. See Secrets Management.
|
Key |
Value |
|---|---|
|
|
The Twilio auth token. |
|
|
The PostgreSQL password, when you use your own server. |
|
|
The Redis password, when you use your own Redis. |
With sdk secrets, add the auth token to the vault instead. PostgreSQL and your own Redis sign in with the pod's identity. On AWS ElastiCache, also set the redisSettings fields the values reference lists for it.
|
Vault secret |
Value |
|---|---|
|
|
The Twilio auth token. On AWS Secrets Manager, |
The secret is read when the pod starts. Restart rpi-twiliomessaging after changing it.
Step 4: Hand over
kubectl get ingress redpoint-rpi -n <namespace> \
-o jsonpath='{range .spec.rules[*]}{.host}{"\n"}{end}' | grep twilio
Give the network administrator the webhook host from the command above and the internal load balancer in front of the ingress controller.
Give the RPI administrators these addresses to set in Twilio:
-
https://<webhook-host>/api/v1/webhook/status -
https://<webhook-host>/api/v1/webhook/inbound -
https://<webhook-host>/api/v1/webhook/link-click
Troubleshooting
|
Symptom |
Fix |
|---|---|
|
|
Set the value named in the message. |
|
With |
The image is too old to read the vault. Use a current Twilio Messaging image. |
|
|
Add a federated credential for |
|
The pod never becomes ready on AWS |
A queue is set as an ARN. Use the queue URL. |
|
The pod logs an authorization error on a topic or queue |
Grant the identity access to the resource named in the log. |
|
The pod stays not ready after an upgrade |
Read the |
Publish the webhook (network administrators)
The ingress stays internal. Put a public edge in front of it that passes only /api/v1/webhook and blocks everything else. The edge must send the original host name to the ingress, or Twilio's signature check fails.
You need the webhook host and the internal load balancer from the Kubernetes administrator, and a certificate for the webhook host.
AWS: CloudFront
-
Create a CloudFront VPC origin for the internal load balancer, HTTPS on
443. The load balancer's security group must allow443from inside the VPC. -
Import the certificate into ACM in
us-east-1. -
Create a distribution with the webhook host as its alternate domain name.
-
Add a behavior for
/api/v1/webhook*to the VPC origin, with caching off, all methods allowed and all viewer headers forwarded. -
Point the default behavior at the same origin, with a CloudFront Function that returns
403.
-
-
Point the webhook host's public DNS record at the distribution.
Azure: Front Door
-
Create a Front Door Premium profile.
-
Add the internal load balancer as an origin over Private Link, HTTPS on
443, with the webhook host as the origin host header. Approve the private endpoint connection on the load balancer's Private Link service. -
Add the webhook host as a custom domain with its certificate.
-
Add a route for
/api/v1/webhook/*to that origin, with caching off. Front Door rejects any path without a route. -
Point the webhook host's public DNS record at the Front Door endpoint.
Check it
curl -si -X POST https://<webhook-host>/api/v1/webhook/status | head -1
curl -si https://<webhook-host>/ | head -1
The first call returns 400 to 403 from the service, because the request is unsigned. The second is blocked: 403 on CloudFront, 404 on Front Door. When both look right, tell the RPI administrators the webhook is live.
Troubleshooting
|
Symptom |
Fix |
|---|---|
|
|
The certificate on the ingress does not cover the webhook host. |
|
|
The edge cannot reach the load balancer. Check the security group on AWS, or the Private Link approval on Azure. |
|
|
Expected. Use the full addresses ending in |
|
Twilio reports signature failures |
The edge rewrites the host name. Forward the original host. |