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:
0(default) — Simple TTS / audio playback.4— Q&A IVR (collects DTMF digits with branched audio per digit).6— Confirmation + validation (callee answers with a key and, optionally, types a value that is validated against the destination list).- Cloning from another campaign (
cp_id) reuses an existing model and just changes scheduling / list.
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:
- send the audio in this same call with
audio64(and, optionally,audioname); - or create the audio first with CreateAudioFile and send the returned
cdw_fileincontent.
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://
-H ‘Content-Type: application/json’
-d ‘{
“tsid”: “YOUR_TSID”,
“name”: “Welcome 2026”,
“cdlc_id”: 12345,
“text”: “Hello
```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"
}
}
return.cp_id(string) — Newly created campaign id (cd_programa.cp_id). Use it withChangeCampaignandGetCampaignsList.return.settings(object) — Values saved on the campaign:max_answered,vel,resends,time_resends(minutes),no_block,group,mobile. Check them against the request.return.duplicate_request(string) —"1"only when a previous request with the samerequest_idhad already created the campaign:cp_idis that campaign and nothing new was created.
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.