This is how to get started sending SMS to your customers from Engage.
Edit attribute
Edit the standard attribute “Mobile phone” to make it active and visible on the contact card.
Specify sender
Decide the sender name for your SMS (this is the name shown in the SMS inbox).
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.
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.
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.
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"
}]
}
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.
{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"mobilePhone": "+46700111222",
"preferences": {
"acceptsEmail": true,
"acceptsSms": true
}
}
{
"mobilePhone": "+46700111222",
"preferences": {
"acceptsSms": true
}
}
Get historical messages
With a single call, the Engage API can fetch the latest SMS and email messages saved for a specific contact.
GET /api/v3/contacts/{ContactId}/messages/latest
GET /api/v3/contacts/111d3329-7eef-45c0-37f9-ae9300a0dacei/messages/latest?count=350
This endpoint is primary for first-line support platforms, allowing customer service employees to quickly troubleshoot a contact’s sent messages without having to log into Voyado Engage.
Response codes
You’ll get one of these two response codes:
Response
{
"count": 2,
"items": [
{
"messageId": "c524e468-pee9-43d5-8f33-af3801140666",
"name": "test",
"sendDateTime": "2022-10-24T16:47:45+00:00",
"type": "SmsMessage",
"source": "Manual",
"isTransactional": false,
"status": "Delivered",
"messageLink": "https://myurl.customer.staging.eclub.se/Open/SmsOnline/Show/aOQaxknO1UOPRq84ARQDBB",
"messageText": "Hello and welcome to ExampleShop. Please add your consent and email here [[registrationUrl:123456c7-79bb-41d4-8db8-af2a00894f33]]"
},
{
"messageId": "d4afac12-2222-4d17-b009-af11009b9a1a",
"name": "Testauto",
"sendDateTime": "2022-09-15T07:26:32+00:00",
"type": "EmailMessage",
"source": "Automation",
"isTransactional": false,
"status": "Delivered",
"messageLink": "https://myurl.customer.staging.eclub.se/open/email/online/Eqyv1ICQF02wCa8FUKlejA/n0pgJu8BBkySna8RAHnP8w/8coDxC_inkCP_K8RAJuajA",
"messageText": "This is a test email."
}
]
}
The field messageLink contains an URL that leads you to a visualization of the message.
The field messageText contains the full text for an SMS, or the subject line if it’s an email.
Field definitions
| Field name | Type | Description | Example value |
|---|
| messageId | GUID | Unique message id | ea11fa26-54d7-4689-984e-ad4000d7a153 |
| name | string | Name of the message in Voyado | 20210610_SE_Summer collection_VIP |
| sendDateTime | datetime | Date and time when the message was sent with offset | 2021-06-100T09:42:44.537+02:00 |
| type | string | Type of message (EmailMessage, SmsMessage or PostalMessage) | EmailMessage |
| source | string | Where the message was sent from in Voyado Engage (Automation, Manual or System) | Manual |
| isTransactional | boolean | If the message was sent as transactional or not (does not take opt-in into account) | false |
| status | string | Delivery status of the send-out | Delivered |
| messageLink | string | The URL for the web version of the email | https://[client].customer.voyado.com/open/email/online/mun9-f1vQEiZ-K1BAUB68Q/9DGtlvkQyka96qpVAMJ70A/m4L3rBllXEiPea1DALLg3A |
| messageText | string | The text content of the SMS or the subject line of the email. | Check out our summer collection! |
Unsubscribe from messages
The Engage API has endpoints to allow unsubscribing of contacts from emails and SMS messages.
Unsubscribe from a 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.
| 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:
POST /api/v3/sms/sendToPhoneNumbers
{
"description": "Message to our members",
"invoiceReference": "Week 3",
"message": "We have exciting news for you...",
"phoneNumbers": [
"46701234567",
"443456789123"
],
"sender": "MyBrand"
}
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.
