Skip to main content

Send notifications

Section ID: Guide/jbo2gqauoj#send-notifications

Build the “new coaching update” notification in the example below. Your application first saves the update in its conversation, then sends a short notice to the intended user. Opening the notice returns the user to that conversation.

Before sending, prepare a workflow whose template accepts the shown payload variables, register the recipient’s device for push, and decide which updates should be grouped into a digest. Replace sample identifiers with the workflow, user and conversation your application has actually created.

Use the prepared workflow and supply the message variables it expects. See workflow and payload meaning.

Call these operations from your backend with a verified key or configured standalone JWT. They do not enforce separate admin roles or recipient permissions. Check that the requesting person may send this notification to this recipient before making the call; an accepted token or supplied user ID is insufficient.

1. Notify the user after the update is saved​

Section ID: Guide/jbo2gqauoj#send-to-one-user

Resolve the recipient and conversation from the authenticated application event. Send once for that intended notification, keep its transaction reference, and use the reference for delivery checks or cancellation. Validate the deep link in your app when it is opened; the link itself grants no access.

Request example: Send a notification to a user · Request fields.

See Send a notification to a user for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • workflowId: text push-notification.
  • userId: text recipient-user-id.
  • payload.title: text New Message.
  • payload.body: text You have a new coaching update.
  • payload.deep_link: text travila://conversation/conv_abc.
  • transactionId: text optional-idempotency-key.

Response:

Response example: Send a notification to a user · Response fields.

See Send a notification to a user for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • acknowledged: boolean true.
  • status: text processed.
  • transactionId: text txn_abc123.

Use the send contract for field meanings and acceptance details. Save the returned transaction before following delivery.

Expected result: the trigger is acknowledged and has a transaction reference. Next, inspect channel delivery and open the notice on the recipient’s device. Reconcile an uncertain send using the original reference before issuing a replacement; acceptance, delivery and opening are separate outcomes.

Variant: announce the same change to selected users​

Section ID: Guide/jbo2gqauoj#send-to-many-users

Split a larger audience into supported batches, and retain a result for each intended recipient:

Request example: Send a notification to multiple users · Request fields.

See Send a notification to multiple users for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • events[0].workflowId: text push-notification.
  • events[0].userId: text user-1.
  • events[0].payload.title: text Update.
  • events[0].payload.body: text New feature available.
  • events[1].workflowId: text push-notification.
  • events[1].userId: text user-2.
  • events[1].payload.title: text Update.
  • events[1].payload.body: text New feature available.

Response:

Response example: Send a notification to multiple users · Response fields.

See Send a notification to multiple users for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • results[0].acknowledged: boolean true.
  • results[0].status: text processed.
  • results[0].transactionId: text txn_1.
  • results[1].acknowledged: boolean true.
  • results[1].status: text processed.
  • results[1].transactionId: text txn_2.

Confirm each intended recipient separately using the per-event result.

Choose explicit recipients for an announcement​

Section ID: Guide/jbo2gqauoj#broadcast-to-everyone

To reach an explicitly selected group, use topics with authorized subscriber membership, or send a bulk request with explicit recipients. This guide does not provide a tenant-wide broadcast operation.

Recover: withdraw an update before delivery​

Section ID: Guide/jbo2gqauoj#cancel-a-pending-notification

Requests cancellation through the configured provider. Whether a delayed, digested or queued delivery can still be stopped depends on its provider state; an accepted cancellation is not proof that every delivery was prevented. Already-delivered messages cannot be recalled. Inspect the returned result and reconcile delivery status where available.

Request example: Cancel a pending notification · Request fields.

See Cancel a pending notification for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • transactionId: text txn_abc123.

Response:

Response example: Cancel a pending notification · Response fields.

See Cancel a pending notification for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • cancelled: boolean true.
  • message: text Notification successfully cancelled.

Check the cancellation result before telling the user the notice was withdrawn.

Variant: send a reminder at the user’s chosen time​

Section ID: Guide/jbo2gqauoj#scheduling-and-delays

There is no send-at-a-time or send-after-a-delay endpoint on this API. Deferred delivery comes from one of two places:

  • Inside a workflow — add a delay step to the workflow definition. Every trigger of that workflow then waits, and manage/cancel with the transaction ID requests cancellation; a race with delivery can still leave an already-dispatched message.

  • Outside the workflow — create a scheduled job that calls manage/send when it runs. Use this for calendar-shaped sends (0 9 * * 1-5, a one-off timestamp, a repeating interval) and anything a user can reschedule.

Variant: combine a busy conversation’s updates into one notice​

Section ID: Guide/jbo2gqauoj#digest--batching

Use a digest when several updates can wait for one summary. Configure the grouping and delivery window in the workflow, then feed each eligible update into that digest. Keep individual event references so a retracted update can be removed while the digest is still pending.

A digest collapses many events into one message. The window and grouping are configured in the workflow's digest step; this endpoint just feeds events into it.

Request example: Send a notification with digest aggregation · Request fields.

See Send a notification with digest aggregation for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • workflowId: text activity-digest.
  • userId: text user-1.
  • payload.title: text Activity Update.
  • payload.body: text New activity in your coaching plan.
  • transactionId: text digest-event-123.

Response:

Response example: Send a notification with digest aggregation · Response fields.

See Send a notification with digest aggregation for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • acknowledged: boolean true.
  • status: text processed.
  • transactionId: text digest-event-123.

Remove a single event from a digest that has not yet been delivered. Once the digest has gone out this is a no-op rather than an error.

Request example: Cancel a pending digest event · Request fields.

See Cancel a pending digest event for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • transactionId: text digest-event-123.

Response:

Response example: Cancel a pending digest event · Response fields.

See Cancel a pending digest event for the request and response contract. The following values illustrate the choices for this example; replace identifiers with your own authorized values.

  • cancelled: boolean true.
  • message: text Digest event successfully cancelled.

Confirm the digest cancellation result; if delivery already happened, show that outcome instead of promising withdrawal.

Document ID: Guide/jbo2gqauoj