Skip to main content
This is how to get started sending SMS to your customers from Engage.
1

Go to contact attributes

In the Engage UI, go to Administration/Config Hub and then Contact attributes.
2

Edit attribute

Edit the standard attribute “Mobile phone” to make it active and visible on the contact card.
3

Specify sender

Decide the sender name for your SMS (this is the name shown in the SMS inbox).
4

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.
5

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.
6

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.
7

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.
{
  "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"
   }]
}
8

Create SMS

Now create an SMS. Here you can see how that’s done.
9

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.
Here’s a payload example for creating a contact including mobile number and consent: 
{
  "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: 
{
  "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. 
POST /api/v3/contacts/{contactId}/unsubscribeEmail?messageId={messageId}

POST /api/v3/contacts/{contactId}/unsubscribeSms?messageId={messageId}
If messageId is not sent in the request, the messageId of the last message received by the contact will be used.
FieldTypeExample value
contactId (mandatory)GUIDa67b201f-d86d-4ee2-bdc7-abce0080a803
messageIdGUIDf0370cc7-5428-4cc3-85c9-ad0800f0bc28

​
The sendToPhoneNumbers endpoint

The Engage API has the following endpoint: 
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: 
{
  "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.
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.
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.