Running an API campaign
    • 04 Apr 2024
    • 6 Minutes to read
    • Dark
    • PDF

    Running an API campaign

    • Dark
    • PDF

    Article Summary

    Who should read this article: Administrators

    Use the Voiso Campaigns APIs to add contacts to your live outbound Dialer campaign.


    Voiso provides a variety of APIs that you can use to automate many processes. For details, refer to the Voiso Developer Portal.

    You can use the Campaigns APIs to get a list of your current campaigns and to add a list of contacts to an active Live campaign.

    Voiso supports Dialer campaign integrations with several common CRMs (refer to Running a CRM campaign). If you use a CRM, Helpdesk, or other data source for contacts that is not currently supported by an integration, you can easily use the Voiso Add contacts API to submit a list of contacts to your Live Dialer campaign.

    Add contacts API

    The Add contacts API enables you to programmatically add multiple contacts to an active Dialer campaign. For example, you can enable third-party automation to add contacts based on certain conditions, such as adding a contact to a campaign when a new lead is created in your CRM, Helpdesk, or other data source.

    • Maximum contacts: Each Add contacts API call supports a maximum of 1000 new contacts. The Campaigns API verifies the phone numbers to ensure they are valid and unique. Invalid or duplicate records are rejected.
    • Rate limiting: Voiso recommends not invoking multiple simultaneous Add contacts API calls to the same campaign. Wait at least two seconds after the first request is complete before invoking a second one. If processing is not complete, a new request will be rejected.

    Create a Live Dialer campaign

    Live Outbound Dialer campaigns automatically dial a list of contacts that you have added to the campaign. The campaign remains active until you stop it. When all the contacts in the calling list have been called, the Live Dialer campaign waits for more contacts to be added before resuming dialing.

    Follow these steps to set up a Live Dialer campaign:

    1. From the main menu bar, navigate to Outbound > Dialer campaigns.
    2. In the Dialer campaigns page, click Add Dialer campaign.
    3. Follow the steps in Adding a new campaign to configure the campaign.
    4. Select Live campaign. You do not need to specify a Poll interval as this will be determined by the application you create to use the Add contacts API.
    5. In the Calling list section, set the Method to File import (CSV, XLSX). You do not need to import a calling list file if all of the contacts in the campaign are being provided by the Add contacts API.
    6. Click Save.


    Create an application

    To automatically add contacts to your Live Dialer campaign using the Add contacts API, create an application that extracts contact information from your CRM, Helpdesk, or other data source and adds it to the body of an Add contacts POST request:

    {{baseUrl}}The name of the Voiso cluster where your contact center is located. Refer to Base URL.
    :api_keyThe API key of the user making the request. Voiso responds with the list of campaigns the requesting user is permitted to access. Refer to Authentication.
    :campaign_idThe ID of the campaign, which can be obtained by using a List Campaigns API request or from the Outbound > Campaigns page.

    The following is the expected format of the body of the request:

      "contacts": [
          "phoneNumber": "<string>",
          "contactName": "<string>",
          "contactSource": "<string>",
          "contactURL": "<string>",
          "priority": "<integer>"
          "phoneNumber": "<string>",
          "contactName": "<string>",
          "contactSource": "<string>",
          "contactURL": "<string>",
          "priority": "<integer>"
    phoneNumber(Mandatory) The contact's phone number in E.164 format to be added to campaign.
    contactName(Optional) The contact's name is displayed on the agent’s softphone when the call is connected.
    contactSource(Optional) Where the contact record was obtained. For example, conference, trade show, social media, and so on.
    contactURL(Optional) The URL for the CRM screen pop of the contact's record.
    prioritySpecify the priority of the contact for calling purposes. Priority ranges from 0 to 1000, where lower values equal higher priority. 0 is the highest priority.

    Here is a sample of a POST request in Postman:


    Running and monitoring the campaign

    When you first create a Live Dialer campaign without contacts, its status on the Dialer campaigns page is Draft (1). The total number of contacts in a live campaign is unknown while the campaign is running, so in the Campaigns table, the infinity symbol (∞) is displayed in the Contacts column (2) and a dash (-) is displayed in the Progress column (3). The controls (4) are not enabled until contacts are added to the campaign.


    When contacts are added to the campaign by your application, the controls become available.


    Click Start to launch the campaign. The campaign status changes to Active as long as there are contacts assigned to the campaign and there are agents available to handle calls.


    Live campaigns pause under the following conditions:

    • There are no new contacts available
    • There are no contacts available that meet the local time requirement
    • There are no logged-in agents available

    Live campaigns resume when new contacts are available that meet the local time constraint and there are logged-in agents available to handle the calls.


    Live campaigns run until you stop them. Live campaigns can be stopped manually in the Campaigns page, or by deselecting Live campaign in the Edit campaign page.

    The Agent experience

    When a campaign is active, the agents you have assigned to the campaign are notified in the Agent Panel that a campaign has started. Agents join the campaign from the Dialer campaign page in the Agent Panel. Refer to Outbound campaigns for more information about how agents participate in Dialer campaigns.

    Monitoring a campaign

    While a campaign is active or paused, you can monitor the progress using one or more widgets in the Real-time dashboard.

    To add a widget to the Real-time dashboard, from the Voiso navigation bar, navigate to Reporting > Real-time dashboard. If you do not already have a dashboard, click Create dashboard. To use an existing dashboard, select it from the Dashboards menu or select Add dashboard to add a new dashboard.

    There are several widgets you can use to track your campaign progress and performance in real-time:

    Reporting Real-time Dashboard Dialer Monitoring Widgets


    For detailed information about a widget, in the Add new widget panel, click the "i" icon next to the widget name.

    Campaign – Call DispositionA pie-chart displaying calls by network response: answered, no answer, busy, rejected, or failed
    Campaign StatusA dashboard summarizing various campaign metrics, such duration of the campaign, the average time an agent waits for the next call, how often customers drop off, the average time spent on calls, and the ratio of calls answered to total calls made
    Campaign – Dial AttemptsA bar graph displaying the number of times that each campaign contact was dialed
    Campaign – Agent CounterA pie chart displaying the number of agents who have joined the campaign and their status: outbound (on a call), waiting, and wrapping-up
    Campaign – Wrap-up CodesA pie chart displaying the number of campaign calls by the wrap-up codes (after-call work completions) that you defined

    Dialer Real-time Dashboard

    Campaign reports

    When a campaign is completed, Voiso creates a campaign report. Refer to Part 6: Reviewing campaign results for information about the campaign report and the calling list report.

    Was this article helpful?

    What's Next