> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending SMS

This is how to get started sending SMS to your customers from Engage.

<Steps>
  <Step title="Go to contact attributes">
    In the Engage UI, go to **Administration/Config Hub** and then [Contact attributes](https://help.engage.voyado.com/hc/en-gb/articles/23406421398428-Contact-attributes).
  </Step>

  <Step title="Edit attribute">
    Edit the standard attribute "Mobile phone" to make it active and visible on the contact card.
  </Step>

  <Step title="Specify sender">
    Decide the sender name for your SMS (this is the name shown in the SMS inbox).
  </Step>

  <Step title="Decide opt-out method">
    Decide on the opt-out method.

    * A stop word, allowing the customer to send a certain word to a certain number to unsubscribe. For this, contact your Voyado specialist or account manager.
    * The default, which is standard Voyado opt out link. In this case, do nothing.
  </Step>

  <Step title="Decide on customer response">
    Decide where the customer can enter their mobile number:

    * In My Pages.
    * At the POS terminal.
    * Opting in by sending a certain word to a number (for example, "Voyado in" sent to 123 123). Contact your Voyado specialist or account manager to arrange this.
  </Step>

  <Step title="Include attribute">
    In your integration, be sure to always include the `mobilePhone` attribute in the create contact JSON payload. This makes sure your contacts is always reachable by SMS.
  </Step>

  <Step title="Include preferences object">
    Also include the preferences object in the create contact JSON payload, with `acceptsSms` set to "true" when the customer opts into SMS communication. This is required for them to receive SMS.

    ```json theme={null}
    {
      "firstName": "Example",
      "email": "example@example.com",
      "countryCode": "SE",
      "birthDay": "1966-06-26",
      "lang":"en",
      "contactType": "ExampleContactType",
      "preferences": {
        "acceptsEmail": true,
        "acceptsPostal": true,
        "acceptsSms": true
      },
      "consents": [{
          "id": "memberConsent",
          "value": true,
          "date": "2022-01-01T00:00:00+0100",
          "source": "ECOM",
          "comment": "Approved member terms at checkout"
       }]
    }
    ```
  </Step>

  <Step title="Create SMS">
    Now create an SMS. [Here you can see](https://help.engage.voyado.com/hc/en-gb/articles/17233924490780-Sending-SMS-messages) how that's done.
  </Step>

  <Step title="Send test SMS">
    Send a test SMS to your phone. Opt out through the method you selected in step 4. Now verify that the `acceptsSms` attribute goes from "true" to "false" on the contact card.
  </Step>
</Steps>

Here's a payload example for creating a contact including mobile number and consent:

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "mobilePhone": "+46700111222",
  "preferences": {
    "acceptsEmail": true,
    "acceptsSms": true
  }
}
```

And here's an example of the payload sent to do a contact update:

```json theme={null}
{
  "mobilePhone": "+46700111222",
  "preferences": {
    "acceptsSms": true
  }
} 
```

## Unsubscribe from messages

The Engage API has endpoints to allow unsubscribing of contacts from emails and SMS messages.

### Unsubscribe from specific message

Using these two endpoints, a contact can be unsubscribed from a specific email or SMS. This is effectively the same as them unsubscribing via the unsubscribe link in an email, or through the unsubscribe link in an SMS.

```http theme={null}
POST /api/v3/contacts/{contactId}/unsubscribeEmail?messageId={messageId}
```

```http theme={null}
POST /api/v3/contacts/{contactId}/unsubscribeSms?messageId={messageId}
```

<Tip>
  If messageId is not sent in the request, the messageId of the last message received by the contact will be used.
</Tip>

| Field                 | Type | Example value                        |
| --------------------- | ---- | ------------------------------------ |
| contactId (mandatory) | GUID | a67b201f-d86d-4ee2-bdc7-abce0080a803 |
| messageId             | GUID | f0370cc7-5428-4cc3-85c9-ad0800f0bc28 |

## The sendToPhoneNumbers endpoint

The Engage API has the following endpoint:

```http theme={null}
POST /api/v3/sms/sendToPhoneNumbers
```

This allows the client to send out SMS messages via Engage (using it as a proxy) without any connection to a specific contact. Even if the mobile number used happens to exist for a contact in Engage, no link will be made to them.

This is a service that can be used as a workaround in case the sending out of SMS can't be solved using an automation. The payload used to send out SMS looks like this:

```json theme={null}
{
  "description": "Message to our members",
  "invoiceReference": "Week 3",
  "message": "We have exciting news for you...",
  "phoneNumbers": [
    "46701234567",
    "443456789123"
  ],
  "sender": "MyBrand"
}
```

The `sender` field can consist of the characters a-z, A-Z, 0-9, and "+". It can be 3-11 characters in length.

<Tip>
  This method should only be used for transactional communication as it doesn't validate consents or accept flags for the receivers, and it doesn't record any statistics.
</Tip>

Any SMS sent in this way will show up on the client's SMS usage account as "Send to phone numbers" but no more details will be given.