Skip to the content.

Create campaign

Create a voice campaign — simple TTS, IVR Q&A, or confirmation+validation flow.

Endpoint: POST https://<base>/api/v2/CreateCampaign.php

Creates a voice campaign that batch-dials a destination list (cd_lista_cadastro). Supports four flavors via cp_type:

The endpoint can also generate the destination list and the audio assets in a single call by accepting CSV/JSON content and TTS text.

Authentication

Token authentication required. See Authentication.

Common parameters

tsid — type: string — required

Token for the account.

name — type: string

Campaign name (cp_nome). When cloning, defaults to the name of the source destination list.

detail — type: string

Free-text description (cp_descritivo).

cdlc_id — type: integer

ID of an existing destination list. Required unless you upload a list inline (see “Inline list” below).

cp_id — type: integer

Source campaign id when cloning. When set, most schedule/audio parameters are copied from the source.

cp_type — type: string

Campaign type: empty / 0 (simple), 4 (Q&A), 6 (confirmation+validation).

cp_ctid — type: string

Customer-side campaign id, useful for analytics and downstream filtering.

content — type: string

Existing audio file id (cd_wav.cdw_file) for the main message.

text — type: string

TTS text — when supplied, the endpoint generates the audio internally and uses it instead of content. Only for simple campaigns (cp_type empty or 0): the other types do not generate audio and need content.

voice — type: string

TTS voice: exactly the cdwv_short returned by GetTTSVoices (e.g. Google|pt-BR-Wavenet-A, fad). Used only when the campaign audio is generated from text (simple campaign, without audio/audio64); in that case a voice outside the account’s list is rejected with code 209; letter case is not significant. ElevenLabs is not allowed in this endpoint (code 210).

amd — type: string

Audio file id used for answering-machine detection.

urlcontent — type: string — no longer supported

Removed on 2026-10-05. The API no longer downloads audio from a URL: any request that sends urlcontent is rejected with code 280 and nothing is created. Use one of these instead:

audio64 — type: string

Base64-encoded audio. Auto-decoded into the audio parameter when audio is empty. The content must be an audio file; anything else is rejected with code 283. Only for simple campaigns (cp_type empty or 0).

audioname — type: string

Optional file name for the audio sent in audio / audio64 (for example greeting.mp3). Only the file name is used: folders are dropped and characters other than letters, digits, ., - and _ are replaced with _. Accepted extensions: wav, mp3, mpeg, ogg, opus, m4a, mp4, aac, 3gp, amr, webm. When the name is missing or has another extension, the type is detected from the audio content.

date_start — type: string

Start date, strictly YYYY-MM-DD and a real calendar date (other formats such as DD/MM/YYYY or DD-MM-YYYY are rejected with 220). Defaults to today. In clone mode, omitting it starts the clone today.

date_end — type: string

End date, strictly YYYY-MM-DD. Must not be before the start date (date_start, or today in clone mode without date_start); otherwise 221 (Invalid date end: before date start). Defaults to date_start.

time_start — type: string

Daily start time, HH:MM or HH:MM:SS in 24-hour format (two digits each, 00:00 to 23:59:59). Anything else (for example 9:00, 10:30:99 or extra characters) is rejected with 222. Default 00:00:00.

time_end — type: string

Daily end time, same format as time_start (invalid values return 223). Default 23:59:59.

vel — type: string — default: max

Maximum calls per minute. Either an integer (1–100) or max to use the customer’s full channel allocation.

resends — type: integer — default: 1

Number of retries when calls fail: 0 (no retry) to 3. Total attempts = resends + 1. When omitted, one retry is made.

time_resends — type: integer — default: 30

Minutes between retries (1–240).

mobile — type: integer — default: 1

Set 1 to allow mobile numbers, 0 to skip them.

max_answered — type: integer

Stop after this many answered calls (0 = no limit).

cp_ativo — type: string — default: 1

Status after the destinations are loaded: 1 active, 0 inactive. Creation is asynchronous: the campaign stays in cp_ativo 2 while loading (see GetCampaignsList). Applies to clones too; in clone mode max_answered, vel, resends, time_resends, no_block, group and detail override the source campaign.

request_id — type: string

