Be approved by Ortto to send transactional messages.
If you have not yet requested permission to send transactional SMS, contact Ortto via email (help@ortto.com) or live chat to do so.
Alternatively, set up a transactional playbook or journey in the Ortto app, at which point you will be prompted to seek permission through the system itself.
Ensure the person receiving the message is subscribed to SMS. Unlike transactional email, a transactional SMS message won’t be sent to a person who isn’t subscribed to SMS.
If you send a transactional SMS message to a person who isn’t subscribed you may see a 202 response (confirming the request has been accepted) in the logs for your custom API data source in the Ortto app, but the send will be marked as Invalid for the recipient (shown under the Activities tab of a person’s view).
Sending transactional SMS messages
Ortto supports sending transactional SMS messages via the API. You might want to do this to send links to tickets, e-books, receipts, invoices, booking confirmation and anything which requires an SMS message to be delivered to a customer.
Example of sending a single transactional SMS message to a single person
The example below sends a single transactional SMS message to the phone number +61 400123456.
shell
curl --request POST 'https://api.ap3api.com/v1/transactional/send-sms' \
--header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"asset": {
"sms_body": "This is the root message content",
"sms_name": "The root name of the SMS message",
"no_click_tracks": false,
"add_utm_tracking": false
},
"smses": [
{
"fields": {
"phn::phone": {
"c": "61",
"n": "400123456"
},
"str::first": "John",
"str::last": "Smith"
}
},
"location": null
}
],
"merge_by": [
"phn::phone"
],
"merge_strategy": 2,
"find_strategy": 0,
"skip_non_existing": false
}'
Asset options for transactional SMS messages
sms_body
This is the body of your SMS message. You are required to provide the full message content here. This can be anything you like and it is up to you to make sure that any Liquid syntax is valid, and test it to see that it renders correctly before sending to real customers. You can use any and all Ortto Liquid syntax.
sms_name
This can be any name you like, the recipient won’t see it.
no_click_tracks
By default we will generate "SMS clicked" activities for any links clicked in your transactional SMS messages. This means that Ortto will rewrite the URLs of you links to go through a redirect before the customer reaches your URL. The user won’t notice as this happens quickly, but sometimes you might like to disable this feature so the URLs are not changed (e.g. because you have a very specific URL structure). Setting no_click_tracks to true will mean Ortto will not rewrite the links in your message.
If you have a sender ID enabled, and:
no_click_tracks set to false (or excluded from the request), your SMS messages will include the opt-out link as usual.
Or,
no_click_tracks set to true, your SMS messages will include "Reply STOP to <your account’s phone number> to opt out", because contacts cannot reply to a sender ID. This opt-out message will override your custom opt-out message (if enabled).
add_utm_tracking
To automatically add UTM tracking parameters to links that don’t already have UTM parameters in your SMS campaign messages, set add_utm_tracking to true. Where a link has an existing UTM parameter, we won’t replace it.
asset_id
This allows you to use a draft or published Ortto SMS asset for the SMS message. This is for assets only, whether attached or unattached to a journey or playbook, and is not for single-send SMS campaigns.
The asset_id value is found in the asset URL, which you need to collect from the Ortto app. It is then added to the API request body at asset. If using asset_id, you do not need to include other asset objects in the API request body.
To add another content element to the SMS message, such as a confirmation widget, we recommend that you create an SMS asset in the Ortto app that includes all the content you require. Then you can use asset_id to supply the message content.
Using an asset ID
To use an SMS asset for a transactional SMS message:
In Ortto, create a new SMS asset, or view an existing SMS asset (such as one attached to a journey, or an unattached draft in your asset manager).
If creating a new SMS asset, at minimum complete the Template, Setup and Content steps. (You can stop at the Review step and leave the asset unpublished if you wish.)
When viewing the draft or published asset, copy the asset ID from the URL. If will look like the below example.
Example asset ID found in the asset URL
Add asset_id and value to the asset array the transactional SMS API call.
The asset_id value will provide the details and data configured at the Template, Setup and Content steps when the SMS asset was created in Ortto.
SMS billing and calculating SMS segments
An important consideration when sending transactional SMS messages is the message’s character count and number of segments it adds up to. SMS messages sent from Ortto are charged per SMS segment.
Remember that each message sent will automatically have an opt-out option appended (as a link or a reply-to number if you use a sender ID and have click tracking disabled). The opt-out content will add to your character count and may increase the number of segments your message consists of.
One way to have a clear indication of how many segments a message consistes of is to create an SMS asset in the Ortto app, then use the asset’s ID value in your API request.
Or, if you are writing the message content as the sms_body value of the API request, test the character count by sending yourself the SMS message (before sending to other recipients) so you can add up the character count of your message plus the appended opt-out content.
Learn more about how Ortto calculates SMS message segments in SMS billing.
Notes about people
It is a prerequisite that any contacts you send SMS to are subscribed (opted-in) to SMS. If you attempt to send an SMS message to a contact who does not already exist in your CDP, they will be created as a contact however they won’t receive the SMS message because the system doesn’t know that person’s SMS subscription status. (The new contact’s record is created by default as opted-in to email but opted-out of SMS.)
If you do not want to send transactional SMS messages to people who do not already exist in the CDP, then provide the skip_non_existing option as true.
As part of sending transactional SMS messages you can add/merge fields for customers in the record provided to this endpoint. For a full description of how this works see here.
Example of sending a single transactional SMS message to a group of people
You can send the same transactional SMS message to a group of people just by including more records in the array of smses provided in the call. This will send the same message to each of the people listed (but interpolating their merge tags into the message).
