TuCloudAPI addextension

TuCloudAPI function to manage FuturePBX (the cloud PBX). Available to: SuperRoot, Operator, Client.

ℹ Requires the pbx parameter (the PBX name, e.g. tucall). The server verifies that your ukey's own account owns that PBX, whatever its role; otherwise, and also for a PBX that does not exist, it returns {"ok":false,"code":"forbidden"}.

Description

Create an extension. The server derives num (max+1, else 200; 112->113), the SIP user (pbxname+num) and — unless password is supplied — a random SIP password; root/tucloudpbx_id come from the tenant. Every lookup id is validated to belong to this PBX. Unique (pbx,num) -> {ok:false,conflict}. The SIP peer + voicemail are created automatically by the DB trigger. Requires a non-readonly ukey. Password is NOT returned (use getextqr).

Call

https://tucloudapi.7kas.com:9087/tucloud?func=addextension&ukey=YOUR_KEY&pbx=PBX_NAME

GET, or POST with the parameters form-urlencoded in the body. Requires the ukey parameter. Always HTTP 200; the response is a JSON envelope.

Parameters

Parameter	Type	Required	Default	Meaning
pbx	string	Yes	—	FuturePBX NAME (e.g. tucall). The (ukey, pbx) pair is the tenant boundary; the server verifies the ukey owns this PBX.
name	string	Yes	—	Display name (required, max 64).
cli_id	integer	Yes	—	Outgoing caller ID id (required; from getextlookups.clis).
ringtime	integer	No	0	Ring seconds: 0 (PBX default) or 5-50.
internalcli_id	integer	No	0	Internal/mobile CLI id (0 = none).
teamsopt	string	No	S	T=Teams, S=VoIP, TS=both.
teamsnum	string	No	—	Teams number (digits only, max 64; unique).
pickupgroup	integer	No	0	Pickup group 0-999.
toext_id	integer	No	0	Send-to extension id (0 = registered SIP mode).
password	string	No	—	Explicit SIP password (blank = auto-generate).
backupnum	string	No	—	Backup number (digits and +, max 64).
backupmonpeer	string	No	—	Extension num to monitor for backup.
music	integer	No	0	Music-on-hold id (0 = default).
tom	integer	No	0	0=tone, 1=music.
voicemail	integer	No	0	1=enable voicemail.
email	string	No	—	Voicemail/notification email.
incom_only_contacts	integer	No	0	1=accept only contacts/extensions.
fwdshowcaller	integer	No	0	1=show original caller on forward.
fwd_cli	integer	No	0	External-forward caller-ID (0=Si,1=No; inverse).
fwd	integer	No	0	External forward: 0=off,1=all,2=busy,3=noanswer,4=busy/noanswer.
fwdnum	string	No	—	External forward destination.
fwd_internal	integer	No	0	Internal forward (same 0-4 scale).
fwdnum_internal	string	No	—	Internal forward destination.
recoutgoing	integer	No	0	1=record outgoing calls.
only_contacts	integer	No	0	1=restrict outbound to contacts.
outs_id	integer	No	0	Outgoing service id (0 = none).
nota	string	No	—	Free note (max 256).
translator_langs	string	No	—	Idiomas que el usuario ENTIENDE, separados por comas (ej. "es,ca,en"), máx. 64. Si la otra parte habla uno de estos, no se traduce ni se factura. Se RECHAZA si excede 64: truncar dejaría fuera el último idioma y traduciría (y cobraría) llamadas que el usuario ya entendía.
translator_lang	string	No	—	Idioma de la traducción. Obligatorio si translator_mode no es 0; con modo 0 se IGNORA. Debe ser un código de la tabla oficial del servicio, EXACTO y respetando las mayúsculas: «pt-BR» vale y «pt-br», «PT-BR» o «ES» se rechazan. Guion, nunca subrayado. Los 79 códigos admitidos: af ak sq am ar hy az eu be bn bg my ca zh-Hans zh-Hant hr cs da nl en et fil fi fr gl ka de el gu ha he hi hu is id it ja jv kn kk km rw ko lo lv lt mk ms ml mr mn ne no nb fa pl pt-BR pt-PT pa ro ru sr sd si sk sl es su sw sv ta te th tr uk ur uz vi zu. OJO: el portugués y el chino SOLO existen como pt-BR/pt-PT y zh-Hans/zh-Hant — no hay «pt» ni «zh» a secas. Un código fuera de la tabla se rechaza aquí a propósito: el servicio aceptaría el armado y cerraría la sesión después, así que la llamada saldría SIN traducir, sin señal en la centralita y con la detección facturada igual. Los cuatro códigos con guion (pt-BR, pt-PT, zh-Hans, zh-Hant) estuvieron retenidos hasta el 2026-10-01 porque el motor aún no los traducía; ya están disponibles y se aceptan como el resto.
translator_mode	integer	No	—	Máscara de bits (OR de flags), 0 = desactivada, rango 0-63. ÁMBITO, elige QUÉ llamadas se traducen: 1 = entrante externa (una llamada de fuera/DID llega a esta extensión); 2 = saliente externa (esta extensión llama a un número externo/RTC); 4 = entrante interna (otra extensión del mismo PBX llama a esta); 8 = saliente interna (esta extensión llama a otra del mismo PBX). MODIFICADOR, elige EN QUÉ LADO se detecta el idioma: 16 = translator_lang es el idioma del INTERLOCUTOR y no el de esta extensión, así que se detecta siempre el de esta y se traduce al configurado para el otro lado; sirve igual en entrantes y salientes. 32 = TRADUCCIÓN PERMANENTE: sin este bit, si el idioma que se detecta resulta ser uno que el otro lado ya entiende, la traducción de ESA llamada se apaga hasta colgar y no se traduce nada más aunque cambie el idioma — así se ahorra el coste. Con el bit 32 la llamada no se apaga nunca: se sigue escuchando y se traduce en cuanto se oye un idioma ajeno, y mientras solo se hablen idiomas entendidos no se dice nada (el español no se repite en español); la escucha se factura toda la llamada. Importa sobre todo cuando el lado detectado es un manos libres: la voz del otro, captada por su micrófono, puede detectarse como idioma de ese lado y dejar la llamada sin traducción para siempre. En una decisión conjunta basta que lo tenga UNA de las filas que participa. 16 y 32 son MODIFICADORES: no activan nada por sí solos, así que un modo con solo modificadores y ningún ámbito se rechaza — marca también cuándo traducir, o deja el modo en 0. UNA SOLA sesión de traducción por llamada, nunca dos. Quién la decide, en una llamada interna (a otra extensión o a un grupo): (a) si esta extensión tiene el bit 16 Y LOS DOS bits de saliente (2 y 8) Y un idioma válido, la arma ella al empezar la llamada, antes de saber el destino, y los ajustes del destino NO se usan; (b) en cualquier otro caso basta que el que llama tenga su bit 8 O el llamado su bit 4, y se toma UNA decisión conjunta con las DOS filas: el idioma del que llama para su pata, el del llamado para la suya, y la lista de idiomas que entiende cada uno — si hablan el mismo idioma o se entienden, no se arma nada. Un lado con translator_mode 0 NO declara nada: su idioma y su lista se ignoran a propósito, para que un dato viejo no pueda vetar en silencio lo que el otro lado sí pidió; su pata se queda en automático y el motor detecta lo que oye. Entrante por un DID (bit 1): decide el destino, salvo que quien llame sea un número de este mismo PBX — esa llamada la puso la centralita y ahí no se arma nada. Un modo distinto de 0 con translator_lang vacío se rechaza: el traductor no se armaría y la llamada no se traduciría sin que nada lo indicase. Omitir el parámetro CONSERVA el valor.

Example

https://tucloudapi.7kas.com:9087/tucloud?func=addextension&ukey=KEY&pbx=tucall&name=Recepcion&cli_id=81324

Response

{ok, ext:{...}} (no password).

Errors

Always HTTP 200. On failure the body is {"ok":false,"code":"...","message":"..."}. Common codes: missing_pbx, forbidden, invalid_param, not_found, conflict, in_use, db_error, server_busy; the Response section above lists any specific to this function.

---

Back to TuCloudAPI