Idempotency key (8 to 64 letters, digits or . _ : -). Repeating a request with the same request_id and the same parameters within 30 minutes (recognized for 30 to 60 minutes) returns the campaign already created, with return.duplicate_request = "1", instead of creating another one, and does not generate a new destination list from datajson/upload. Use it to retry safely after a timeout or a connection error; send a new value for each new campaign. The same request_id with different parameters (or a different uploaded file) is a different request and creates a new campaign. Two simultaneous requests with the same key are serialized. A campaign whose loading failed (cp_ativo 0 with cp_status_txt starting Falha na geração) is ignored, so the retry creates a new one. Without request_id, behavior is unchanged.

limit_name — type: integer — default: 1

How much of the destination’s name is spoken in the NOME variable: 0 full name, 1 first name only, 2 first and second name.

no_block — type: integer

1 disables the PROCON-style block-list filter (use with care; legal/compliance implications in BR).

group — type: integer

Group id (cd_group.cdg_id) for organizing the campaign in dashboards. 0 means no group. In clone mode, omitting group keeps the source campaign’s group and 0 removes it.

queue_id — type: integer

Contact-center queue id (cc_fila.ccf_id) to which calls are transferred. Used in clone mode (cp_id): omitting it keeps the source campaign’s queue and 0 removes it. The queue must belong to the account (a paused or inactive queue of the account is accepted); a queue of another account, or one that does not exist, returns 253. In clone mode without queue_id, the queue inherited from the source campaign is refused only if it belongs to another account (a deleted queue is kept as before). Outside clone mode the parameter is ignored.

rurl — type: string

Custom callback URL for status updates. It must be a complete URL (with scheme) pointing to a public address: an invalid URL or an internal address is rejected with code 208 and nothing is created. Requests to this URL come from 35.232.103.91 or 35.184.30.236; if your endpoint filters by IP, allow both (see Webhook delivery).

tfix — type: string

Fixed termination route. Multiple values separated by |.

xnum — type: integer

Set 1 to allow multiple destination numbers per record.

sms_action — type: string

Trigger an SMS follow-up. One of ok, nae, oknae, dtmf1. Only with cp_type empty / 0.

sms_text — type: string

SMS body when sms_action is set. Max 160 chars (accents stripped).

Q&A campaign (cp_type=4) — extra parameters

cont0..cont9 — type: string

Audio file ids played per digit pressed (cont0 for 0, cont1 for 1, …).

contentno — type: string

Audio for “no digit pressed”.

dtmfini — type: string

Digit that replays the initial audio.

nans — type: integer — default: 1

Number of digits to capture (1–3).

dtime — type: integer — default: 7

Seconds to wait for digits (4–15).

Confirmation+validation (cp_type=6) — extra parameters

The call plays content (the question) and waits for one key. A confirming key leads to content4, or to the validation step when ndigval is set. This type needs content: text and audio64 are not converted.

dtmfini — type: string

Keys that confirm, separated by | (for example 1 or 1|2). Send it: when omitted, the call skips the question and the confirmation key.

dtmf2 — type: string — default: NO

NO, or the key that repeats the question after content6. Add |<digit> to define a refusal key (for example NO|9). The refusal key is checked before dtmfini, so it must not be one of the confirming keys.

nans — type: integer — default: 1

How many times the question is asked again after a key that is not accepted (1–3).

content4 — type: string

Audio played after a confirming key, or after the value is validated when ndigval is set. The call then ends.

content8 — type: string

Audio played when no key is pressed. The call then waits for a key one more time.

contentno — type: string

Audio played before hanging up when no key is pressed at all.

contentfail — type: string

Audio played before hanging up when the callee presses the refusal key or runs out of attempts with keys that are not accepted.

content2 — type: string

Audio used to ask the question again after a key that is not accepted.

content6 — type: string

Used only when dtmf2 defines a repeat key: audio played after a key that is not accepted; the call then waits for a key again.

ndigval — type: string — default: NO

Number of digits of the value the callee must type to be validated, after the confirming key. NO means no validation.

compw — type: string

Column used to validate the digits typed by the callee. One of cod_cli, extra1, extra2, extra3. The digits typed are compared with the first ndigval digits of that column (other characters in the column are ignored).

content5, content7, content3 — type: string

Validation audios: content5 asks for the value, content7 asks again after a wrong value, and content3 is played before hanging up when validation fails.

nans2 — type: integer — default: 1

How many times the value is asked again after a wrong one (1–3).

fdtmf — type: string

