Campaigns

A campaign represents a set of jobs to call which is assigned to a team.

Fields

class Campaign
agent: integer

If set, only this agent can handle calls for the campaign.

attempt_count_max: integer

Maximum number of times a job will be called.

attempt_interval: integer

Minimum time (in seconds) between attempts for a given job.

  • 1800 = 30 minutes

  • 3600 = 1 hour

  • 7200 = 2 hours

  • 10800 = 3 hours

  • 14400 = 4 hours

  • 18000 = 5 hours

  • 21600 = 6 hours

  • 28800 = 8 hours

  • 36000 = 10 hours

  • 86400 = 1 day

  • 172800 = 2 days

  • 259200 = 3 days

  • 604800 = 7 days

  • 1209600 = 14 days

audio_prompt: integer

This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

broadcast_rate: integer

Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

call_rebound_strategy: integer

This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

caller_id: integer

Whether to display the Caller ID.

  • 0 = always show

  • 1 = alternate show / hide

  • 2 = always hide

  • 3 = shuffle numbers

created_at: datetime

The campaign’s creation date and time.

detect_voicemail: boolean

Whether to detect answering machines.

  • true

  • false

email_message: integer

This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

form: integer

This form will allow agents to fill out information about each contact.

id: integer

The campaign’s unique ID.

is_active: boolean

Whether the campaign is active.

  • true

  • false

kind: integer

The type of campaign.

  • 0 = phone campaign

  • 1 = SMS broadcast campaign

  • 2 = voice broadcast campaign

  • 3 = voicemail drop campaign

  • 4 = e-mail broadcast campaign

  • 5 = letter broadcast campaign

  • 6 = data enrichment campaign

  • 7 = RCS broadcast campaign

  • 100 = no action campaign

letter_message: integer

This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

mode: integer

Calling mode.

  • 1 = progressive

  • 2 = predictive

name: string

The campaign’s name.

portal: integer

A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

priority: integer

The campaign’s priority.

  • 1 = high

  • 2 = normal

  • 3 = low

skill: integer

Skill to assign to the campaign’s outgoing calls, for agent routing.

team: integer

The campaign’s team.

text_message: integer

This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

text_prompt: integer

This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

API

GET /j/campaigns

Retrieves the list of campaigns.

Example request:

GET /j/campaigns HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "id": 1,
      "agent": null,
      "attempt_count_max": 3,
      "attempt_interval": 7200,
      "audio_prompt": null,
      "call_rebound_strategy": null,
      "caller_id": 0,
      "created_at": "2015-01-06T10:21:14.243Z",
      "detect_voicemail": true,
      "email_message": null,
      "is_active": true,
      "kind": 0,
      "letter_message": null,
      "mode": 2,
      "name": "Test campaign 1",
      "priority": 2,
      "skill": 1,
      "team": 1,
      "text_message": null,
      "text_prompt": null
   },
   {
      "id": 2,
      "agent": null,
      "attempt_count_max": 3,
      "attempt_interval": 7200,
      "audio_prompt": null,
      "call_rebound_strategy": null,
      "caller_id": 1,
      "created_at": "2015-01-06T10:34:25.378Z",
      "detect_voicemail": true,
      "email_message": null,
      "is_active": false,
      "kind": 0,
      "letter_message": null,
      "mode": 2,
      "name": "Test campaign 2",
      "priority": 2,
      "skill": null,
      "team": 2,
      "text_message": null,
      "text_prompt": null
   }
]
Request Headers:
Query Parameters:

  • agent (integer) – An optional agent ID

  • end (datetime) – An end date and time to filter by created_at.

  • start (datetime) – A start date and time to filter by created_at.

  • team (integer) – An optional team ID.

Response JSON Array of Objects:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • created_at (datetime) – The campaign’s creation date and time.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • id (integer) – The campaign’s unique ID.

  • is_active (boolean) – Whether the campaign is active.

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • team (integer) – The campaign’s team.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Status Codes:

  • 200 OK – no error

  • 400 Bad Request – for instance a required field is missing

  • 403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token

GET /j/campaigns/:id

Retrieves the specified campaign.

Example request:

