Send a SMS

To simplify job creation, Docoon 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:

Parameters list:

Structure details of AdhocRecipients

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

{
  "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, …).

{
  "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

{
  "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:

{
  "JobNumber": 44608862
}

Error response

Status: 400: Bad request

{
  "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 ?”.

{
  "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”.

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

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

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