---
title: "Send a signing link by WhatsApp or SMS"
description: "Deliver the signing link yourself over WhatsApp or SMS with custom delivery, a short ceremony URL and a handler that sends it when the envelope starts."
canonical: "https://signatureapi.com/docs/cookbook/whatsapp-link"
source: "https://signatureapi.com/docs/cookbook/whatsapp-link.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:17:27Z"
---

# Send a signing link by WhatsApp or SMS

Deliver the signing link yourself over WhatsApp or SMS with custom delivery, a short ceremony URL and a handler that sends it when the envelope starts.

_Last verified against API version 1.18.0._

SignatureAPI sends no email in this flow. You create the envelope with a custom ceremony and a short URL, then send the link through your own WhatsApp or SMS account when the signing ceremony opens.

Custom authentication records how you identified the signer (here, the provider name and phone number in the audit log). `delivery_type: none` stops the signed copy from being emailed to this recipient. See [custom authentication](https://signatureapi.com/docs/api/guides/how-to/custom-authentication) and [short ceremony URLs](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url#short-ceremony-urls).

## Send the link when the envelope starts

The ceremony opens when the envelope is `in_progress`, which is the `envelope.started` event. Subscribe an endpoint to it, fetch the envelope, and send `recipients[].ceremony.url`. The phone number comes from your own records.

```javascript WhatsApp
import express from "express";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.SIGNATUREAPI_WEBHOOK_SECRET);
const app = express();

app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.sendStatus(400);
  }
  if (event.type !== "envelope.started") return res.sendStatus(200);

  const api = await fetch(`https://api.signatureapi.com/v1/envelopes/${event.data.envelope_id}`, {
    headers: { "X-API-Key": process.env.SIGNATUREAPI_KEY },
  });
  const envelope = await api.json();
  const url = envelope.recipients.find((r) => r.key === "customer").ceremony.url;

  // Cloud API: a message to a customer you have not written to in the last 24 hours must be an approved template.
  const send = await fetch(
    `https://graph.facebook.com/${process.env.WHATSAPP_API_VERSION}/${process.env.WHATSAPP_PHONE_NUMBER_ID}/messages`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        messaging_product: "whatsapp",
        to: process.env.CUSTOMER_PHONE, // digits with country code, from your records
        type: "template",
        template: {
          name: "signing_request", // your approved template, with one {{1}} body variable
          language: { code: "en_US" },
          components: [{ type: "body", parameters: [{ type: "text", text: url }] }],
        },
      }),
    },
  );
  res.sendStatus(send.ok ? 200 : 500); // a 500 makes SignatureAPI retry the event
});

app.listen(3000);
```

```python SMS (Twilio)
import os

import requests
from flask import Flask, request
from standardwebhooks import Webhook
from twilio.rest import Client

wh = Webhook(os.environ["SIGNATUREAPI_WEBHOOK_SECRET"])
twilio = Client(os.environ["TWILIO_API_KEY"], os.environ["TWILIO_API_SECRET"], os.environ["TWILIO_ACCOUNT_SID"])
app = Flask(__name__)


@app.post("/webhooks/signatureapi")
def handle():
    try:
        event = wh.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 400
    if event["type"] != "envelope.started":
        return "", 200

    api = requests.get(
        f"https://api.signatureapi.com/v1/envelopes/{event['data']['envelope_id']}",
        headers={"X-API-Key": os.environ["SIGNATUREAPI_KEY"]},
    )
    api.raise_for_status()
    url = next(r for r in api.json()["recipients"] if r["key"] == "customer")["ceremony"]["url"]

    twilio.messages.create(
        to=os.environ["CUSTOMER_PHONE"],  # E.164, from your records
        from_=os.environ["TWILIO_FROM"],
        body=f"Please sign your Service Agreement: {url}",
    )
    return "", 200
```

- **Retries can repeat the message.** A failed delivery is retried and the same event can arrive twice. Record the event `id` you handled and skip repeats, so the customer isn't texted twice. See [duplicate deliveries](https://signatureapi.com/docs/api/webhooks#duplicate-deliveries).
- **Verify first.** Use the raw body. See [verify the signature](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks#verify-the-signature).
- **Messaging rules are the provider's.** WhatsApp templates need Meta's approval ([template overview](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview)). For SMS see the Twilio [Message resource](https://www.twilio.com/docs/messaging/api/message-resource).

## Related

- [Send signing links via SMS](https://signatureapi.com/docs/api/guides/use-cases/sms-signing-link)
- [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url)
- [Envelope events](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopestarted)

### Example: Custom delivery, short link

No email is sent. Your app sends the short link.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "documents": [
    {
      "key": "agreement",
      "title": "Service Agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "customer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "customer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "delivery_type": "none",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "WhatsApp",
            "data": {
              "phone": "+1-555-867-5309"
            }
          }
        ],
        "url_variant": "short"
      }
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement",
  "label": null,
  "message": null,
  "status": "processing",
  "mode": "test",
  "routing": "sequential",
  "language": "en",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "attestation": "none",
  "branding": {
    "logo": null,
    "accent_color": "#2463eb",
    "email": {
      "from": "noreply@signatureapi.com",
      "footer": null,
      "logo_position": "left"
    }
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "topics": [],
  "metadata": {},
  "documents": [
    {
      "id": "doc_4YvlxUZN28CeonDq6rTbvk",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "agreement",
      "title": "Service Agreement",
      "page_count": 2,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
      "format": "pdf",
      "fixed_positions": [],
      "places": [
        {
          "key": "signer_signs_here",
          "type": "signature",
          "recipient_key": "customer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "customer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "custom",
            "provider": "WhatsApp",
            "data": {
              "phone": "+1-555-867-5309"
            }
          }
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "short",
        "url": "https://sign.signatureapi.com/s/BgnexxxxxxxxIbRi"
      },
      "delivery_type": "none",
      "ceremony_creation": "automatic",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "completed_at": null,
      "status_updated_at": "2026-11-02T14:03:11.000Z"
    }
  ],
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "name": null,
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "type": "standard",
    "status": "pending",
    "url": null,
    "language": "en",
    "timezone": "UTC",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "agreement"
    ],
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null
  },
  "captures": {},
  "snapshot_url": null,
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors.",
  "errors": [
    "recipients[0].email must be a valid email address"
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
