Recipes

ServiceTitan recipes

Text customers from your own number with a script that reads ServiceTitan jobs through its API.

Two recipes for ServiceTitan. Each names its trigger and the BlueBot step, lists the fields to map and says how to test it with your own number before anyone else gets a text.

How ServiceTitan connects

API: Your own code calls BlueBot’s REST API and listens to its signed webhooks.

Remind customers the day before

Part	What it is
Trigger	A script you run each afternoon
Action	`POST /v1/messages`
Connects through	API

Steps

Read tomorrow’s appointments through ServiceTitan’s API.
Send each customer a text with POST /v1/messages, the job number in metadata and an Idempotency-Key per appointment, so a second run never texts twice.
Listen for message.failed to catch numbers that didn’t take the text.

Map the fields

BlueBot field	Map it to
`to`	The person’s mobile number from ServiceTitan. US numbers can leave off the +1.
`text`	Hi {{first_name}}, this is Northside Plumbing. Your technician is booked for tomorrow between {{arrival_window}}. Reply here if that doesn’t work.
`{{first_name}}` in the text	ServiceTitan’s first name field.
`{{arrival_window}}` in the text	ServiceTitan’s arrival window field.
`metadata`	`source` set to `servicetitan`, and `record_id` set to the record’s id, so the status and reply webhooks for this text can find the record again.
`service`	Auto, the default: iMessage when the person uses it, otherwise SMS through your iPhone.

POST/v1/messagesSend a text →

curl -X POST "https://usebluebot.com/api/v1/messages" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: servicetitan-1042" \
  -d '{
    "to": "+15555550123",
    "text": "Hi Maria, this is Northside Plumbing. Your technician is booked for tomorrow between (arrival window). Reply here if that doesn’t work.",
    "metadata": {
      "source": "servicetitan",
      "record_id": "1042"
    }
  }'

Test it

Run the request with your own number in to. A text arrives on your phone from your own number.

Get replies back to the office

Part	What it is
Trigger	A text comes in (BlueBot’s message.received webhook)
Action	A webhook for `message.received` starts it, and ServiceTitan takes the text
Connects through	API

Steps

Point a BlueBot webhook for message.received at your own endpoint.
Find the last text you sent that number with GET /v1/messages and read the job number from its metadata.
Add the reply to that job as a note through ServiceTitan’s API so the office sees it.

Map the fields

From BlueBot	Into ServiceTitan
`data.from`	The phone number to find the person by in ServiceTitan. It’s in E.164 (`+15555550123`); search by the last 10 digits if ServiceTitan stores numbers another way.
`data.text`	The words, for a note, a row or a message. Null when the person sent only a picture.
`data.received_at`	When it came in, in UTC.
`data.files`	Pictures and voice memos. Each `url` works for an hour, so copy a file you want to keep.
`data.chat_id`	Set when the text came in a group chat; null for a one-to-one text.

Test it

Run bluebot listen --forward-to http://localhost:3000/webhooks, then text your BlueBot number from another phone. The CLI forwards the event to your handler, signed. BlueBot copies texts from people you’ve texted through it, unless you set Which chats to copy to Everything.

Before you turn it on

Text only people who asked to hear from you. Anyone who replies STOP goes on your stop list, and BlueBot cancels texts to them. Stop words
A text that can’t go yet waits with a hold rather than failing: quiet hours, your Mac away, a daily limit. Holds
ServiceTitan with BlueBot on the integrations page says what else the two do together.