Skip to the content.

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:

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.

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:///api/v2/MakeTTSCall.php’
-H ‘Content-Type: application/json’
-d ‘{ “tsid”: “YOUR_TSID”, “dest”: “5511999999999”, “text”: “Hello , your appointment is confirmed.", "nome": "John", "voice": "Google|pt-BR-Wavenet-A", "encoding": "UTF-8" }'


```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:///api/v2/MakeTTSCall.php’
-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:///api/v2/MakeTTSCall.php’
-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" } }

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