Send submissions via SMS

I like it and I think it's a model we can move towards in other places where there are currently blocking actions.

It would be good to get some confirmation from users like @barhin that this change would not cause too much confusion for data collectors.

Paging @Shobhit_Agarwal who had made some demos in that direction last summer and thinks a lot about UI in general and @tomsmyth who also thinks a lot about user experience and making sure the app is intuitive.

This is a really clever implementation, @joeldean! I love it. My only minor complaint is with the color choice and size of indicator. Red/green is a natural choice, but about 5% of the world's population is color blind, so I'd just go with a single color (Android blue) and stop it half way when it has failed.

No problem! Changes made. Good to see that you have an eye for accessibility :smiley:

Hi folks. Exciting stuff!

Regarding usability of @joeldean's design, I agree it's looking nice! A few comments:

  • I think this use case is probably going to push us into doing background sends instead of the synchronous modal-based kind. I don't think it would be very humane to do a mix of the two, and the SMS sends might take too long to be synchronous.
  • With that in mind, I think it would be good to produce a mockup of how SMS and HTTP sends would look together. Presumably the HTTP ones would be sent one at a time? So perhaps if you check multiple and hit send, they all get marked as 'Queued' and then change to 'Sending' and then they disappear if they succeed?
  • We further now need to consider how to report errors. That should be in the mockups. Detailed error information is really important for debugging so there needs to be a way to see the big gross error string that the server barfs back in the case of HTTP sends. There may be something similar for SMS?
  • The send medium (SMS/HTTP) should probably be listed on all items, just for consistency?
  • There is a proximity issue with the progress bars. It's not immediately clear whether they apply to the item below or above. Can they be brought into the interior of the list item?

Great work!

1 Like

Thanks for the feedback, Tom! Some really solid points.
I think the implementation of the Sms feature will be done by itself before any changes are made to the HTTP submission flow. So the user will still see a dialog when forms are being uploaded over HTTP. Is that correct @yanokwa?
I think it's best if we make sure these changes incrementally so we can have a good feedback loop going as the feature implementation goes along. Once we get the background sending working well for SMS from an architecture standpoint and that fits well with the UI then we can port it over to HTTP. Nonetheless, I know the introduction of SMS submission will have an impact on the user experience so considerations still have to be taken with how they work together.
I am going to do some brainstorming and share here how we could approach both mediums on the same page from a UI standpoint and share them here to continue the discussion.

I think it's best if we make sure these changes incrementally so we can have a good feedback loop going as the feature implementation goes along.

I am all for being incremental but I think it needs to be done in a way that does not sacrifice good UI principles. To me, sending a form is sending a form, and I would not expect a modal for one protocol and a background job for another. I think that would violate consistency and principle of least surprise.

One way to do it incrementally would just be to stick with the modal for now for both SMS and HTTP. Maybe observers just have to go to the toilet or get a snack while their form sends. Not the end of the world.

Another would be to first deploy the change to make HTTP a background job and then introduce SMS in a later build.

needs to be done in a way that does not sacrifice good UI principles.

I agree with you, @tomsmyth but in this case, the new feature is completely optional and requires user action to trigger (setting an SMS receiver in settings). I think adding SMS send support with the proposed new UI as an experimental feature will give an opportunity to get feedback on that UI before it gets rolled out to the more common HTTP sending. Initially I expect few organizations will be set up to receive SMSs and we can work specifically with those to get feedback.

@tomsmyth So I worked a new design that incorporates all the feedback you made mentioned. Here it is!

So the main ideas behind this design are :

  • There's a form icon depicting the current state of the form whether it be for a SMS or HTTP submission and if it's currently submitting, if it failed or if it's complete.

  • I utilized the card component from the Material Design spec so that the proximity of each form submission doesn't confuse the user as to which form does a progress bar belong.

  • The progress bar now has a percentage attribute so users can know exactly how far along the submission has gone.

So yes, I hope these changes can help to push us in the right direction as to how the SMS and HTTP submission can live together on one page. Even if we don't integrate background sending for HTTP in this iteration, this UI would be a good way to showcase the state of each submission type.
Feedback welcome!


Terrific work! This is much better. The use of cards is right on.

A couple small things:

  • When I saw the 85/100 fraction my first thought was that 85 out of 100 SMSes have been sent. Maybe just use "85%"?
  • Forms usually disappear once they're complete, right? So maybe here we show the check icon and 100% for a few seconds and then it fades away?
1 Like

I'm liking how this is coming along, @joeldean.

One thing I want to get onto the public record is that the clipboard icons feel a little too decadent! I would drop them and just use the blue circles. That is, use the available space to communicate unique status and do it in a way that our users, a lot of whom have uncorrected vision, can see easily.

@joeldean are you planing to make this app available at the google play store? I think it will be nice to have more feedback and inputs


Yes, this feature will be available in Collect and there will be a beta period where everyone can offer feedback.

Great! @yanokwa


