Consent Docs
Open console

Send notice links from your own gateway

Fetch a notice campaign's links when a batch is ready, send them through your own mailer or SMS gateway, and act on the withdrawals people make.

How-to2 min readFor web, backend and mobile developers

Let your sender fetch a notice campaign's links as soon as a batch is ready, instead of downloading the file in the console. The product sends no messages: your mailer or SMS gateway does.

Before you start#

  • A notice campaign with people added.
  • A secret key with Read notice campaign links, for your sender (campaigns:links). Anyone holding a link can answer for that person, so give the scope to your sender's key only.
  • A webhook endpoint subscribed to campaign.batch_issued and campaign.withdrawn.

  1. When campaign.batch_issued arrives, read campaignId, batchId and download.path. The event never carries a link.

  2. Page through the links with the key, 1,000 at a time unless you set limit, up to 5,000.

    Node.jsJavaScript
    const base = `https://console.dpconsent.com/consent/sdk/v1/campaigns/${campaignId}`;
let after = null;
do {
  const query = new URLSearchParams({ limit: '5000' });
  if (after) query.set('after', after);
  const response = await fetch(`${base}/batches/${batchId}/links?${query}`, {
    headers: { Authorization: `Bearer ${process.env.PIEDAP_SENDER_KEY}` },
  });
  const page = await response.json();
  await queueMessages(page.links);
  after = page.next;
} while (after);
    Python
    import json
import os
import urllib.request

base = f"https://console.dpconsent.com/consent/sdk/v1/campaigns/{campaign_id}"
after = None
while True:
    query = "limit=5000" + (f"&after={after}" if after else "")
    request = urllib.request.Request(
        f"{base}/batches/{batch_id}/links?{query}",
        headers={
            "Authorization": f"Bearer {os.environ['PIEDAP_SENDER_KEY']}",
        },
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        page = json.load(response)
    queue_messages(page["links"])
    after = page["next"]
    if not after:
        break
    cURLShell
    CAMPAIGN="https://console.dpconsent.com/consent/sdk/v1/campaigns/$CAMPAIGN_ID"
curl "$CAMPAIGN/batches/$BATCH_ID/links?limit=5000" \
  -H "Authorization: Bearer $PIEDAP_SENDER_KEY"

  3. Match each link to your customer by reference, the key you gave the row, or by fingerprint.

  4. Send each url in the person's language, and keep the linkId with the message.

  5. Upload your sender's delivery report on the campaign in the console. There is no API for it.

The links of a batch can be read for 7 days after it is issued. Then the call answers 410 LINKS_NO_LONGER_AVAILABLE, and only new links can be issued.

Act on answers#

campaign.withdrawn arrives once a withdrawal on a link is applied. It names the campaign, the person's reference and the records withdrawn, in withdrawnConsentIds. Each record also sends its own consent.withdrawn. Stop processing for that person. A person with no record still sends campaign.withdrawn, with an empty list.

A withdrawal reaches only the records recorded under the person's first identifier, the Identifier column of the upload, or linked to it. Their other identifiers serve to leave out erased people and to find duplicates. An acknowledgement sends no webhook and changes no record.

Use your own domain#

Links can use your own domain, set as Link address on the campaign. Forward it to the deployment, keep the method and the form body, and do not log the path:

nginx.conf
server {
  server_name notice.example.in;
  access_log off;
  location / {
    proxy_pass https://consent.example.in/sdk/v1/n/;
    proxy_set_header Host consent.example.in;
  }
}

The deployment's own request log masks link tokens. For SMS, use the same domain in the message templates you registered.

Limits#

  • One address may open links 300 times in 10 minutes, and use 20 unknown links. People behind one mobile carrier address share these limits.
  • The key draws on the 60-a-minute budget for calls on a person.
  • Each page read is recorded in the audit log as CAMPAIGN_LINKS_READ, with the key's name.
  • Mode and the basis are labels you choose with your counsel. In this release, REQUEST_CONSENT and a basis of NO_CONSENT_ON_RECORD show the same page with the same two buttons and ask for nothing more. This wording awaits review by your counsel.

↑↓ to move, Enter to open