Implementing the Full SMS Lifecycle

Preview

This is part of the v2 API preview. Details may change before it is final. For the v1 API, see Implementing the Full SMS Lifecycle (v1).

A complete SMS integration does more than send. Every message goes through a lifecycle, and Connect records an event at 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 and Connect accepts it: sms.queued.
2. Delivery: The message is handed to the network (sms.sent), then delivered (sms.delivered) or not (sms.failed, with a reason).
3. Reply: The recipient replies: sms.received. 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: suppression.created. Future messages to them are not sent.

Every sms.* event carries the full message, so one handler can deal with all of them.

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 events. The walkthrough below uses its three simulated handsets:

Number	Behaviour
+447700900001	Delivered a couple of seconds after sending
+447700900002	Fails as an invalid number
+447700900003	Delivered, then replies

Walkthrough: a complete test integration

1. Choose how to receive events. Either create a webhook for sms.delivered, sms.failed, sms.received and suppression.created, or poll the events feed.

2. Test a delivered message. Send a message to +447700900001. You get sms.queued, sms.sent and then sms.delivered, with the message’s status of delivered.

3. Test a failed message. Send a message to +447700900002. You get sms.failed, with a reason of category invalid, code invalid_destination_address and retryable of false. 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 get sms.delivered, then sms.received with the simulator’s reply and a 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 get sms.received with the content STOP, then suppression.created with a source of stop. Any further messages to the number are not sent.

Note

While v2 is in preview, creating v2 webhooks has to be turned on for your workspace. Contact support to turn it on. The events feed works without it.

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 events 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. Replies to it arrive with a channel of sms.