Batch Messaging

Building on the power of Delayed Messaging, this feature caters to developers who need to send batches of messages to a conversation either as a bot or as a pre-packaged “flow.” Each message in the batch can specify a delay, complete with a typing indicator duration as desired for realism, yielding the effect of a live participant in the conversation typing a series of messages over a period of time spanning seconds to several minutes. Throw full support for Rich Content into the mix, and you can imagine building some powerful messaging flows, all with the convenience of just a single Server API request.

To get started, simply post an array of Message objects to the same familiar endpoint. Order of delivery is guaranteed to reflect order of appearance in the array.

Note

Each Message's delay_in_seconds is relative to the prior Message in the array. Unlike sending a single delayed message, there is no minimum delay when sending a batch. This allows you to send one message immediately, followed by some number of messages to follow a short time thereafter.

Below is an example “flow” where a bot sends an immediate response, followed by a few messages each having a delay with a period of simulated typing.

HTTP request:

POST/apps/:app_uuid/conversations/:conversation_uuid/messages

Example:

[
    {
        "sender_id": "layer:///identities/ReservationBot",
        "parts": [
            {
                "mime_type": "text/plain",
                "body": "Thanks for your inquiry. Let me see what rooms we have available..."
            }
        ]
    },
    {
        "schedule": {
            "delay_in_seconds": 12.0,
            "typing_indicator_in_seconds": 5.0
        },
        "sender_id": "layer:///identities/ReservationBot",
        "parts": [
            {
                "mime_type": "text/plain",
                "body": "Here's one option, our King Standard Suite."
            },
            {
                "mime_type": "image/png",
                "content": {
                    "id": "layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67",
                    "size": 24832
                }
            }
        ]
    },
    {
        "schedule": {
            "delay_in_seconds": 8.5,
            "typing_indicator_in_seconds": 4.2
        },
        "sender_id": "layer:///identities/ReservationBot",
        "parts": [
            {
                "mime_type": "text/plain",
                "body": "The King Imperial Suite is also available that night."
            },
            {
                "mime_type": "image/png",
                "content": {
                    "id": "layer:///content/a753ef3a-c8f1-11e7-bef1-80e6501cbcbc",
                    "size": 26071
                }
            }
        ]
    },
    {
        "schedule": {
            "delay_in_seconds": 7.0,
            "typing_indicator_in_seconds": 3.8
        },
        "sender_id": "layer:///identities/ReservationBot",
        "parts": [
            {
                "mime_type": "text/plain",
                "body": "Would either of these rooms interest you?"
            }
        ]
    }
]

Possible responses:

Message batch scheduled successfully | Status: 202 (Accepted)

The following restrictions apply:

  • The posted array must not be empty.
  • Up to 12 Message objects in the array are supported.
  • The overall delay of the batch (i.e. when the very last message is sent) must not exceed 5 minutes.
  • If any Message in the batch is invalid, the entire batch will be rejected.