Sending List and Time Pickers

Interactive messages provide a range of functionality, from letting the user select an item from a list to scheduling an appointment. Messages for Business comes with a set of interactive messages that you can use, or you can create and use custom interactive messages. When sending an interactive message to the user, set the type field to interactive. For more information, see List Picker Message and Time Picker Message.

In this section's exercises, you'll learn how to provide a rich user experience using list and time pickers.

Exercise: Sending a Text-only List Picker

In this exercise, you generate a request ID to send a text-only list picker payload to trigger an item selection in the Messages app.

The request ID ensures that the requests and responses are properly paired. In situations where an agent sends multiple interactive messages, the MSP may receive responses out-of-order or no response for some requests. The request ID ensures that the responses match the corresponding request.

TIP When parsing the list picker response, note that the selected options of the list picker are sent back to the MSP as a subset of the options in the list picker.

Complete the following tasks:

  1. Generate a request ID.
  2. Assemble list picker item configuration with optional sections.
  3. Send a message with payload.

Perform the following tasks on your test server:

  1. Locate the code zip folder and unzip it.
  2. Open and edit the 06_send_text_list_picker.py file by inserting the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.
  3. Save and run the 06_send_text_list_picker.py file.

Expected MSP server response

Messages for Business server return code: 200

If your custom message isn't being shown on your client device, use the following matrix identifying the type of messages sent and how they appear in the UX.

Message Type Reply Message Response Message
Text Picture
List Picker ✓ ✓

Exercise: Sending a List Picker with an Image

In this exercise, you send a list picker with an image payload to trigger an item selection in the Messages app. When a user responds to a list picker with a text message, the two messages are delivered separately without association.

TIP If you cannot see the images in interactive message bubbles, make sure your image DPI is set to the common DPI setting for iOS, which is 72.

Complete the following tasks:

  1. Base64-encode the image data.
  2. Assemble a list picker payload with the encoded image data.
  3. Send a list picker message with the payload.

Perform the following tasks on your test server:

  1. Locate the code zip folder and unzip it.
  2. Locate and edit the 07_send_list_picker_with_image.py file by inserting the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.
  3. Save and run the 07_send_list_picker_with_image.py file.

Expected MSP server response

Messages for Business server return code: 200

Exercise: Sending a List Picker with Multiple Images

In this exercise, you send a list picker with multiple images and receive a data reference for use in the next exercise, Exercise: Sending a List Picker Using a Data Reference.

Complete the following tasks:

  1. Perform iteration over a dictionary containing three image files, encrypting each for transmission.
  2. Use references in JSON to specify which images go with each section of the list picker.
  3. Print out the data reference in JSON format for use in the next exercise, Sending a List Picker Using a Data Reference.

Use the same List Picker from Exercise: Sending a List Picker with an Image. Note the references specify multiple images. You use a dictionary to match the image identifiers in JSON to the file names. Then loop through the images to encrypt each one and add it to the payload.

This example includes an additional header parameter, include-data-ref, that is set to true. This setting directs the Messages for Business server to return the data reference. Because HTTPS header key-value pairs are string only, set the value of true to a four character string.

Perform the following tasks on your test server:

  1. Locate and edit the 08_send_list_picker_with_multiple_images.py file by inserting the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.
  2. Save and run the 08_send_list_picker_with_multiple_images.py file.
  3. Save the data reference from the output to use in later exercises.

Expected MSP server response

Messages for Business server return code: 200
Messages for Business server response body:
{
    "dataRef": {
        "bid":"<bid save for next exercise>",
        "owner":"<owner save for next exercise>",
        "url":"<url save for next exercise>",
        "size":"<size save for next exercise>",
        "signature":"<signature save for next exercise>",
        "signature-base64":"<signature-Base64 save for next exercise>",
        "title":"Select Produce",
        "dataRefSig":"<dataRefSig save for next exercise>"
    }
}

Exercise: Sending a List Picker Using an InteractiveData Reference

An InteractiveData Reference (IDR) in Messages for Business is like a super-charged URL. An IDR points to a set of large media assets. These media assets are usually 10KB, but can be 100MB or more. The IDR pointer is easier to use rather than expending the bandwidth to upload or download assets. It conforms to the JSON standard in a form that is unique to Messages for Business.

The IDR allows you to send the list picker using an abbreviated handle instead of uploading all the attachments again.

In this exercise, you reuse a previous interactive data reference sent in Exercise: Sending a List Picker with Multiple Images, and assumes that you got the data reference from the response. Make sure the dataRefSig field is present in the data reference.

Perform the following tasks on your test server:

  1. Locate and edit the 09_send_list_picker_with_data_ref.py file.
  2. Insert the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.
  3. Insert the interactive_data_ref, located towards the bottom of the file, with the output data reference from Exercise: Sending a List Picker with Multiple Images.
  4. Save and run the 09_send_list_picker_with_data_ref.py file.

Expected MSP server response

Messages for Business server return code: 200

Exercise: Sending a Time Picker

This exercise sends a message payload to trigger a time picker in the Messages app on the user's device.

When setting the times for your list picker, the start date can't be earlier than the current date/time, otherwise the times are removed from the time picker. If all items in the time picker are for past times, then the device displays an empty time picker with a message "No times available."

You can have the following types:

  • Long duration items, even extending to days long
  • Zero time length duration items, use this feature with discretion
  • Across different days, different months, or different years

Complete the following tasks:

  1. Generate time picker request ID.
  2. Assemble time picker configuration with or without timezone offset.
  3. Send a message with a payload.

Sending a Time Picker Using the User's Timezone

This example sends a time picker for an event in San Francisco to a user in New York. The event occurs in San Francisco on 2020-10-15 at 10:00am (PDT: GMT-7 hours), and you want the user in New York (EDT: GMT-4 hours) to view the time picker as 2020-10-15 at 1:00pm.

Sending the time of an event requires you to convert the event time to GMT, 2020-10-15T17:00+0000, and use it as thestartTime value. In this case, you don't set the timezoneOffset value.

On your server

  1. Locate and edit the 10_send_time_picker_with_user_timezone.py file by inserting the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.

  2. Save and run the 10_send_time_picker_with_user_timezone.py file.

Sending a Time Picker Using a Fixed Timezone

This example sends a time picker for an event in San Francisco to a user regardless of their timezone.

Setting the time of the event regardless of the user's timezone requires you set the startTime value as GMT, 2020-10-15T17:00+0000. And you need to set a timezoneOffset, in this case -420 minutes for San Francisco PDT.

With the timezoneOffset value set, the user's device always displays the time where the event occurs without converting the time to the user's timezone.

Perform the following tasks on your test server:

  1. Locate and edit the 11_send_time_picker_with_fixed_timezone.py file by inserting the destination_id, located towards the bottom of the file, with the source_id from the output in Exercise: Receiving a Text Message.

  2. Save and run the 11_send_time_picker_with_fixed_timezone.py file.

Expected MSP server response

Messages for Business server return code: 200

If your custom message doesn't show on your client device, use the following matrix identifying the type of messages sent and how they appear in the UI.

Message Type Reply Message Response Message
Text Picture Text
Time Picker ✓ ✓