> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Using SMS and WhatsApp delivery with the eSignature REST API

> See context around using SMS and WhatsApp delivery with the eSignature REST API.

eSignature REST API 2.1 only

To send an envelope with [SMS and WhatsApp delivery](/docs/esign-rest-api/esign101/concepts/sms-delivery) enabled for one or more recipients, you can call [Envelopes:create](/docs/esign-rest-api/reference/envelopes/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:

| Object                                        | Description                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signers, carbonCopy`, or `certifiedDelivery` | Recipient types that support SMS and WhatsApp delivery are `signer`, `carbonCopy`, or `certifiedDelivery`.                                                                                                                                                                                                                        |
| `additionalNotifications`                     | Attribute of the recipient that contains an array of `recipientAdditionalNotification` objects. The `recipientAdditionalNotification` object has an optional attribute, `secondaryDeliveryMethod`, where you can define the SMS or WhatsApp delivery details for the recipient.                                                   |
| `secondaryDeliveryMethod`                     | Contains the SMS or WhatsApp delivery details for the recipient. Has the following two attributes:- `phoneNumber`: A `recipientPhoneNumber` object that holds the SMS or WhatsApp delivery phone number.
- `secondaryDeliveryMethod`: A string that indicates the delivery method. The supported values are `SMS` and `WhatsApp`. |

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](/docs/esign-rest-api/how-to/request-signature-sms-whatsapp).

## 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:

```text
"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:

```text
"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](https://support.docusign.com/s/document-item?bundleId=gav1643676262430\&topicId=kwk1607393003979.html) 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](https://en.wikipedia.org/wiki/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](/platform/webhooks/connect) only supports receiving SMS notification details in JSON format, rather than in XML.

## SDK support

The current [eSignature REST API v2.1 SDKs](/docs/esign-rest-api/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](/docs/esign-rest-api/esign101/error-codes) 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](https://support.docusign.com/s/document-item?bundleId=gav1643676262430\&topicId=kwk1607393003979.html) 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.