Text clients with Twilio

Crewtavo sends and receives text messages (SMS) through a phone number you get from Twilio. You pay Twilio directly, and texts come from your own business number. It takes about half an hour to set up, plus the wait while US carriers approve your number.

Setting it up is done on the server, so it’s usually the owner, or whoever has access to your Railway project.

What texting does in Crewtavo

Once it’s on:

• Quotes and invoices can be sent by Text as well as by email (see Create and send a quote and Create an invoice and get paid).
• Messages can text clients, and their replies come back into the same conversation. See Text and email clients from Messages.
• Automations can text clients with the Text the client action. The ready-made Text the client when the crew is on the way rule texts them when a crew taps On my way. It’s off until you turn it on in Settings → Automations (see Automate reminders and follow-ups).
• Review requests can go by text (see Ask for Google reviews), and so can a roof estimate’s signed copy.
• Your team can get their notifications by text, if they choose it in their notification settings (see Your profile, notifications and Crewtavo on your phone).
• Subcontractors can get job offers, paperwork requests and Text sign-in link by text, and a sub on a new phone can sign in with a 6-digit code texted from your number. Without texting, those codes go by email. See Work with subcontractors.

Everything Crewtavo texts a client is kept in their conversation in Messages.

Note

Texting is set up for the whole server. If more than one business runs on your Crewtavo, they all text from this one number, and a reply goes to the business that has a client with that phone number.

What it costs

Twilio charges for the phone number each month and for each text, sent or received. A text over 160 characters is billed as several. In the US there are also fees to register your number with the carriers (one-time, plus a small monthly fee). For a small business it usually comes to a few dollars a month plus a cent or two a text, but check Twilio’s SMS pricing for your country.

Twilio’s free trial works for trying it out, but it can only text numbers you’ve verified in Twilio and adds a note to each text. Upgrade the account before texting clients.

Set up texting

1. Get a Twilio number

1. Sign up for Twilio and add a payment method to upgrade from the trial.
2. In the Twilio Console, open Phone Numbers → Manage → Buy a number.
3. Pick a local number that can send SMS, ideally in your area code, and buy it.

2. Register the number (US)

US carriers block texts from business numbers that aren’t registered for A2P 10DLC. In the Twilio Console, register your business (the “brand”) and how you’ll text (the “campaign”), and add your number to the Messaging Service the campaign uses (you can create one while registering). Twilio’s guide walks through it: A2P 10DLC registration.

Describe what you send: appointment reminders, quotes and invoices, and replies to customers. If your subs sign in with a texted code, list one-time passcodes too. Approval can take from a few days to a few weeks, and until it’s done Twilio blocks texts from the number to US phones (error 30034). Toll-free numbers have their own verification instead.

3. Copy your account details

On the Twilio Console’s home page, under Account Info, copy the Account SID (it starts with AC) and the Auth Token. Use the Auth Token itself, not an API key.

4. Add the variables in Railway

1. In Railway, open your project, then the crewtavo service, then Variables.

2. Add these three:

   Variable	Value
   TWILIO_ACCOUNT_SID	Your Account SID, like AC1234…
   TWILIO_AUTH_TOKEN	Your Auth Token
   TWILIO_FROM_NUMBER	Your Twilio number with the country code and no spaces, like +15551234567

3. Deploy the change when Railway asks.

All three are needed: with any one missing, texting stays off. With Docker, add them to .env.instance and run npm run instance again. (See Optional settings for the other variables.)

5. Send replies to Crewtavo

So clients’ replies come into Messages, tell Twilio where to send them:

1. In the Twilio Console, open Phone Numbers → Manage → Active numbers and choose your number.

2. Under Messaging Configuration, set A message comes in to Webhook, with this address and HTTP POST:

   https://your-crewtavo-address/api/webhooks/twilio

   Use the address you open Crewtavo at, like https://crm.yourcompany.com or your ….up.railway.app address, followed by /api/webhooks/twilio.

3. Save.

Type the address exactly: https:// at the start and no slash at the end. Crewtavo checks that each incoming text really came from Twilio, and the check fails if the address differs. If you later move Crewtavo to your own domain, the old address keeps working, so replies don’t stop; you can change it in Twilio to the new one whenever you like.

If your number is in a Messaging Service

Registering for A2P 10DLC usually puts your number in a Messaging Service, and the service’s settings can take over from the number’s. In Messaging → Services, open the service, then Integration, and under incoming messages choose Defer to sender’s webhook (Twilio’s default), or Send a webhook with the same address as above.

Check it works

1. Reload Crewtavo. “Texting isn’t turned on yet.” should be gone from Messages and the send options.
2. Open a client whose Phone is your own mobile number. You can add yourself as a client to test.
3. In Messages, choose Text, write a message and send it. It should arrive on your phone from your Twilio number.
4. Reply from your phone. Within half a minute the reply shows in that client’s conversation, and owners, admins and office staff get “New text from a client”.

Apps → Twilio

Apps → Twilio shows Not available yet (“Ask whoever set up Crewtavo to turn on Twilio.”) until the variables are set. After that, there’s nothing to install there: texting already works from the variables, and a key saved on that page isn’t used.

Troubleshooting

What happens	What to do
Text says “Texting isn’t turned on yet.” after you added the variables	Check all three are on the crewtavo service, spelled exactly, and that the change was deployed. Then reload Crewtavo.
“The text provider refused it (…)”	Twilio turned the text down, and the words after the code say why. A trial account can only text verified numbers; a number that replied STOP can’t be texted until it replies START; and the number has to be a mobile that can get texts.
“Couldn’t reach the text provider. Try again.”	Twilio didn’t answer in time. Try again in a minute.
Crewtavo says it was texted, but it never arrives	In the Twilio Console, open Monitor → Logs → Messaging and look at the message’s status and error. In the US it’s usually a number whose A2P 10DLC registration isn’t approved yet (error 30034).
A client’s reply doesn’t show up	Check that the number they texted from is the Phone on their client record: texts from numbers that aren’t on a client are dropped. A text with only a picture doesn’t come in either.
No replies show up at all	Check the webhook address and HTTP POST (step 5), and the Messaging Service tip. In Monitor → Logs → Errors, a 403 means the address in Twilio isn’t exactly your Crewtavo address, or the Auth Token in Railway isn’t the current one.
Texting stopped after you changed the Auth Token in Twilio	Put the new token in TWILIO_AUTH_TOKEN and deploy. Sending and receiving both use it.

Still stuck? See Getting help.