Send a Voice message

To simplify job creation, Docoon REST API provides to you a specific resource per media. For Voice jobs only the resource is called “VoiceJobs”.

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

When the Voice 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 Voice request informations

Name: /VoiceJobs
Type: POST

Headers:

Parameters list:

Structure details of AdhocRecipients

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

Structure details of FileReference

The object File Reference is used for both list and documents, The structure is the same but you have to select the right “Type” depending of your document.

{
  "JobType": "Vocal",
  "TrackingId": "Send Basic Voice message",
  "Documents": [
    {
      "Name": "Test.txt",
      "Type":1,
      "Content": "VGhpcyBpcyBhIHZvaWNlIG1lc3NhZ2U="
    }
  ],
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00336xxxxxx"
    }
  ]
}

Voice advanced parameters description

In addition to the parameters presented above, there are advanced parameters allowing to configure specific parameters to Voice sending (Text to speech speed, Test to speech voice, sender, scenario, …).

{
  "JobType": "Vocal",
  "TrackingId": "Send Voice message with advanced parameters",
  "Documents": [
    {
      "Name": "Test.txt",
      "Type":1,
      "Content": "VGhpcyBpcyBhIHZvaWNlIG1lc3NhZ2U="
    }
  ],
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00336xxxxxx"
    }
  ],
  "Parameter": {
    "Sender": "0612XXXXXX",
    "TextToSpeechVoiceRate": 5,
    "TextToSpeechVoiceId": 7,
    "ScenarioId": 1,
    "TransferNumber": "0612XXXXXX",
    "TransferKey": "3",
    "RepeatKey": "1",
    "AcknowledgeKey": "2",
    "Media": 2 
  }
}

Send a Voice message 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.

{
  "JobType": "Vocal",
  "TrackingId": "Send Voice message with file list",
  "Documents": [
    {
      "Name": "Test.txt",
      "Type":1,
      "Content": "VGhpcyBpcyBhIHZvaWNlIG1lc3NhZ2U="
    }
  ],
  "Lists": [
    {
      "Name": "test.tab",
      "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 Voice message (only with text documents) 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": "Vocal",
  "TrackingId": "Send Voice message with personalization",
  "Documents": [
    {
      "Name": "Test.txt",
      "Type":1,
      "Content": "SGkgYEJDRjIsIEFyZSB5b3UgZnJvbSBgQkNGMyA/"
    }
  ],
  "AdhocRecipients": [
    {
      "Name": "Dupont",
      "Address": "00337xxxxxx",
      "OptionalFields": [
        "Company A"
      ]
    },
	{
      "Name": "James",
      "Address": "00336xxxxxx",
      "OptionalFields": [
        "Company B"
      ]
    }
  ]
}

Scheduled job

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

{
  "JobType": "Vocal",
  "TrackingId": "Send scheduled Voice message",
  "ScheduledStartTime": "2019-01-01T00:00:00.688Z", 
  "Documents": [
    {
      "Name": "Test.txt",
      "Type":1,
      "Content": "VGhpcyBpcyBhIHZvaWNlIG1lc3NhZ2U="
    }
  ],
  "AdhocRecipients": [
	{
      "Name": "Dupont",
      "Address": "00336xxxxxx"
    }
  ]
}