Who should read this article: Administrators

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

Introduction

Voiso provides a variety of APIs that you can use to automate many processes and manage your 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.

For details, refer to the Campaigns APIs in the Voiso Developer Portal.

List campaigns API

Use the List campaigns API to get a list of your current campaigns and to add a list of contacts to an active Live campaign.

Add campaign 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.

Limitations

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.

Update campaign contacts

Use the Update Contacts API to update existing contacts/leads in a live Dialer campaign. Contacts are identified by their phone number. You can only update the contact name, source, URL, active state, and priority.

Change campaign status

After you create a live Dialer campaign in your contact center, you can use the Change campaign status API to manage the status of a campaign to start, stop, or pause.

Update campaign agents and teams

Use the Update campaign agents and teams API to manage agents and teams assigned to a campaign programmatically. This endpoint enables external applications to dynamically assign or unassign agents and teams from an active Dialer campaign. This is useful for automating campaign workforce management, especially in real-time dialing scenarios where campaign membership changes frequently.

How to run an API campaign

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:

From the main menu bar, navigate to Outbound > Dialer campaigns.
In the Dialer campaigns page, click Add Dialer campaign.
Follow the steps in Adding a new campaign to configure the campaign.
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.
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.
Click Save.

Dialer%20API%20Campaign%20Add%20Campaign

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}}/api/v1/:api_key/campaigns/:campaign_id/contacts

Name	Description
{{baseUrl}}	The name of the Voiso cluster where your contact center is located. Refer to Base URL.
:api_key	The 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_id	The 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>"
    }
  ]
}

Name	Description
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.
priority	Specify 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:

{
  "method": "POST",
  "url": "https://cluster1.voiso.com/api/v1/ab7a556b6...bb00cc6c3/campaigns/25735/contacts",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "contacts": [
      {
        "phoneNumber": "4407414992548",
        "contactName": "Bill Bringy",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "1"
      },
      {
        "phoneNumber": "4407415552548",
        "contactName": "Alicia Gonzales",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "2"
      }
    ]
  }
}

With these parameters, you can make a PUT request:

PUT {
  "method": "PUT",
  "url": "https://cluster1.voiso.com/api/v1/ab7a556b6...bb00cc6c3/campaigns/25735/contacts",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "contacts": [
      {
        "phoneNumber": "4407414992548",
        "contactName": "Bill Bringy",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "1",
        "isActive": 1
      },
      {
        "phoneNumber": "4407415552548",
        "contactName": "Alicia Gonzales",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "2",
        "isActive": 0
      }
    ]
  }
}

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.

Dialer%20API%20Campaign%20Draft%20Status

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

Dialer%20API%20Campaign%20Draft%20Status%20Start%20Enabled

Start, pause, or stop the campaign via API

Start, pause, and stop your Live campaigns programmatically using the Change campaign status API.

This is useful for integrating campaign state control into custom dashboards or automations—such as triggering campaign start when agents become available or pausing it when contact quotas are met.

Make a POST request to:

https://{{cluster}}/api/dialer/v1/campaigns/{campaign_id}/operation

Include the operation parameter in the request body with one of the following values:

start
pause
stop

Sample request

{
  "operation": "start"
}

Sample response

{
  "id": 12345,
  "operation": "start",
  "success": true,
  "message": "Campaign started successfully"
}

If the operation cannot be performed, the response will indicate success: false and include an array of error messages.

Example failure response

{
  "id": 12345,
  "operation": "start",
  "success": false,
  "errors": ["Campaign must have at least one agent to start"]
}

Note

Only users with Edit all campaigns or Edit own campaigns permissions can use this API.

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.

Note

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.

Manage agents and teams

Manage agents and teams assigned to a campaign programmatically using the Update campaign agents and teams API.

This endpoint enables external applications to dynamically assign or unassign agents and teams from an active Dialer campaign. This is useful for automating campaign workforce management, especially in real-time dialing scenarios where campaign membership changes frequently.

To update the assigned agents and teams, make a PATCH request to:

https://{{cluster}}/api/dialer/v1/campaigns/{campaign_id}/agents

The request body supports the following optional parameters:

Field	Description	Type	Required
add_agents	List of agent emails to assign to the campaign	array	Optional
remove_agents	List of agent emails to unassign from the campaign	array	Optional
add_teams	List of team names to assign to the campaign	array	Optional
remove_teams	List of team names to unassign from the campaign	array	Optional

Sample request

{
  "add_agents": ["agent5@abc.com", "agent6@abc.com"],
  "remove_agents": ["agent2@abc.com"],
  "add_teams": ["team1", "team2"],
  "remove_teams": ["team3"]
}

Sample response

{
  "id": 12345,
  "added_agents": ["agent5@abc.com", "agent6@abc.com"],
  "removed_agents": ["agent2@abc.com"],
  "added_teams": ["team1", "team2"],
  "removed_teams": ["team3"],
  "agent_not_in_campaign": [],
  "agent_not_found": [],
  "team_not_in_campaign": [],
  "team_not_found": []
}

Note

To use this endpoint, the authenticated user must have either the Edit all campaigns permission or the Edit own campaigns permission for the specified campaign.

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

Tip

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

Widget	Description
Campaign – Call Disposition	A pie-chart displaying calls by network response: answered, no answer, busy, rejected, or failed
Campaign Status	A 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 Attempts	A bar graph displaying the number of times that each campaign contact was dialed
Campaign – Agent Counter	A 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 Codes	A 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.