Send a SMS

To simplify job creation, Odyssey Messaging REST API provides to you a specific resource per media. For SMS jobs only the resource is called “SMSJobs”.

We will review how to send quickly a SMS with one recipient or many recipients. We will also review the SMS advanced parameters and the text personnalisation of the message.

When the SMS job request is accepted, you will get a jobNumber, it means a job was accepted and was put in the appropriate queue (depending on your priority defined in your contract), we will send the message to each recipient as soon as possible depending of the current traffic.

When the job is finished, you will be able to check the transmission status of each recipient, check “Get transmission reports” easy worflow for more information.

Send SMS request informations

Name: /SMSJobs
Type: POST

Headers:

Name Value
Authorization Value : Authorization token check : Connect to REST API
Content-Type Value : application/json

 

Parameters list:

Parameter Type Description
JobType String JobType you want to use (‘SMS’ for SMS Sending).
Text String Text of your message
TrackingID String (Optional) String of your choice, as a reference for the job (shown in the summary and in your billing).
LaunchType Integer (Optional) Choose your type of sending 0 = Send your message , 1 = Do a proof , 2 = Do a preview.
ScheduledStartTime String (Optional) Choose a date to schedule your job.Example : ‘2017-06-08T03:50:25.355Z’
AdhocRecipients List of AdhocRecipients (Optional can be replace by List File)
List of AdhocRecipients: List of the recipients for the sending, see below for the AdhocRecipients Structure.
Lists List of FileReference (Optional can be replace by AdhocRecipients)
List of FileReference: Used for the recipient list.
List format: .xlsx, .xls, .csv, .tab.
your list should at least contained the phone number in the first column (default setting), then it is up to you to fill the other column.
Parameter SMSParameter Avanced parameters for SMS sending (see below).

 

Structure details of AdhocRecipients

This Object is used to list your recipient in the “AdhocRecipients”

Parameter Type Description
Name String Name or Id of your recipient.
Address String Address/Phone number of your recipient.
OptionalFields List of String List of additionnal information of your recipient (Last Name, Birth date, Country, …) .
The first 5 items of the list will be included in the reports.
It is also possible to use these elements to personalize the messages.
If you want to add the first item of this list use ‘BCF3 (then ‘BCF4, 5 etc..).
`BCF1 = Value inserted into the field “Address” and `BCF2 = Value inserted into the field “Name”.
Send Basic SMS
{
  "JobType": "SMS",
  "Text": "Hello  World!",  
  "TrackingId": "Send Basic SMS",
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00337xxxxxx"
    }
  ]
}

SMS advanced parameters description

In addition to the parameters presented above, there are advanced parameters allowing to configure specific parameters to SMS sending (sender address, content encoding, shorturl activation, …).

Parameter Type Description
Media Integer Type of media used
1: SMS (Always this value for SMS sending).
Sender String Sender field is the text or phone number that is displayed on the recipient’s mobile to identify the sender of the message.
This field is limited to 11 characters. The allowed characters are a-z, A-Z, 0-9, space, dash.
! Many operators prohibit the usage of phone number.
! Once the transmitter is personalized, it is impossible to reply to the message or unsubscribe.
ContentType Integer Type of message:
1: Text message using ASCII encoding, up to 160 chars.
3: Unicode, up to 70 chars, used for non latin alphabets.
You can find more informations here
LifeSpan Integer Lifespan of the message if this one couldn’t be delivered right away.
In minutes, the value should be between 720 (12 Hours) and 2880 (48 hours).
ShortUrl Boolean Shortened the URL in your sending.
True : for short URLs
False : to keep your URLs
The short URL is kept 90 days in our systems.
ShortUrlTracking Boolean Allow the tracking on your short URL, you can check the statistics on the customer portal.
With this parameter, a different url per recipient will be generated.
AllowMultiPartition Boolean Allow you to send long SMS (more than one partition which will be concatenated on the recipient’s mobile phone).
MaxPartition Integer Maximum numbers of partition that can be send.
Use advanced parameters
{
  "JobType": "SMS",
  "TrackingId": "Send SMS with advanced parameters",
  "Text": "Hello World !",
  "Parameter": {
    "Sender": "My company",
    "ContentType": 3,
    "Media": 1
  },
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "Company A"
      ]
    }
  ]
}

 

Send a SMS using a file list

