Using SMS and WhatsApp delivery with the eSignature REST API

To send an envelope with SMS and WhatsApp delivery enabled for one or more recipients, you can call Envelopes:create and pass in data for a new attribute, secondaryDeliveryMethod, to the additionalNotifications properties of your signer, carbonCopy, or certifiedDelivery recipients, specifying the phone number for each recipient. The required values and object hierarchy for this are shown below:

For a walkthrough of how to request a signature using SMS or WhatsApp delivery, see How to request a signature by SMS or WhatsApp delivery.

JSON example request bodies

The following example JSON shows the structure of the SMS delivery attributes within a signers object when the envelope is to be delivered by SMS only:

"signers": [
  {
    "name": "Signer Name",
    "recipientId": "1",
    "deliveryMethod": "SMS",
    "phoneNumber": {
      "countryCode": "1",
      "number": "2125551212"
    },
    "tabs": …

This example shows how to use WhatsApp delivery in addition to email delivery:

"signers": [
  {
    "recipientId": "1",
    "name": "Signer Name",
    "email": "signer@fontara.com",
    "deliveryMethod": "Email",
    "additionalNotifications":
	[
        {
          "secondaryDeliveryMethod": "WhatsApp",
          "phoneNumber": {
            "countryCode": "1",
            "number": "2125551212"
          }
        }
      ]
    "tabs": ...

Note: To use SMS or WhatsApp delivery in the UI, follow the steps documented in the Multi-Channel Delivery for Notifications: SMS and WhatsApp support guide.

API usage notes

• Only eSignature REST API v2.1 is supported.
• The countryCode attribute is the numeric country code for the phone number.
• Use country code “1” for the US, Canada, and the other countries in the North American Numbering Plan (NANP).
• Do not include a plus symbol (+) before the numeric country code.
• The number attribute can include a leading zero for countries outside of the NANP. Do not include a leading one or zero for the US or other countries in the NANP.
• Use only the characters 0-9 in the number attribute. Since users may include spaces, dashes or other characters when they input the number, remove any additional characters before sending the number in an API call.
• The additionalNotifications attribute is set to an array. The array must have exactly one element.
• Docusign Connect only supports receiving SMS notification details in JSON format, rather than in XML.

SDK support

The current eSignature REST API v2.1 SDKs for C#, Node.js, Java, PHP, Python, and Ruby include support for the recipientAdditionalNotification and recipientPhoneNumber objects that enable SMS and WhatsApp delivery.

Troubleshooting errors

• “errorCode” : “OPTED_OUT_PHONE_NUMBER_FOR_RECIPIENT” This error code indicates that the recipient has opted out of Docusign SMS or WhatsApp messages and is unable to receive your SMS or WhatsApp notification.

  • The recipient would need to opt back in before you can send an envelope to them using SMS or WhatsApp delivery. The Multi-Channel Delivery for Notifications: SMS and WhatsApp guide provides instructions for opting back in to Docusign SMS or WhatsApp messages, which you can share with your signers if they need assistance.
  • You can change the Delivery selection to Email only rather than have the recipient opt in for SMS or WhatsApp delivery.

• Other errors Other errors will occur if:

  • The recipient type is not signer, carbonCopy, or certifiedDelivery (Needs to Sign, Needs to View, or Receives a Copy).
  • The recipient is a signing group. Signing groups do not support SMS or WhatsApp delivery.
  • The envelope already has 10 or more SMS or WhatsApp delivery recipients. Ten is the maximum number of SMS and WhatsApp delivery recipients allowed per envelope.