Send texts

On Boost, your integration can send texts from your SimpleVox numbers: appointment reminders from your booking system, a follow-up when a job closes in your CRM, a note to a customer when a part arrives. Each text lands in the number’s conversation, so the whole team sees it next to the customer’s calls and replies.

Before you send

• A Boost plan. Sending over the API is part of Boost. See Plans and billing.
• A token with Send SMS. Create a personal API token and tick Send SMS under Write permissions. See Authentication.
• Allowance or credits. Texts you send through the API count toward Boost’s monthly allowance of 500 segments per person, shared with your AI tools. Past it, the billing owner buys credits in Settings → Plan & billing. See AI tool and API usage.
• A number that can send. The number needs an approved A2P 10DLC registration with the number attached, the same as texting from the app. The token’s person needs access to the number, and the token must include it.

Send a text

Send the number to text from as phone_number_id (history and activity entries include it), the customer’s number as to in E.164 format, such as +12025550142, and the text as body. Each request sends one text to one person. Pictures aren’t accepted. Reference: Send a text.

curl https://api.simplevox.app/v1/messages \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "phone_number_id": "5c0e8a7d-2f41-4b6a-9e3d-7a1c4b8f2e90",
    "to": "+12025550142",
    "body": "Hi Mary, your water heater part is in. Reply with a day that suits and we'll book the install."
  }'

A successful request returns 202 Accepted with the saved message. Trimmed:

{
  "data": {
    "id": "e3b7c1a4-9d2f-4e6b-8a05-3f1c7d9e2b84",
    "conversation_id": "a81d4f60-7c3e-4b29-9f1a-6e2d8c0b5a37",
    "state": "queued",
    "error_code": null,
    "provider_segments": 1
  }
}

202 means SimpleVox saved the text and handed it on, not that it reached the customer’s phone. Keep the id to follow it.

Follow a text

Read the message to see its current state, along with any error_code. Treat state as open-ended. You can also replay changes on the numbers your token can read. Reference: Retrieve a message.

A text you sent stays readable after a plan change, as long as you still have access to its number.

Pictures and files

Reading a message also returns its pictures and files in media, including ones customers send you. A picture message can arrive before SimpleVox has saved its pictures, so media.state starts as pending. Read the message again, or replay changes until its content_state is media_available. Then each entry in media.attachments has a signed download_url that works without your token until expires_at, about 15 minutes later:

curl -o attachment "$DOWNLOAD_URL"

Anyone with the link can open it until then, so don’t log or share it, and read the message again for fresh links. preview_url shows a JPEG, PNG, GIF or WebP image instead of downloading it. To get a fresh link for one attachment, request it with your token and follow the redirect (curl -L). Reference: Retrieve a message, Download an attachment.

Retries

Every send needs an Idempotency-Key. If a request times out or the response is lost, send it again with the same key and the same body. SimpleVox returns the text it already saved instead of sending a second one.

Caution

Never retry an uncertain text with a new key. A new key is a new text, and the customer may get it twice.

• The same key with a different body is refused with 409.
• Keys belong to the token that used them.
• If state is uncertain, SimpleVox couldn’t confirm the hand-off to the carrier. Don’t send again. Read the message or replay changes until it settles.

When a text isn’t sent, error.code says why, such as sms_registration_unavailable or messaging_allowance_reached. The reference lists every code this request can return; Handle errors covers what to do.

Send texts your customers expect

Carriers watch business texting closely. Text people who’ve asked to hear from you, about the job they booked. Customers who reply STOP are opted out of texts from that number, and sending to them returns 403 with sms_recipient_opted_out until they reply START. See Texting and A2P 10DLC registration.