You can also use a file list for your recipient. You will have to replace the “AdhocRecipients” list by a “Lists” of File Reference (see the structure below). List format accepted : .xlsx, .xls, .csv, .tab.

By Default, the phone number should be in the first column of the first (and only) sheets of your file.
The other columns can be used for personalizations.

Structure details of FileReference

Parameter Type Description
Name String Name of the file with extension (abc.xls).
Content String File content encoded in BASE64.
Hosted Boolean (Optional) True: if the file is hosted in your list of document (Odyssey hosted document), False: if not.
MimeType String (Optional) If the file’s MIME type is defined, it will be used for sending email. Else, the system will associate a MIME type based on the file extension.
Type Integer Select your document type
0 = List
Use file list
{
  "JobType": "SMS",
  "TrackingId": "Send SMS with file list",
  "Text": "Hello World !",
  "Lists": [
    {
      "Name": "test.tab",
      "Hosted": false,
      "Type":0,
      "Content": "77u/MDAzMzc4Tg3OA=="
    }
  ]
}

Sucessful response

Status: 200 : OK

Parameters list:

Parameter Type Description
JobNumber int ID of the job created
Sucessful response
{
  "JobNumber": 44608862
}

Error response

Status: 400: Bad request

Parameter Type Description
Message String Specification of the problem.
ModelState list of job List of job (String error).
Error response
{
  "Message": "The request is invalid.",
  "ModelState": {
    "job": [
      "An error has occurred."
    ]
  }
}

More Usage Examples

Message personalization

You can personalize your SMS using “`BCFX” values. X being the position of the data you want to send.
For Adhoc sending, `BCF1 is the Address or Phone number, `BCF2 is the Name, `BCF3 the first optional field, `BCF4 the second optional field, …
For List sending, the number is the position in the column. `BCF1 is the first column (usually the phone number), `BCF2 is the second column, …

In the following AdHoc Sample,
We use the text : “Hi `BCF2, Are you from `BCF3 ?”
the resulting test of the 1st Recipient will be : “Hi Dupont, Are you from Company A ?”.
the resulting test of the 2nd Recipient will be : “Hi James, Are you from Company B ?”.

Personalization using Adhoc
{
  "JobType": "SMS",
  "TrackingId": "Send SMS with personalization",
  "LaunchType": 0,
  "Text": "Hi `BCF2, Are you from `BCF3 ?",
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "Company A"
      ]
    },
	{
      "Name": "James",
      "Address": "00336xxxxxx",
      "OptionalFields": [
        "Company B"
      ]
    }
  ]
}

Full message personalization

Using the personalization mechanisms defined above, you can fully personalize your message by using a single field in your recipient list.

For example, you can use the third field in your list to store the entire message that to be sent to the recipient.

In the following AdHoc Sample,
We use the text : “`BCF3”
the resulting test of the 1st Recipient will be : “This the text for the first recipient Dupont”.
the resulting test of the 2nd Recipient will be : “This the text for the second recipient James”.

Full message personalization
{
  "JobType": "SMS",
  "TrackingId": "Send SMS with Full message personalization",
  "LaunchType": 0,
  "Text": "`BCF3",
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "This the text for the first recipient Dupont"
      ]
    },
	{
      "Name": "James",
      "Address": "00336xxxxxx",
      "OptionalFields": [
        "This the text for the second recipient James"
      ]
    }
  ]
}

Scheduled job

Use the “ScheduledStartTime” value to delay your sending.
In our example you will send a message the 1st of January 2019.

Scheduled job
{
 "JobType": "SMS",
  "TrackingId": "Send a Scheduled SMS",
  "Text": "Happy New Year!",
  "ScheduledStartTime": "2019-01-01T00:00:00.688Z", 
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "Company A"
      ]
    }
  ]
}

 

Short URL with tracking

SMS character numbers being restricted, we recommend using short URL or short link for your sending.
You can do that selecting the option “ShortUrl”.

We also help you track the click counts of your users with the option “ShortUrlTracking”.
To access the click datas, consult the details of your job in the customer portal.

Short URL with tracking
{
 "JobType": "SMS",
  "TrackingId": "Send SMS with tracking URL",
  "Text": "Hello World ! Please click on the following link : https://www.odyssey-messaging.com/",
  "Parameter": {
    "Media": 1,
	"ShortUrl":true,
	"ShortUrlTracking":true
  },
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "Company A"
      ]
    }
  ]
}