Sending pushes

A function that declares push in its function.yaml has ctx.push.send. The call answers at once; backd’s workers deliver.

export default async function (ctx) {
  const r = await ctx.push.send({
    user: order.owner,                  // or users: [...], or audience (below)
    kind: "order-shipped",              // a template of the realm, or title + body (raw)
    data: { order_no: order.no, eta: "tomorrow" },
    group: `order-${order.id}`,
    priority: "high",
  });
  // r = { send_id: "ps_…", users: 1, jobs: 1, queued: 1, limited: 0, no_devices: 0 }
}

# function.yaml
push: true                              # or push: { kinds: [order-shipped], audience: false }

Who#

Give exactly one of:

Gating by consent#

requires_consent: "marketing" skips the users who don’t hold that consent: they are counted as no_consent in the result and in the send’s record, and they don’t count against their limits. It enforces a withdrawal even when the function’s own code forgets to check, and works with user, users and audience alike.

await ctx.push.send({ audience: "all", title: "New arrivals", body: "…", requires_consent: "marketing" });
// { …, queued: 980, no_consent: 20 }

A consent the realm doesn’t declare is 400 invalid_push_message.

A list of a million ids can’t go through a function call, which is what audience is for: backd pages through the matching users itself, so the audience is fixed batch by batch.

What#

kind names a template; without it, title and body are the text (a raw message). The other fields (link, data, badge, sound, group, ttl, priority, silent, platform) are described with the message. data values are strings. The message is rendered in every language of the realm and checked before anything is queued; a function that can’t send gets an error it can show or let end it:

What backd does with it#

flowchart LR
    F[ctx.push.send] --> S[send record]
    S --> P[planner: pages an audience]
    P --> B[batch: up to 1,000 users]
    S --> B
    B -->|limits, devices, language| U[delivery unit: up to 100 users]
    U --> W[worker: one request set per provider]

• A batch applies the limits, resolves each user’s devices (only those whose session is still alive), picks each user’s language and makes delivery units of up to 100 users. A send of up to 1,000 users is planned during the call, so the answer already says how many were limited or had no_devices; larger sends answer null for those and the counts appear on the send as batches run.
• A delivery unit carries device ids, never tokens: the worker loads and decrypts them when it runs. Each device gets a result:

A device the sender gave no result for counts as failed. A failure of the call as a whole (the network, rejected credentials) retries the whole unit under push.delivery.retry; devices already delivered in that attempt may get the push twice. After the last attempt, what is still pending counts as failed.

• Idempotent planning. If a worker dies mid-batch, the batch runs again from where it was: units have deterministic ids, so none is made twice and nobody is charged twice.

Limits#

Per user, push.limits.per_user (5 a minute and 24 a day by default), counted once per push however many devices the user has. Silent pushes count too, and nobody is exempt: there is no urgent flag and no administrator bypass. A user over their limit is skipped and counted as limited; there is no per-call cap, so very large sends are kept in check by batching, these limits and push.delivery.parallelism.

wait#

wait: true waits for the totals within the function’s time limit and returns what it has then, with sent, invalid, failed and completed. Don’t use it for large sends.