> ## 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.
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).
Edit the standard attribute "Mobile phone" to make it active and visible on the contact card.
Decide the sender name for your SMS (this is the name shown in the SMS inbox).
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 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.
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.
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"
}]
}
```
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.
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 another 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:
```
{
"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.
```http theme={null}
GET /api/v3/contacts/{ContactId}/messages/latest
```
By default, the latest 100 messages will be fetched. By adding the parameter count to your query, you can request any number up to the maximum of 500. A query to this endpoint will look like this:
```http theme={null}
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:
```http theme={null}
'200' : OK
```
```http'404' : ContactNotFound theme={null}
```
### Response
```json theme={null}
{
"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.
```http theme={null}
POST /api/v3/contacts/{contactId}/unsubscribeEmail?messageId={messageId}
```
```http theme={null}
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:
```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.
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.