GET /j/campaigns/1 HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "id": 1,
   "agent": null,
   "attempt_count_max": 3,
   "attempt_interval": 7200,
   "audio_prompt": null,
   "call_rebound_strategy": null,
   "caller_id": 0,
   "created_at": "2015-01-06T10:21:14.243Z",
   "detect_voicemail": true,
   "email_message": null,
   "is_active": true,
   "kind": 0,
   "letter_message": null,
   "mode": 2,
   "name": "Test campaign 1",
   "priority": 2,
   "skill": 1,
   "team": 1,
   "text_message": null,
   "text_prompt": null
}
Request Headers:
Response JSON Object:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • created_at (datetime) – The campaign’s creation date and time.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • id (integer) – The campaign’s unique ID.

  • is_active (boolean) – Whether the campaign is active.

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • team (integer) – The campaign’s team.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Status Codes:

  • 200 OK – no error

  • 403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token

  • 404 Not Found – the requested resource was not found

POST /j/campaigns/by_template

Creates a new campaign from a campaign template and a list of jobs. This is the recommended way to create a campaign as all the campaign options are defined in the template. The benefits are:

  • Your users can manage the template via the Spacivox web interface.

  • No additional work is needed to make use of new campaign features.

You can specify a name for the campaign, otherwise a name will be created automatically based on the current date and the campaign template’s name.

The campaign template must not be the team’s default campaign template.

Example request:

POST /j/campaigns/by_template HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

{
  "campaign_template": 123,
  "is_active": true,
  "jobs": [
    {
      "name": "Simon Dupont",
      "numbers": ["0123456789", "0612345678"],
      "reference": "1234567",
      "value": 123.45
    },
    {
      "data": {"some_property": "some value"},
      "name": "A. Durand",
      "numbers": ["0234567891"],
      "reference": "2345678",
      "url": "https://crm.example.com/customers/2345678",
      "value": 234.56
    }
  ],
  "name": "Test campaign",
  "reuse_existing": true
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": 3,
   "is_active": true,
   "jobs_result": [
     {
       "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 3,
         "city": null,
         "country": null,
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {},
         "email": "",
         "id": 14,
         "label": null,
         "name": "Simon Dupont",
         "numbers": ["+33123456789", "+33612345678"],
         "postal_code": null,
         "reference": "1234567",
         "state": 0,
         "url": "",
         "value": 123.45
      },
      "status_code": 200
    },
    {
      "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 3,
         "city": null,
         "country": null,
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {"some_property": "some value"},
         "email": "",
         "id": 15,
         "label": null,
         "name": "A. Durand",
         "numbers": ["+33234567891"],
         "postal_code": null,
         "reference": "2345678",
         "state": 0,
         "url": "https://crm.example.com/customers/2345678",
         "value": 234.56
       },
       "status_code": 200
     }
   ]
   "name": "Test campaign",
}
Request Headers:
Request JSON Object:

  • campaign_template (integer) – The campaign template to apply.

  • is_active (boolean) – Whether the campaign is active.

  • jobs (array) – The list of jobs to import. An empty list is allowed.

  • name (string) – The campaign’s name.

  • reuse_existing (boolean) – Reuse the existing campaign with the same template and name

Response JSON Object:

  • id (integer) – The campaign’s unique ID.

  • is_active (boolean) – Whether the campaign is active.

  • jobs_result (array) – The result of jobs import, in input order.Returns a ‘status_code’ and either ‘data’ (on success) or ‘errors’.

  • name (string) – The campaign’s name.

Status Codes:

Note

When creating a campaign by template, the caller may specify "reuse_existing": true.

In that case, if an existing, non-archived campaign with the same template and name exists, it will be used instead of creating a new one.

The is_active flag, if provided, will be applied to the reused campaign: setting "is_active": true will reactivate the campaign if it had been paused or stopped.

Warning

The response jobs field contains only the details of actually created jobs.

If the input contained duplicate references, the response will only include the details of the first job for each reference.

If the call used reuse_existing = true and an input job shared a reference with an existing job, the response won’t contain any details for that job.

POST /j/campaigns

Creates a new campaign and optionally imports a list of jobs. Unless you need to retain full control over the configuration options, consider using the campaign template-based API.

Example request:

POST /j/campaigns HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

