Place voice call (TTS)
Outbound voice call with TTS, IVR/DTMF, transfer, and recording.
Endpoint: POST https://<base>/api/v2/MakeTTSCall.php
Places a single outbound voice call through the Velip telephony stack. The call can carry recorded audio files, dynamic TTS content with placeholders (<NOME>, <EXTRA1>–<EXTRA4>, <COD_CLI>), DTMF/IVR navigation, transfer to a contact-center queue (PA), and optional recording.
This is the most flexible endpoint of the Velip API; many parameters are advanced and only relevant for specific call types. The minimal viable call requires tsid, dest, and either text (for TTS) or content (for a recorded audio id).
Authentication
Token authentication required. See Authentication.
Core parameters
tsid — type: string — required
Token for the account.
dest — type: string — required
Destination phone number. With setbrasil=1 (default) accepts national formats; otherwise pass full E.164 (without +).
text — type: string
TTS text spoken to the callee. One of text, text1..text11, content, or any of the placeholders (nome, extra1..4, cod_cli) must be present.
content — type: string
Audio file id from GetAudiosList. Multiple slots available: content1..content15, plus contentno, contentend, contentfail, contentdtmf.
Every audio parameter must reference an audio of your account (audios shared by Velip, such as silences, and audios of accounts in the same corporate group are also accepted). Otherwise the call is rejected with code 205.
voice — type: string
TTS voice: exactly the cdwv_short returned by GetTTSVoices (e.g. Google|pt-BR-Wavenet-A, MS|pt-BR-FranciscaNeural, Polly|Camila|neural, fad). When the call has text (text, text1…text11 or textfail), a voice outside the account’s list is rejected with code 209 and the call is not placed; letter case is not significant. Without text, voice is not used (audios with nome/extra* keep the voice they were created with). When omitted, the default voice is used. ElevenLabs is not allowed in this endpoint.
encoding — type: string
Encoding of the text payload. One of UTF-8, 2UTF-8 (double-encoded), ASCII. Defaults to ISO-8859-1 for form requests; UTF-8 for JSON.
setbrasil — type: integer — default: 1
When 1, normalizes Brazilian numbers; when 0, sends as-is (international).
callerid — type: string
Caller id to present on the call. Honored only when the account has a fixed caller id (which always takes precedence over this parameter) or its own termination routes. For any other account the value is ignored: the call is still placed with the default caller id of the route, and the response carries return.warning = callerid ignored: not allowed for this account.
ctid — type: string
Customer-side correlation id; can be enforced unique per call when cdcs_uni_ctid=1.
cpid — type: string
Optional campaign id, used to group analytics for many calls.
httpdup — type: integer — default: 10
Duplicate-suppression window (seconds, 1–600). Returns code 244 when triggered. Pass 0 to disable. A request rejected by validation before becoming a call (codes such as 201, 203, 204, 205, 208, 209, 210) does not count, so the corrected request can be sent again right away.
TTS placeholders
When the spoken script contains placeholders, pass them as separate parameters. The system substitutes them at audio-generation time:
| Placeholder | Parameter |
|---|---|
<NOME> / <NAME> |
nome |
<EXTRA1> |
extra1 |
<EXTRA2> |
extra2 |
<EXTRA3> |
extra3 |
<EXTRA4> |
extra4 |
<COD_CLI> / <CODCLI> |
cod_cli |
Example: text=Hello <NOME>, your code is <COD_CLI> with nome=John&cod_cli=4321.
Call modes (type)
Choose how the call is conducted with the type parameter:
type |
Behaviour |
|---|---|
0 (default) |
Plays the audio/TTS to the callee and hangs up. |
2 |
Plays the audio/TTS, waits for the confirmation digit (dtmfconf) and then transfers to dest2. |
3 |
Transfers to dest2 as soon as the callee answers, with no DTMF prompt. |
6 |
Confirmation: plays a question, waits for one key and plays a closing audio. See Confirmation call. |
22 |
Plays content and records the response (use rec=<seconds>). |
100 |
Call conducted by a conversational agent with ASR/NLU (dtmfini=<ccba_id> is required). |
Summary: type × dtmfconf
type=2 and type=3 are the same transfer mode with or without a confirmation key. Always send them as one of these two pairs:
| What you want | Send | What happens |
|---|---|---|
| Transfer after a key press | type=2 + dtmfconf=<digit> |
Plays the audio/TTS and waits for the digit. Pressed: transfers to dest2. Not pressed: no transfer, plays contentno if set. |
| Direct transfer | type=3, no dtmfconf |
Transfers to dest2 as soon as the callee answers, with no DTMF prompt. |
If the pair is mismatched, dtmfconf wins: type=3 with a digit runs as type=2, and type=2 without a digit (or with NO) runs as type=3.
In type=100 the parameter has a different meaning:
type |
dtmfconf |
What happens |
|---|---|---|
100 |
empty | The agent listens to the callee (speech recognition on). |
100 |
1 |
Key-press answers for the whole call: speech recognition off, each turn waits for dtime. |
Confirmation call (type=6)
The call plays a question, waits for one key and ends with an audio chosen by the answer.
| Parameter | Role in type=6 |
|---|---|
content or text |
The question. |
dtmfini |
Keys accepted as an answer: digits 0–9 separated by \| (for example 1\|2). The request is not rejected without it, but then no key is accepted. Do not send NO: the question is skipped and the call goes straight to content4. |
content4 |
Audio played after an accepted key. The call then ends. |
content8 |
Audio played when no key is pressed. The call then waits for a key one more time. |
contentno |
Audio played before hanging up when no key is pressed at all. |
contentfail |
Audio played before hanging up when the callee presses the refusal key or a key that is not accepted. |
dtmf2 |
Send NO, or NO\|<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 accepted keys. If dtmf2 is omitted, after a key that is not accepted the call stays silent for up to dtime seconds waiting for another key before playing contentfail. |
dtmf |
Leave it empty or send NO (uppercase). Any other value turns on a typed-value validation step that only works in campaigns (CreateCampaign, cp_type=6): in a single call it always fails, content4 is not played and resp_1 comes back as #. |
dtime |
Seconds to wait for the key. Default 7. |
nans, dtmf4 |
Optional repetition: dtmf4 is a key that replays the question and nans is how many repetitions are allowed. With nans, a key that is not accepted also makes the call play content2 and wait again before contentfail. Leave both out for a call that ends on the first answer. |
What happens for each answer, with dtmf2 starting with NO and without nans:
| Callee | Call |
|---|---|
Presses a key listed in dtmfini |
Plays content4 and hangs up. |
| Presses the refusal key | Plays contentfail, if set, and hangs up. |
| Presses another key | Plays contentfail, if set, and hangs up. |
| Presses nothing | If content8 is set, plays it and waits once more: accepted and refusal keys work as in the first wait, and any other key ends the call with contentfail. Without content8, or with no key again, plays contentno, if set, and hangs up. |
resp_1, returned by GetCallStatus, holds the key the callee pressed: an accepted key, the refusal key or, in the first wait, any other key. It is empty when no key was pressed. Compare it with your accepted keys to know whether the callee confirmed.
The key can be pressed while the question is still playing.
DTMF / IVR
Specify the digits to capture and the action per digit:
ndig — type: integer
Number of digits expected in the response.
dtime — type: integer
Seconds to wait for digits.
dtmfconf — type: string
Confirmation digit. Its effect depends on the call mode:
type=2/type=3— the digit the callee must press to be transferred todest2. Sending it makes the call run astype=2; leaving it empty (or sendingNO) makes it run astype=3, which transfers on answer without a prompt. When the digit is not pressed, the call is not transferred andcontentnois played, if set.type=100—dtmfconf=1switches the whole call to key-press answers: speech recognition stays off from the first turn to the last, and each turn waits for the digit timeout (dtime). Do not send it for agents that are expected to listen to the callee.
dtmfini — type: string
Initial DTMF mapping. For type=100, this is the ccba_id of the agent to bridge to. For type=6, the keys accepted as an answer, separated by |.
dtmf, dtmf2..dtmf11 — type: string
Per-digit destinations. Each maps a key press to a follow-up content/text or to a transfer.
Transfer to PA / second leg
dest2 — type: string
Number (or routed target) of the second leg. Special prefixes bypass national normalization and select the leg technology:
| Prefix | Second leg |
|---|---|
| (digits) | Telephone number (PSTN). Prefixes 0800, 300, 400, 103 bypass normalization. |
RT<ccba_id> |
FastVoice AI agent — bridges the answered call to the realtime agent (cc_bot_agent) identified by ccba_id. See FastVoice AI agent. |
WA<number> |
WhatsApp Calling second leg. |
FI<queue_id> |
Contact-center PA queue. |
fifo — type: integer
When set, queues the transfer in a FIFO until a PA is available.
fifolim — type: integer
Maximum seconds to hold the call in the FIFO before giving up.
senddtmf — type: string
Digits to send after the second leg answers (for IVR-to-IVR bridging).
senddtmftime — type: integer
Seconds to wait after answering the second leg before sending senddtmf.
FastVoice AI agent
Set dest2=RT<ccba_id> to have an autonomous FastVoice agent answer the second leg. When the callee picks up, the call is bridged to the agent (OpenAI Realtime or Gemini Live over SIP) resolved from cc_bot_agent.ccba_project_id, and the AI conducts the conversation end-to-end.
- Use it with
type=3(bridge on answer, no DTMF prompt,dtmfconfempty),type=2(bridge after thedtmfconfdigit), ortype=100(ASR/NLU). <ccba_id>is the numeric id of an active agent owned by the account (shown asRT<id>in the FastVoice panel). If the agent is missing, inactive, or belongs to another account, the AI leg does not open (logged asRT_AGENT_NOT_FOUND) and the call proceeds without it.- Combine with
rec/startrecto record the whole conversation andtimelimitto cap its duration.
Recording
rec — type: integer
Maximum seconds of recording to keep. Set together with mrec for legacy compatibility.
startrec — type: string
When recording starts: pa (after PA bridge), conf (after conference forms), or ini (from the start).
Scheduling and retries
repeat — type: string
Format tries|interval_min|until|YYYY-MM-DD HH:MM. Example 3|30|22:00|2026-05-10 09:00 — first call at 09:00 on 2026-05-10, then up to 2 retries every 30 minutes until 22:00.
priority — type: integer
Routing priority. -20 = generate audio synchronously and dial as soon as ready; -1 = dial immediately, ignoring queue priority.
block — type: string
Schedule a “do not dial before” timestamp.
ringtime — type: integer
Maximum ring duration in seconds.
timelimit — type: integer
Maximum total call duration in seconds.
answer — type: integer
Seconds before considering the call answered when no media is detected.
SMS follow-up after the call
The endpoint can trigger an SMS based on the call outcome:
sms_action — type: string
One of ok, nae, oknae, dtmf1. Decides which call outcomes trigger the SMS.
sms_text — type: string
Body for the follow-up SMS (max 160 chars). Accents are stripped.
sms_dtmf — type: string
When sms_action=dtmf1, the digit that triggers the SMS.
Other parameters
free — type: integer
When 1, releases the call from the Procon (do-not-call) blocklist. Defaults to the account’s list policy (livre_1/livre_0) when omitted.
amd — type: string
Audio id used as Answering-Machine Detection prompt.
moh — type: integer
Music-on-hold mode: 1 = dial tone, 2 = default music, 3 = silence.
rurl — type: string
URL-encoded callback URL for status updates (overrides the per-account default). 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 the call is not placed. 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).
numlim — type: integer
When set together with cpid, blocks repeated dialing of the same number more than numlim times.
audiolim — type: integer
Same as numlim, but for the same number AND the same audio.
bkddd — type: integer
1 rejects calls outside the configured DDD time window. 2 queues them silently.
tfix — type: string
Forces a specific termination route (only when authorized for the account). Multiple routes separated by |, e.g., 0|100.
When the account is restricted to its own termination routes, only those routes are honored: routes outside the account’s list are dropped, and if none is left (including 0) the call goes through the account’s routes. In that case the response carries return.warning = tfix limited to the terminations enabled for this account. When omitted, the call uses the account’s routes.
Request example
```bash curl (simple TTS)
curl -X POST ‘https://
-H ‘Content-Type: application/json’
-d ‘{
“tsid”: “YOUR_TSID”,
“dest”: “5511999999999”,
“text”: “Hello
```bash curl (DTMF + transfer)
curl -X POST 'https://<base>/api/v2/MakeTTSCall.php' \
-H 'Content-Type: application/json' \
-d '{
"tsid": "YOUR_TSID",
"dest": "5511999999999",
"text": "Press 1 to talk to an agent, 2 to hang up.",
"type": 2,
"ndig": 1,
"dtime": 10,
"dtmfconf": "1",
"dest2": "08001234567",
"fifo": 60
}'
```bash curl (confirmation)
Plays the question tf12345 and waits for 1 or 2; then plays tf12346 and hangs up.
curl -X POST ‘https://
-H ‘Content-Type: application/json’
-d ‘{
“tsid”: “YOUR_TSID”,
“dest”: “5511999999999”,
“type”: “6”,
“content”: “tf12345”,
“dtmfini”: “1|2”,
“content4”: “tf12346”,
“dtmf”: “NO”,
“dtmf2”: “NO”
}’
```bash curl (agent bridge)
curl -X POST 'https://<base>/api/v2/MakeTTSCall.php' \
-H 'Content-Type: application/json' \
-d '{
"tsid": "YOUR_TSID",
"dest": "5511999999999",
"type": 100,
"dtmfini": "42",
"rec": 1800,
"startrec": "ini"
}'
```bash curl (call answered by a FastVoice AI agent)
Places the call; when the callee answers, the second leg is bridged to the
FastVoice agent RT473 (dest2), which handles the conversation autonomously.
The whole call is recorded from the start (rec/startrec) and capped at 300s.
curl -X POST ‘https://
-H ‘Content-Type: application/json’
-d ‘{
“tsid”: “YOUR_TSID”,
“type”: “3”,
“priority”: “-1”,
“content”: “tf785432937”,
“content1”: “”,
“content2”: “”,
“contentfail”: “”,
“rec”: “300”,
“startrec”: “ini”,
“timelimit”: “300”,
“free”: “1”,
“moh”: “0”,
“dest”: “5516997998564”,
“dest2”: “RT473”
}’
## Response
```json 200 OK
{
"return": {
"status": "OK",
"status_code": "0",
"cd_id": "abc_1234567"
}
}
json 400 Validation
{
"return": {
"status": "number invalid",
"status_code": "203",
"cd_id": "0"
}
}
-
return.status(string) —OKon success; otherwise the failure message. -
return.status_code(string) —0on success; otherwise the numeric error code. -
return.cd_id(string) — Internal call id, prefixed with the customer database alias (<cdcs_db>_<cd_id>). Use it withGetCallStatusto query progress. -
return.warning(string, optional) - Present when a parameter was ignored or limited. It tells how the request was read, so it also comes when the request fails afterwards (for example,244http duplicity). Currently:callerid ignored: not allowed for this account(seecallerid) andtfix limited to the terminations enabled for this account(seetfix). When both apply, they come together, separated by;.
Error codes
In addition to the global authentication codes, MakeTTSCall may return:
| Code | status |
Cause |
|---|---|---|
201 |
No text |
No text*, content, nome, or extra* provided. |
203 |
number invalid |
dest could not be normalized. |
204 |
Invalid content / Invalid content1 … |
Call without text* and a content, content1..content5 or contentfail that is not an audio id (letters and digits only, e.g. tf785432937). |
205 |
Content not found |
An audio parameter references an audio that does not exist or does not belong to the account. In a call without text*, content, content1..content5 and contentfail must exist; any audio parameter (content, content1..content15, contentno, contentend, contentfail, contentdtmf, amd) pointing to another account’s audio is rejected. Audios shared by Velip (e.g. silences) and by accounts of the same corporate group are allowed. |
208 |
Invalid rurl: … |
rurl is not a valid URL or points to an internal address. |
209 |
Voice not found |
The call has text and voice is not one of the voices returned by GetTTSVoices for the account. The call is not placed. |
210 |
TTS … not permitted in MakeTTSCall |
Voice provider not allowed for this endpoint (e.g., ElevenLabs). |
220 |
DP |
Duplicate ctid for the customer (when cdcs_uni_ctid=1). |
230 |
block ddd time |
Regional or holiday block hit. |
244 |
http duplicity |
Duplicate within httpdup window. |
250 |
<MakeCall status> |
Underlying MakeCall.php failed; errodet carries the raw response. |
260 |
error audio file |
Audio queue insertion failed. |
290 |
Inform agent ID / Agent is not valid |
type=100 requires dtmfini=<ccba_id> valid for the account. |
301 |
Sms no action |
SMS follow-up requested without sms_action. |
302 |
Sms no text |
SMS follow-up requested without sms_text. |
304 |
Invalid sms_action |
sms_action is not in [ok, nae, oknae, dtmf1]. |
305 |
Sms text 160 characters |
sms_text longer than 160 characters. |
500 |
internal error |
The voice list could not be read (temporary failure). The call is not placed; repeat the request. |
Notes
- The
cd_idreturned has the form<cdcs_db>_<numericId>. Pass it as-is toGetCallStatus. - Audio files referenced by
content*must already exist (cd_wav) and belong to the account (code205otherwise). Your own audio files auto-renew their expiration when used; assets unused for 180 days may be purged from storage. - For dynamic TTS, set
priority=-20to generate audio synchronously before dialing — useful when the call must go out immediately. - ElevenLabs voices are blocked at this endpoint due to provider TOS. Use Google or Polly voices for
MakeTTSCall.