How to create an IVR/Survey via API

We will explain how to create a Campaign, a Survey-Template and Audio via the API.

It’s similar to what we do on the webUI, which you can find at http://HOSTNAME_IP/module/survey/ Therefore, make sure you are familiar with the UI.

Firstly we will upload an audio file, then create a Survey Template, add a Section to the Survey template which will play a message, create a campaign with the Survey Template, then start it.

There are 5 points to follow:

Let’s go through each point in more detail.

1) Upload audio Via API

Upload a new audio file with the following API/Curl command.

CURL Usage:

curl -u username:password -H 'Accept: application/json' \
--request POST http://HOSTNAME_IP/rest-api/audio-files/ \
--form 'name="audio created from API"' \
--form 'audio_file=@"/path/duck01.wav"' \
--form 'user_id="1"'

The result should be similar to this:

{
    "id": 6,
    "name": "audio-via-API",
    "audio_file": "/usermedia/upload/audiofiles/duck01.wav",
    "user_id": 1
}

Note the id (6), that will be your audio-ID for later.

2) Create a Survey Template

Next, create a survey template via API, this is similar to creating the survey template on the webUI at http://HOSTNAME_IP/module/survey/add/

CURL Usage:

curl -u username:password --dump-header - -H "Content-Type:application/json" -X POST --data '{"name": "Survey created from API"}' http://HOSTNAME_IP/rest-api/survey-template/

Result:

{
    "url": "http://127.0.0.1:8000/rest-api/survey-template/27/",
    "name": "Survey created from API",
    "description":null,
    "created_date": "2021-06-19T20:34:47.283180+02:00",
    "updated_date": "2021-06-19T20:34:47.283199+02:00",
    "user": "http://127.0.0.1:8000/rest-api/users/1/"
}

You should get a result similar to the example note the Survey-Template-ID from the result url data. (eg. “url”: “http://127.0.0.1:8000/rest-api/survey-template/27/”, the ID is 27)

That survey-template-ID will be used when you create the section & the Campaign.

3) Create a Section into your Survey Template

So far, you have created a Survey Template. At the moment it’s empty, as you can see on the UI.

You need to add at least one section for a Survey/IVR to work. This is similar to adding a section from the webUI.

The documentation about different type of sections is at, Survey & IVR Configuration

We will keep things simple here and we will create one section Play message (type 1), but it’s possible to create multiple sections and navigate them with branching.

Let’s create a simple Play message section.

To create this via the API, you will need the audio-ID & the survey-template-ID from before.

Earlier our audio-ID was 6 and our survey-template-ID was 27.

Create the Section-Template via API, as follows:

curl -u username:password --dump-header - -H "Content-Type:application/json" -X POST --data '{"type": "1", "audiofile": "/rest-api/audio-files/25/", "question": "Basic Message", "survey": "/rest-api/survey-template/27/"}' http://HOSTNAME_IP/rest-api/section-template/

4) Create a campaign for the previously created Survey Template

Now it’s time to create a campaign, you must also have created a phonebook and imported contacts in that phonebook.

Curl example to create a campaign with IVR/Survey:

curl -u username:password --dump-header - -H "Content-Type:application/json" -X POST --data '{"name": "campaign-via-api", "description": "", "callerid": "1239876", "startingdate": "2021-06-01 14:13:33", "expirationdate": "2022-08-30 13:13:33", "frequency": "100", "max_aleg":100, "max_xfer":10, "dial_method":1, "agent_dial_rate":1, "callmaxduration": "50", "maxretry": "1", "intervalretry": "3000", "calltimeout": "45", "aleg_gateway": "/rest-api/gateway/2/", "sms_gateway": "", "object_id" : "27", "extra_data": "2000", "voicemail": "True", "amd_behavior": "1", "voicemail_audiofile": "", "dnc": "", "user": "/rest-api/users/1/", "phonebook": ["/rest-api/phonebook/1/"], "daily_start_time": "00:00:00", "daily_stop_time": "23:59:59", "callerid_group": "/rest-api/callerid_group/1/"}' http://HOSTNAME_IP/rest-api/campaigns/

Keep the id from the result, that is your Campaign-ID.

Parameters:

* The `name`, try to give a unique name to your campaign.
  • The object_id parameter is the survey-template-ID that you created earlier using the API or WebUI.
  • The aleg_gateway is the gateway to be used, most of the time it will be the same one.
  • You will notice more settings in the campaign APIs, if you have questions, contact support.

5) Start the campaign via API

When a campaign is created via API the Campaign status is set as New.

If you are ready to start your campaign, it can be done with the following Update Campaign API, as follows:

curl -u username:password --dump-header - -H "Content-Type: application/json" -X PATCH --data '{"status": 1}' http://HOSTNAME_IP/rest-api/campaigns/175/

Note: status: 1 is for Started, now the system should start making calls.

You can also stop or pause a campaign via this API.

The different campaign status values are:

  • 1: START
  • 2: PAUSE
  • 3: ABORD
  • 4: END