8 min read

Twilio Integration

ArkCloud sends outbound text messages through the Twilio account set up for the deployment. Until a platform operator enters the Twilio credentials, no message is sent and no reminder is delivered. On ArkCloud's hosted service texting is switched on, but US carrier registration (A2P 10DLC) for the sending number is not yet complete, so texts to US phones may be filtered until it is. Inbound texts are read only for opt-out keywords: a patient who replies STOP has their SMS consent withdrawn in ArkCloud. Other replies do not reach staff.

Text messages to patientsPartially available

Texts are sent from ArkCloud's hosted account, only to patients who have agreed to texts, and STOP replies are honoured. US carrier registration (A2P 10DLC) for the sending number is not yet complete, so texts to US phones may be filtered until it is. Calls are not available.

What Twilio Does Here

Twilio carries ArkCloud's outbound texts. The Twilio account, its numbers, its carrier registration and its costs are yours.

Carrier-grade delivery

Twilio publishes its own availability terms; ArkCloud offers no SLA over them

Your account

Messages are billed by Twilio to the account whose credentials are entered

Your agreement

Any Business Associate Agreement is between you and Twilio

What It Does

Outbound SMS

Text messages sent through your Twilio account from your sending number (or messaging service): Rehab appointment reminders, statement-ready notices and notification texts.

Consent check

Payment, payment-plan, portal-link, statement-ready and staff-sent notification texts read consent from the patient's SMS consent flag, contact preferences and the TCPA consent register - any opt-out wins, and no record means no text - and are refused outside 8am-9pm in your organisation's timezone. Rehab appointment reminders check the patient's SMS consent and their own quiet hours.

Honest outcomes

In production with no Twilio account configured, a send fails as not configured and nothing is sent (lib/sms.ts). Outside production nothing is sent either: the text is written to the server log, and Rehab appointment reminders are recorded as simulated rather than sent.

STOP withdraws consent

A reply of STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, REVOKE or OPTOUT, received at POST /api/webhooks/twilio-sms, turns SMS consent off for every patient with that phone number, in every organisation. START does not turn consent back on. ArkCloud sends no reply; Twilio sends its own opt-out confirmation.

Example Messages

Appointment Reminder

Rehab appointment reminders

[Practice]: Hi [first name], reminder - your appointment with [provider] is on [date] at [time]. Reply STOP to opt out.

Statement Notice

A statement is ready - no balance detail or PHI beyond the statement number

Your statement [number] is ready. Please sign in to view it.

Turning It On

Prepare Twilio

Create a paid Twilio account and buy a sending number

Complete any carrier registration Twilio requires for your traffic (for US 10DLC, A2P registration)

Optionally create a Messaging Service

Set the number's "A message comes in" webhook to POST https://<your ArkCloud host>/api/webhooks/twilio-sms - without it, STOP replies never reach ArkCloud

Enter the credentials

A platform operator opens the Operator back office -> Credentials, group Twilio (SMS and calls)

Enters TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN and TWILIO_PHONE_NUMBER (E.164, e.g. +14045550100), and optionally TWILIO_MESSAGING_SERVICE_SID

Or sets the same keys in the server environment; a value saved in the back office overrides the environment and is stored encrypted

Record consent and test

Record SMS consent on the patients you will text

Send a reminder to a test patient whose number you control

Text STOP from that phone and confirm the patient's SMS consent in ArkCloud is now off, and that Twilio blocks further messages

Not Built

Two-way texting - inbound texts are read only for opt-out keywords; other replies are not stored or shown to staff

Re-consent by text - START or UNSTOP does not turn SMS consent back on; staff record renewed consent on the patient

Voice reminders or call recording through this SMS integration - an outbound call from it is refused with "Outbound calling is not available in ArkCloud yet. No call was placed." and nothing is recorded. Incoming call routing on a Twilio number (phone menus, ring groups, voicemail) is set up under Voice -> Call routing and has not yet been run on a live number

Holding a text until the sending window opens - a text outside 8am-9pm is refused, not queued

SMS verification codes for sign-in - multi-factor sign-in uses an authenticator app (TOTP)

Delivery-receipt tracking inside ArkCloud

Statement-ready texts are sent only to patients with SMS consent on file (the consent flag, contact preferences or the TCPA consent register) who have not opted out anywhere, and only between 8am and 9pm; otherwise - including when the account cannot be read - the statement is recorded as not delivered, with the reason.

Best Practices

Get Explicit Consent

Obtain and record consent before sending automated texts to patients.

Check the inbound webhook

STOP replies update consent in ArkCloud only if the Twilio number's inbound webhook points at /api/webhooks/twilio-sms and the auth token is entered; a request without a valid Twilio signature is refused. Opt-outs received before the webhook was set, or by phone or letter, still need recording by hand.

Keep PHI out of texts

Texts should point the patient to sign in rather than carry clinical or balance detail.

Watch delivery in Twilio

Delivery failures and carrier filtering are visible in the Twilio console, not in ArkCloud.

Security

ArkCloud reaches Twilio's API over HTTPS. SMS itself is not an encrypted channel between the carrier and the patient's phone, so keep protected health information out of texts. Whether you may send PHI through Twilio depends on your own agreement with Twilio.

Encrypted credentials

The auth token saved in the back office is stored encrypted

Operator-only setup

Only a platform operator can enter or change the Twilio credentials

Signed inbound requests

Inbound texts are accepted only with a valid Twilio signature, checked against the auth token; with no token configured they are refused

Amazon Connect Email Providers Communication Notifications