Hey everyone! Need some feedback! So at first, the Sms Submission feature was just accounting for sent messages meaning, Collect was just tracking whether a message was sent successfully or not and displaying the progress likewise. Due to some discussions on the issue ( delivery reports have now been included therefore the way how the status message is modeled is being refactored. What I want to know is, how should this message be presented to track all the different states that could occur due to sent and delivery SMS events being provided to the app. Some examples.

Say I am sending a form that gets converted to 4 text messages. 3 of them are sent, 2 are delivered and one isn't delivered. That's the most complex mix of states I can think of taking place. What do you think is the best way to summarize this?

Should it be "3 of 4 messages were sent, Two (2) delivered and one (1) failed at 11:24 PM, June 1, 2018."

So when the user sees this, they would know they could press retry and the one that failed would resent. Right?

Also for messages that aren't delivered by the network should the user be able to resend those messages? When a user hits the retry button what should happen in the case of a message that's not delivered versus one that fails? I am thinking to just do a retry in both cases.

Eg. 2
How does this wording for the rest of possible states sound?

  1. All messages were sent and delivered at 11:24 PM, June 1, 2018.
  2. All messages were sent but only two were delivered at 11:24, PM, June 1, 2018.

or should it just be phrases

  1. 4 of 4 messages sent and delivered at 11:24 PM, June 1,2018.
  2. 4 of 4 messages sent and 3 delivered at 11:24 PM, June 1, 2018.

Incorporating delivery reports is :+1:. But agreed that it's tricky to know how seriously to take them. Does anyone have a sense of how reliable delivery report sending and receiving is on networks that support them? In other words, is not receiving a delivery report more likely to mean the message wasn't delivered or that the delivery report itself failed?

One more case to consider which we discussed on the GitHub issue is that not all networks send delivery reports. Your approach of not automatically re-sending and just letting the user decide what they want to do with the information sounds good. For the case where not a single delivery report is received, are you thinking you'll write something like "No delivery report received" or not say anything about delivery reports? I lean towards not including text about delivery reports. That seems the least confusing.

To me, the most compelling reason to read delivery reports is to get the header identifier for the submission to match that with the instanceID. I would be ok with not surfacing delivery information in the UI since I'm not sure it's all that meaningful and it could be quite confusing. Like you said, @joeldean, if I didn't get any or all delivery reports, do I resend? It's really not clear.

Currently a user can resend the same submission over HTTP over and over again and it's up to the receiving server to handle that gracefully. Once a form has been sent over HTTP it disappears from the main Send Finalized Form view. To see it, a user needs to tap the overflow menu button, Change View and then Show Sent and Unsent Forms. So the big question to me is if and when to similarly hide an SMS submission. When all messages are successfully sent? When all are successfully delivered (may never happen if the network does not send delivery reports)? Never? I am really not sure. Anyone else on this thread?

If I select a form for which certain messages failed to send and tap send, it seems clear only the failed messages should resend. As @joeldean points out, the other cases are some messages sent but not delivered and all messages sent and delivered. In the case where all were sent and delivered, it seems pretty clear a resend should send all. I'm again not sure what to do with some messages sent but not delivered. We could bypass the issue by only using the delivery reports for IDs and not surfacing delivery information in the UI.

I think the shorter the messages the more likely users are to read them fully. What do other think of 3/4 messages sent. 2/4 delivered. 1/4 failed?

1 Like

I also love how this feature is coming along! I recently had a discussion with someone from a big cell service company about large-scale text surveys and they had made the experience that multi-part SMS may arrive out of order.

I just wanted to confirm that our implementation would be able to deal with multi-part submissions arriving in an order different from how they were sent?

1 Like

On the Collect side it wouldn't be a problem. Even if delivery reports end up being reported it won't matter what order those come back in.

It will be up to the receiving end to handle order for data presentation and further analysis. Any service natively capable of receiving multi-part SMS (e.g. Android/iOS default messaging apps, Twilio and most other SMS gateway services) do this implicitly.

Those building custom receiving solutions may need to read the user data header and recreate the order. If they use an API like Twilio's this will be done seamlessly.

Hey everyone! I have an idea about how delivery reports could be added to Sms Submissions. One thing I know we have all become accustomed to is being able to see status updates on each individual message whether it's in Slack, Messenger or WhatsApp so what I am proposing is somewhat or a pop up but more along the lines of this component called a Bottom Sheet that shows all the messages being sent and the state on each of them. So if it was delivered, it would show that. If it failed that would be shown as well. This solves a ton of issues we are currently having with just displaying a single status message in each instance item/row. These are :

  1. Users would be able to drill down and see the individual statuses of each message they are sending and the content of that message. Also, each message would be tagged with an id received from the delivery report so that it can be cross-referenced with the recipient.
  2. The main list would only show a generalized status message so the UI/UX isn't cluttered and if a user wants to have a deeper understanding of what's taking place they could perform a long press to trigger the Report Pop Up.
  3. This pop up could also work for Http/Google submissions, where a trail could be shown for errors and successes, so this ties into a conversation we were having in Slack about submission history.

So yes if we all agree that this approach could work, I would do a mockup and I think we could tackle this in a separate PR once we put a beta of the current implementation out there or we could add a version of this to it if it's something we all like.

1 Like

The first beta for v1.16.0 is rolling out now and includes SMS support! Please learn more about the beta program and join to try this out. There is a form called SMS Test on the default server.

You will only be able to actually send messages from a device with a SIM. In server settings, change "Send submissions via" to SMS and send a destination phone number. This can be any number that receives text messages.

The additions to the form specification are described here. XLSForm support will be coming soon.

Some needed feedback:

  • Are the changes to the form sending screen easy to understand without retraining?
  • Are the settings clear?
  • Does the text message format work for you?

Some bugs we are aware of that still need to be worked out:

  • Order of forms can change once one is sent
  • Saved forms can't be edited

Paging @TSC.


SMS submission is now available in ODK Collect v1.16 and documented at! Thanks to @joeldean and all who have participated in the conversation.

There are a number of additions that are being considered for this including auto-send, functionality to let the enumerator choose the destination on submission, and functionality to make it easier for enumerators to re-submit a form sent by SMS to a server once they have connectivity. If any of these features are important to you, please open up new topics in the features category to discuss your use case and how you would use them.