{
  "attempt_count_max": 3,
  "attempt_interval": 7200,
  "caller_id": 0,
  "detect_voicemail": true,
  "jobs": [
    {
      "name": "Simon Dupont",
      "numbers": ["0123456789", "0612345678"],
      "reference": "1234567",
      "value": 123.45
    },
    {
      "data": {"some_property": "some value"},
      "name": "A. Durand",
      "numbers": ["0234567891"],
      "reference": "2345678",
      "url": "https://crm.example.com/customers/2345678",
      "value": 234.56
    }
  ],
  "is_active": true,
  "kind": 0,
  "mode": 2,
  "name": "Test campaign",
  "priority": 2,
  "skill": 1,
  "team": 2
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "id": 3,
   "agent": null,
   "attempt_count_max": 3,
   "attempt_interval": 7200,
   "audio_prompt": null,
   "call_rebound_strategy": null,
   "caller_id": 0,
   "created_at": "2015-01-06T11:44:53.427Z",
   "detect_voicemail": true,
   "email_message": null,
   "is_active": false,
   "kind": 0,
   "letter_message": null,
   "mode": 2,
   "name": "Test campaign",
   "priority": 2,
   "skill": 1,
   "team": 2,
   "text_message": null,
   "text_prompt": null
}
Request Headers:
Request JSON Object:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • is_active (boolean) – Whether the campaign is active.

  • jobs (array) – A list of jobs to import (optional).

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • team (integer) – The campaign’s team.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Response JSON Object:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • created_at (datetime) – The campaign’s creation date and time.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • id (integer) – The campaign’s unique ID.

  • is_active (boolean) – Whether the campaign is active.

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • team (integer) – The campaign’s team.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Status Codes:

Warning

This API is deprecated. New campaign features are no longer added.

New developments MUST NOT use this API, and MUST use the /j/campaigns/by_template endpoint instead.

The endpoint will be removed in 2027.

PUT /j/campaigns/:id

Updates are performed in a transaction in order to allow taking locks on the object being updated.

Example request:

PUT /j/campaigns/1 HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

{
   "agent": null,
   "attempt_count_max": 3,
   "attempt_interval": 7200,
   "call_rebound_strategy": null,
   "caller_id": 0,
   "detect_voicemail": true,
   "is_active": true,
   "kind": 0,
   "mode": 2,
   "name": "Test campaign 1 (renamed)",
   "priority": 2,
   "team": 1,
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "id": 1,
   "agent": null,
   "attempt_count_max": 3,
   "attempt_interval": 7200,
   "audio_prompt": null,
   "call_rebound_strategy": null,
   "caller_id": 0,
   "created_at": "2015-01-06T10:21:14.243Z",
   "detect_voicemail": true,
   "email_message": null,
   "is_active": true,
   "kind": 0,
   "letter_message": null,
   "mode": 2,
   "name": "Test campaign 1 (renamed)",
   "priority": 2,
   "skill": 1,
   "team": 1,
   "text_message": null,
   "text_prompt": null
}
Request Headers:
Request JSON Object:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • is_active (boolean) – Whether the campaign is active.

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Response JSON Object:

  • agent (integer) – If set, only this agent can handle calls for the campaign.

  • attempt_count_max (integer) – Maximum number of times a job will be called.

  • attempt_interval (integer) – Minimum time (in seconds) between attempts for a given job.

  • audio_prompt (integer) – This message will be played to prompt the contact to press a key. Only available for voice broadcast campaigns.

  • broadcast_rate (integer) – Number of calls / messages per minute (between 1 and 24 for calls, between 1 and 48 for messages). Only available for broadcast campaigns.

  • call_rebound_strategy (integer) – This strategy will determine what other media to attempt if a contact is not reachable. Only available for phone and voice broadcast campaigns.

  • caller_id (integer) – Whether to display the Caller ID.

  • created_at (datetime) – The campaign’s creation date and time.

  • detect_voicemail (boolean) – Whether to detect answering machines.

  • email_message (integer) – This message will be sent by e-mail to the contact. Only available for e-mail broadcast campaigns.

  • form (integer) – This form will allow agents to fill out information about each contact.

  • id (integer) – The campaign’s unique ID.

  • is_active (boolean) – Whether the campaign is active.

  • kind (integer) – The type of campaign.

  • letter_message (integer) – This message will be sent by letter to the contact. Only available for letter broadcast campaigns.

  • mode (integer) – Calling mode.

  • name (string) – The campaign’s name.

  • portal (integer) – A unique link to this portal will be generated for the contact and substituted in the SMS or e-mail message. Only available for SMS or e-mail broadcast campaigns.

  • priority (integer) – The campaign’s priority.

  • skill (integer) – Skill to assign to the campaign’s outgoing calls, for agent routing.

  • team (integer) – The campaign’s team.

  • text_message (integer) – This message will be sent by SMS to the contact. Only available for SMS broadcast campaigns.

  • text_prompt (integer) – This prompt will be sent by SMS to the contact to initiate a two-way conversation. Only available for SMS broadcast campaigns.

Status Codes:

  • 200 OK – no error

  • 400 Bad Request – for instance a required field is missing

  • 403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token

  • 404 Not Found – the requested resource was not found