Running an API campaign

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.

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:

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

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>"
    }
  ]
}

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.

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

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"]
}

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.

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:

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": []
}