Cookbook
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.
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 and 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.
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);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
idyou handled and skip repeats, so the customer isn’t texted twice. See duplicate deliveries. - Verify first. Use the raw body. See verify the signature.
- Messaging rules are the provider’s. WhatsApp templates need Meta’s approval (template overview). For SMS see the Twilio Message resource.
Related
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"
}
}
]
}npx signatureapi envelopes create --body - <<'EOF'
{
"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"
}
}
]
}
EOF{
"name": "create_envelope",
"arguments": {
"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"
}
}
]
}
}{
"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
}{
"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 every call can return are in Errors and Authentication.