Skip to main content

Send notifications

Section: DOC-CP-notifications-sending#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: DOC-CP-notifications-sending#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.

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

Response:

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

{
  "acknowledged": true,
  "status": "processed",
  "transactionId": "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: DOC-CP-notifications-sending#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.

{
  "events": [
    {
      "workflowId": "push-notification",
      "userId": "user-1",
      "payload": {"title": "Update", "body": "New feature available"}
    },
    {
      "workflowId": "push-notification",
      "userId": "user-2",
      "payload": {"title": "Update", "body": "New feature available"}
    }
  ]
}

Response:

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

{
  "results": [
    {"acknowledged": true, "status": "processed", "transactionId": "txn_1"},
    {"acknowledged": true, "status": "processed", "transactionId": "txn_2"}
  ]
}

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

Choose explicit recipients for an announcement​

Section: DOC-CP-notifications-sending#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: DOC-CP-notifications-sending#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.

{
  "transactionId": "txn_abc123"
}

Response:

Response example: Cancel a pending notification · Response fields.

{
  "cancelled": true,
  "message": "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: DOC-CP-notifications-sending#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: DOC-CP-notifications-sending#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.

{
  "workflowId": "activity-digest",
  "userId": "user-1",
  "payload": {
    "title": "Activity Update",
    "body": "New activity in your coaching plan"
  },
  "transactionId": "digest-event-123"
}

Response:

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

{
  "acknowledged": true,
  "status": "processed",
  "transactionId": "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.

{
  "transactionId": "digest-event-123"
}

Response:

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

{
  "cancelled": true,
  "message": "Digest event successfully cancelled"
}

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

Document ID: DOC-CP-notifications-sending. Section identities and revisions.