Recipes

Moving from Twilio recipes

Swap a Twilio send for BlueBot’s and text from your own number instead of a rented one.

Three recipes for Moving from Twilio. 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 Moving from Twilio connects

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

Move a send from Twilio to BlueBot

Part	What it is
Trigger	Your code sends a text
Action	`POST /v1/messages`
Connects through	API

Steps

Replace the call to Twilio’s Messages API with POST /v1/messages.
Send the fields to and text where you sent To and Body, and drop From, since BlueBot sends from your own number.
Add an Idempotency-Key so a retried request never sends twice.

Map the fields

BlueBot field	Map it to
`to`	The person’s mobile number from Moving from Twilio. US numbers can leave off the +1.
`text`	Your appointment is confirmed for tomorrow at 10 AM. Reply here with any questions.
`metadata`	`source` set to `twilio`, 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: twilio-1042" \
  -d '{
    "to": "+15555550123",
    "text": "Your appointment is confirmed for tomorrow at 10 AM. Reply here with any questions.",
    "metadata": {
      "source": "twilio",
      "record_id": "1042"
    }
  }'

Test it

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

Move your inbound webhook

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

Steps

Add your endpoint in BlueBot as a webhook for message.received.
Read the sender and the words from the JSON body, where Twilio sent From and Body as form fields.
Check the webhook-signature header with your whsec_ secret in place of X-Twilio-Signature.

Map the fields

From BlueBot	Into Moving from Twilio
`data.from`	The phone number to find the person by in Moving from Twilio. It’s in E.164 (`+15555550123`); search by the last 10 digits if Moving from Twilio 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.

Move your status callbacks

Part	What it is
Trigger	A text you sent changes state
Action	Moving from Twilio acts on what BlueBot reports
Connects through	API

Steps

Put your own IDs in metadata when you send.
Subscribe to message.delivered, message.read and message.failed, each of which carries that metadata.
Read the hold on a queued text to see why it’s waiting, such as quiet hours.

Map the fields

From BlueBot	Into Moving from Twilio
`data.state`	`sent`, `delivered`, `read`, `failed` or `expired`, for a field or a filter.
`data.metadata`	The `record_id` you sent with the text, to find the record it was for.
`data.failure.reason`	Why a failed text didn’t go: `not_on_imessage`, `messages_refused` or `file_unavailable`.
`data.to`	Who the text was for.

Test it

Send one text to your own number, then look for the event. To try the step without sending anything, POST /v1/webhooks/{id}/test sends an example of any event type to your webhook.

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
Moving from Twilio with BlueBot on the integrations page says what else the two do together.