Optional key filter in the form <key>|<seconds>. Both parts are required and <seconds> must be greater than 0; otherwise 219.

Inline list

You can supply the destination list directly instead of pre-creating it via CreateDestinationBase:

datajson — type: object | string

JSON array (or stringified JSON) of destinations.

Or send a multipart form with a CSV/JSON file (any field name). The endpoint detects the file extension and routes accordingly.

FTP report scheduling

relftp — type: integer

ID of an existing FTP delivery profile (cd_programa_ftp.cpftp_id) to deliver call results.

Request example

```bash curl (simple TTS) curl -X POST ‘https:///api/v2/CreateCampaign.php’
-H ‘Content-Type: application/json’
-d ‘{ “tsid”: “YOUR_TSID”, “name”: “Welcome 2026”, “cdlc_id”: 12345, “text”: “Hello , welcome to Acme.", "voice": "Google|pt-BR-Wavenet-A", "vel": "max", "date_start": "2026-05-08", "time_start": "09:00:00", "time_end": "18:00:00" }'


```bash curl (Q&A)
curl -X POST 'https://<base>/api/v2/CreateCampaign.php' \
  -H 'Content-Type: application/json' \
  -d '{
    "tsid": "YOUR_TSID",
    "name": "NPS 2026",
    "cdlc_id": 12345,
    "cp_type": "4",
    "content": "tf12345",
    "cont1": "tf12001",
    "cont2": "tf12002",
    "cont3": "tf12003",
    "nans": 1,
    "dtime": 7
  }'

Response

json 200 OK { "return": { "status": "OK", "status_code": "0", "cp_id": "987654" } }

Error codes

In addition to global authentication codes, CreateCampaign may return:

Code Cause
200 FTP profile (relftp) does not exist.
205 Uploaded file rejected (executable).
206/207 datajson parameter or uploaded JSON file is not valid JSON.
208 rurl is not a valid URL or points to an internal address. Nothing was created.
209 The audio is generated from text and voice is not one of the voices returned by GetTTSVoices for the account. Nothing was created.
500 The voice list could not be read (temporary failure). Nothing was created; repeat the request.
210 TTS provider not permitted in this endpoint (ElevenLabs).
212–227 Validation errors on individual parameters (max_answered, mobile, vel, resends, time_resends, cp_type, no_block, limit_name, etc.).
220/221 date_start / date_end is not a valid YYYY-MM-DD date, or date_end is before the start date (Invalid date end: before date start).
222/223 time_start / time_end is not HH:MM or HH:MM:SS (24-hour, two digits each).
230 Active campaign already exists with the same base, start date and start time.
231 cp_ativo is not 0 or 1.
232 A request with the same request_id is still being processed (waited 60 s). Repeat the same request in about a minute.
233 request_id is not 8 to 64 letters, digits or . _ : -.
263 Internal error checking request_id (database). Nothing was created; retry later.
240–244 Audio assets referenced (content, contentno, contentfail, amd, content2..content8) not found or not available to the account. An account can use its own audio, Velip system audio and audio of accounts in the same corporate group; audio of another account returns the same “not found” message, so the response does not reveal whether that audio exists.
250/251 Group or destination list invalid.
252 compw not recognized.
253 Queue not found (clone mode only): queue_id does not exist or belongs to another account, or, without queue_id, the source campaign’s queue belongs to another account. Nothing was created.
260 DB error inserting the campaign model.
261 DB error inserting the campaign row.
262 Campaign id was not generated (parameter validation failed silently).
270–275 Failure generating the destination list from inline data (datacsv/datajson).
280 urlcontent was sent. Audio by URL is no longer supported: send the audio in audio64, or create it with CreateAudioFile and send the returned cdw_file in content. Nothing was created.
281 Audio generation failed (TTS or conversion of the audio sent in audio / audio64).
283 audio file type not recognized: the content sent in audio / audio64 is not a supported audio file. The campaign is not created.
282 Source cp_id (clone) does not belong to the customer.
290/291 cp_type=6: nans / nans2 out of bounds. cp_type=4: 290 is nans and 291 is dtime out of bounds.
300–305 SMS follow-up parameters invalid.

Note This is the most powerful and most error-prone endpoint of the API. We recommend creating campaigns through the Velip portal until your integration is well-tested, and only switching to programmatic creation for high-volume / repetitive use cases.