Update campaign agents and teams descriptions

Please refer to the detailed API endpoint specification: Update campaign agents and teams

What you can achieve with the Update campaign agents and teams API

This API enables you to add or remove agents and teams assigned to a specific active outbound dialer campaign.

User permissions required

Edit all campaigns, or
Edit own campaigns (for campaigns the user created)

Prerequisites

The target campaign must already exist and be active.
Agent sign-in email addresses and team names must match existing records in your contact center.

Making requests

The Update campaign agents and teams API requires the Base URL (cluster_id) and the contact center API key as a bearer token in the request header.

The following parameter must be included in the request URL:

Parameter	Description	Type	Required	Notes
campaign_id	Unique identifier of the campaign to be modified.	integer	Required	Must be included in the request URL.

The request body must be a JSON object with one or more of the following fields:

Parameter	Description	Type	Required	Notes
add_agents	A comma-separated list of agent sign-in email addresses to add to the campaign.	array	Optional	Email addresses must match the sign-in email addresses of existing agents.
remove_agents	A comma-separated list of agent sign-in email addresses to remove from the campaign.	array	Optional
add_teams	A comma-separated list of team names to add to the campaign.	array	Optional	Names must match existing team names in your contact center.
remove_teams	A comma-separated list of team names to remove from the campaign.	array	Optional

Request example

PATCH {
  "method": "PATCH",
  "url": "https://cluster1.voiso.com/api/dialer/v1/campaigns/12345/agents",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
    },
  "body": {
    "add_agents": ["[email protected]", "[email protected]"],
    "remove_agents": ["[email protected]"],
    "add_teams": ["team1", "team2"],
    "remove_teams": ["team3"]
    }
}

Response

The response provides confirmation of successful updates as well as any items that could not be added or removed.

Element	Description	Type	Notes
id	ID of the campaign.	int	Use the List campaign API to retrieve a list of campaigns you have access to.
added_agents	Agent emails successfully added to the campaign.	array
removed_agents	Agent emails successfully removed from the campaign.	array
added_teams	Team names successfully added to the campaign.	array
removed_teams	Team names successfully removed from the campaign.	array
agent_not_in_campaign	Agent emails that were not found in the campaign.	array
agent_not_found	Agent emails that do not exist in your contact center.	array
team_not_in_campaign	Team names that were not found in the campaign.	array
team_not_found	Team names that do not exist in your contact center.	array

Response sample

{
  "id": 12345,
  "added_agents": ["[email protected]", "[email protected]"],
  "removed_agents": ["[email protected]"],
  "added_teams": ["team1", "team2"],
  "removed_teams": ["team3"],
  "agent_not_in_campaign": ["[email protected]"],
  "agent_not_found": ["[email protected]"],
  "team_not_in_campaign": ["team4"],
  "team_not_found": ["team5"]
}

Troubleshooting

The following issues are sometimes encountered:

Invalid Key

The API requires a valid bearer token. If you see this error: "error": "Invalid Key" verify that your token is correct and has not expired. Refer to Authentication for details.

Campaign not found

If you receive: "error": "Campaign not found" ensure the campaign ID exists and is accessible to your user. Use List campaigns or check the Outbound > Campaigns page.

Missing permissions

If you receive: "error": "No access" your user does not have the correct permissions. The profile must include either Edit all campaigns or Edit own campaigns permissions.

Nothing to update

If none of the optional fields (add_agents, remove_agents, etc.) are included, the request will return an error. Include at least one updatable field.