Delayed Messaging

When sending messages through Server API on behalf of a bot (or a real user), there may be times when immediate delivery will feel too abrupt to the recipient. It’s a dead giveaway that it’s not coming from a real person. In order to make artificial responses feel more realistic, you may want to simulate the time it normally takes a recipient to process something, start typing, and eventually send a reply. By including a schedule in your message, you can easily build experiences like that and customize them according to your needs.

The schedule object supports the following parameters:

Name Type Description
delay_in_seconds number The time in seconds (floating point) after which the message should be sent. Must be between 1.0 and 300.0.
typing_indicator_in_seconds number The duration in seconds (floating point) the sender appears to be typing. Must be between 1.0 and delay_in_seconds.

Note

typing_indicator_in_seconds is relative to the send time. For example, if you have a delay_in_seconds of 7.5 and typing_indicator_in_seconds of 3.3, the typing indicator will start after a 4.2 second delay.

HTTP request:

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

Example:

{
    "sender_id": "layer:///identities/8rEsAfaBYS",
    "parts": [
        {
            "body": "I have just the thing for you!",
            "mime_type": "text/plain"
        }
    ],
    "schedule": {
        "delay_in_seconds": 8.2,
        "typing_indicator_in_seconds": 3.8
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>/messages\
 -d '{"sender_id":"layer:///identities/8rEsAfaBYS","parts":[{"body":"I have just the thing for you!","mime_type":"text/plain"}],"schedule":{"delay_in_seconds":8.2,"typing_indicator_in_seconds":3.8}}'

Possible responses:

Message scheduled successfully | Status: 202 (Accepted)

Note

This is a slight departure from the 201 (Created) response you’d normally receive with ordinary non-scheduled messaging. You will not get a Message in the body of the response (the body is empty), since the Message will actually be created in the future.