Implementing the Full SMS Lifecycle

A complete SMS integration does more than send. Every message you send goes through a lifecycle, and Connect tells you about each stage so your application can react to it.

You can build and test every stage for free, before your workspace goes live, using the Phone Simulator.

The lifecycle at a glance

1. Send: You send a message with the API and Connect accepts it.
2. Delivery receipt: The delivery status changes (for example Delivered or Failed) and Connect sends you an SMS Delivery Receipt webhook.
3. Reply: The recipient replies and Connect sends you an Inbound SMS webhook, or you pick it up with Inbound SMS Synchronisation. See Replies for how recipients can reply.
4. Opt-out: The recipient replies STOP or unsubscribes, and Connect adds their number to your suppression list so future messages to them are not sent.

Testing with the Phone Simulator

The Phone Simulator is a set of fake phones that never touch a mobile network. Messages to them are free, work before your workspace goes live, and produce real delivery receipts, replies and webhooks. The walkthrough below uses its three simulated handsets:

Number	Behaviour
+447700900001	Delivered
+447700900002	Fails with error 300
+447700900003	Delivered, then replies

Walkthrough: a complete test integration

1. Set up a webhook endpoint. Add your endpoint in Settings → Webhooks and enable both the SMS Delivery Receipt and Inbound SMS events. See Webhooks.

2. Test a delivered message. Send a message to +447700900001. You will receive a delivery receipt webhook with DeliveryStatusStr of Delivered.

3. Test a failed message. Send a message to +447700900002. You will receive a delivery receipt webhook with DeliveryStatusStr of Failed and ErrorCode 300. Make sure your application handles it, for example by flagging the number as invalid.

4. Test a reply. Send a message to +447700900003 with a reply link. You will receive the delivery receipt, then an Inbound SMS webhook with the simulator’s reply and Channel of web.

5. Test an opt-out. Open the reply link from your message to +447700900003 (shown on the Phone Simulator page) in your browser, and reply STOP. You will receive an Inbound SMS webhook with the body STOP, and the number is added to your suppression list. Any further messages to it are not sent.

Tip

Remove the simulator’s number from your suppression list once you have finished testing opt-outs, so you can keep using it.

Going live

When your workspace goes live you can send to real phone numbers, and messages are billed. Your integration does not need to change, as real messages produce the same webhooks as the simulator.

If you want recipients to be able to reply by text message rather than through a reply link, you can add a dedicated virtual number once you are live.