Outbound Messaging

Overview

The system allows you to send outbound messages to a user, including an optional notification banner or alert. To initiate a message to a user’s device, your backend system makes a standard HTTP PUT request to our Messaging endpoint.

You must provide the following:

• Designated user’s username

• Authorization credentials

• Message payload

• Unique handle (such as a UUID or a primary key from your database)

The system then uses the provided handle to track the message lifecycle, allowing you to monitor events like read receipts or process direct replies.

Key Behaviors and Features

Beyond basic text delivery, the outbound API supports several key behaviors:

• Alerts and Custom Sounds: You can trigger push notifications to alert the user of a new message.

  • You can specify custom sounds (such as a honk or a guitar) or choose to display a silent text banner.

The alert and sound properties interact in the following ways:

• Text-to-Speech: You can include a custom text-to-speech announcement. If the user's device is locked or running turn-by-turn navigation, the app can read the announcement out loud safely.

• Timestamps and Sorting: You can explicitly set the composition timestamp to match your internal systems. This timestamp dictates how messages are sorted on the user's device. For groups of messages sent simultaneously, you can use sub-second precision to guarantee the exact display order.

• Message Retrieval and Link Regeneration: You can programmatically retrieve existing messages. This is particularly useful for regaining access to captured signature links.

  NOTE: If a signature link reaches its standard 7 day expiration, retrieving the message will automatically regenerate a new link with a refreshed expiration date.

• Message Deletion: You can explicitly delete a message via the API, which will immediately remove it from the platform and the user's mobile device.

  NOTE: Establish and adhere to a routine message retention policy. Delete older messages to ensure users interact only with current, active, and relevant messages.

Read and Delete Events

When a user reads a message, the system sends a payload containing a read_at timestamp. You can use this request as a signal to mark the message as read within your backend systems.

{
    "direction": "outbound",
    "username": "JDOE",
    "composed_at": "2026-01-16T16:34:12+00:00",
    "read_at": "2026-01-16T16:34:24+00:00",
    "message_type": "text",
    "body": "Test."
}

Similarly, if a user deletes a message, the payload will include a deleted_at timestamp. If your integration does not require tracking these read or delete events, you can simply acknowledge the notification and take no action by returning an empty HTTP 200 response.

Resources

API

• Messaging