Configure SMS Alerts

The response ladder (breach, reminder, escalation, final escalation) and follow-up reminders are email by default. With a Twilio account saved on the brokerage, the brokerage can turn on text messages and every alert also texts the people it emails. Each brokerage brings its own Twilio account and number; a platform-wide account in the API’s environment is only a fallback for brokerages that have none.

What gets texted

Each text is short, under 300 characters: the lead’s name, how long they have waited or what the follow-up is about, the lead’s phone number when they gave one, and the link to the lead. One text per recipient per rung, never repeated. When automatic reassignment moves a lead, the new agent gets a text too.

Alert	Who is texted
Breach, reminder, follow-up due	The assigned agent at their mobile number, or their office line when that is all the profile has. Unassigned leads text the brokers and owner instead.
Escalation, final escalation	Brokers and the owner, at the phone on their broker contact. A manager with no broker contact, or one with no phone on it, gets email only.

Numbers are sent as US numbers unless they already start with +: ten digits get +1, eleven digits starting with 1 get +, anything else is skipped as unsendable.

Configure a brokerage

1. In the Twilio console, note the Account SID and Auth Token, and buy or pick a number with SMS capability.
2. Open the brokerage in the admin and find the Lead Routing card. Under Response and follow-up, below the channel switches, is the Twilio account box.
3. Enter the Account SID, the Auth token and the From number. The from number is normalized the same way recipients are; a number Twilio could never send from is refused when you save.
4. Type your own mobile into Send a test to and click Send test text. The test uses the credentials in the form when you have typed a token, so you can prove them before saving; otherwise it uses the saved ones. It waits for the carrier to accept or reject the message rather than reporting that Twilio queued it, so it takes a few seconds and a text that never arrives comes back as a failure with Twilio’s own error on the page.
5. Save the brokerage. The badge on the box reads Sending from own number once all three parts are stored.

The auth token is stored encrypted with the same key as MLS feed credentials (CREDENTIAL_ENCRYPTION_KEY) and is never returned by the API again; the settings only say whether one is saved. To replace it, type a new one. To remove it, use Remove the saved token under the field and save.

Register the number for A2P 10DLC first

US carriers require any application texting from a normal ten-digit number to be registered with The Campaign Registry. An unregistered number is not blocked by Twilio: Twilio accepts the message, returns a success, and the carrier silently drops it. The test button reports this as Twilio error 30034 rather than a send.

Register in the Twilio console under Messaging, then Regulatory Compliance, then A2P 10DLC. Create a brand, then a campaign describing the use case, then a messaging service holding the number. Sole proprietor registration needs a code texted to the owner’s mobile and clears quickly; standard brand registration needs an EIN and takes longer to vet. Either way the console quotes the setup and monthly fees.

A verified toll-free number is the alternative. Verification is a form rather than a registry and takes several business days, but it means a different sending number.

There is no exemption for texting a brokerage’s own agents. Alerts from a system are application traffic either way.

Register the number you intend to keep

Registration attaches to whichever number sits in the messaging service’s sender pool, so settle on the permanent number for lead alerts before paying to register one.

Turn it on for a brokerage

In the same card, the Channels row has Text message alerts. It is off for every brokerage until a broker or admin turns it on. The switch saves whether or not Twilio is configured, so a brokerage can be set up ahead of its account; the row says Needs a Twilio account below until one is complete.

Platform fallback

A brokerage with no complete Twilio account of its own falls back to the platform’s, when the API has one:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_FROM_NUMBER=+12085550100

All three are required for the fallback to count. With neither a brokerage account nor a platform one, services/sms.py sends nothing, logs one warning the first time a text is requested, and the alert carries on by email. GET /api/admin/brokerages/alert-capabilities reports the platform fallback as sms; the brokerage’s own state is sms_configured on the brokerage itself.

Let agents opt out

On the agent profile, next to Mobile Phone, Text me lead alerts is on by default. Off means the brokerage’s texts skip that agent; the email and any browser push still go. Brokers and owners have no switch of their own yet: remove the phone from the broker contact to stop their texts.

Note

The sending number is one-way. Replies to it go nowhere. The text always carries the link, so the action is in the admin, not in the thread.

Check it is working

POST /api/v1/admin/leads/lifecycle/sweep returns, for every rung, sms_sent and push_sent counts beside the email sent flag, and the summary line ends with N texted, M pushed. A text that Twilio refuses is logged at ERROR with the status code and the first part of Twilio’s reply, and never stops the email. POST /api/admin/brokerages/{id}/sms-test is the endpoint behind the test button, for scripting the same check; it answers with ok, Twilio’s status and any error_code.

Those counts mean the alert sweep handed each message to Twilio, not that a phone received it. The sweep deliberately does not wait for carriers, because it texts many people at once and delivery receipts arrive well after the alert should have gone out. The test button is the surface that waits, and Twilio’s own message log is where to look when a specific alert never arrived.