Saltar a: navegación, buscar

API de mensajes de voz

Descripción API de mensajes de voz

Con esta API usted podrá subir mensajes (mediante ficheros WAV/MP3 o utilizando nuestra herramienta de síntesis de texto a voz) a los diferentes puntos de reproducción de mensajes de voz de su Número Virtual o extensión de Centralita.

Si no sabe lo que es una API lea ¿Qué son las APIs de Telefácil?

Activación API de mensajes de voz

Este servicio debe activarse explícitamente dentro de la web, en Desarrolladores > Permisos de las APIs. En esa sección también se pueden restringir (opcionalmente) las direcciones IP desde las que se puede llamar a través de esta aplicación web. Si usted tiene una dirección IP fija por favor introdúzcala aquí, aumenta la seguridad.

URL

La API de mensajes de voz se ofrece como un servicio web, accesible mediante la URL:

https://scgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?principal=xxxxxxxxx&pass=xxxxxxxx&tipo_ov=numero_virtual&tipo_mensaje=buzon&destino_mensaje=902009955&tipo_entrada=fichero&fichero=C:\mensaje.mp3&tipo_fichero=mp3

Para los clientes de Canarias, la URL es:

https://cgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?principal=xxxxxxxxx&pass=xxxxxxxx&tipo_ov=numero_virtual&tipo_mensaje=buzon&destino_mensaje=902009955&tipo_entrada=fichero&fichero=C:\mensaje.mp3&tipo_fichero=mp3

La petición deberá realizarse vía POST multipart/form-data. El fichero a enviar debe ser local.

Parámetros obligatorios

  • 'principal' es el número de teléfono del cliente (con el que se dio de alta), también llamado "usuario de la cuenta Telefácil".
  • 'pass' es la contraseña de la cuenta Telefácil.
  • 'tipo_ov': debe ser uno de los valores 'numero_virtual', 'centralita' o 'boton_web'.
  • 'tipo_mensaje': debe ser alguno los siguientes valores.
    • 'buzon': Mensaje del buzón de voz de su Número Virtual o extensión, que se activará si no hay desvíos disponibles (p. ej.: "En este momento no podemos atenderle, deje su mensaje después de oír la señal").
    • 'aviso': La locución de aviso se activa al contestar la llamada, y sirve para indicarle que esta se realiza a través de su Oficina Virtual.
    • 'predesvio': Mensaje de predesvío para su Número Virtual o extensión que se escuchará (completo) antes de desviar la llamada (p. ej.: información relevante que debe ser escuchada en su totalidad).
    • 'durante': Este mensaje se activará durante el desvío de la llamada. Finalizará cuando se conteste la llamada o salte el buzón de voz. Deberá ser un mensaje corto y sin relevancia (p. ej.: una melodía o del tipo "su llamada es importante").
    • 'secr_nombre': Mensaje que escuchará el llamante si usted activa el filtro secretaria para su Número Virtual o extensión durante el desvío de la llamada (p. ej. "Diga su nombre y el motivo de su llamada"). Usted, antes de conectar con el llamante, sabrá quién le llama, teniendo la posibilidad de desviarlo al buzón de voz o simplemente cortar la llamada.
    • 'secr_transf': Este mensaje lo escuchará el llamante después de pasar por el filtro de secretaria virtual y usted haya aceptado la llamada (p. ej. "Estamos transfiriendo su llamada").
    • 'secr_op5': Mensaje que escuchará el llamante si usted elige la opción 5 en el menú de secretaria virtual (activando mensaje de rechazo y cortar llamada). P. ej.: "El usuario ha restringido sus llamadas".
    • 'filtro_normal': Si usted filtra un número llamante y selecciona la opción "cortar con mensaje", se activará la locución que usted suba aquí (p. ej. "El usuario ha restringido sus llamadas").
    • 'filtro_privado': Si usted decide filtrar las llamadas entrantes que le llegan como número privado con la opción "cortar con mensaje", podrá activar un mensaje del tipo "Hemos restringido las llamadas para los números privados".
    • 'centralita': (Solo centralitas). Mensaje de bienvenida de la centralita: es el primer mensaje que oye el llamante. Debe indicar qué extensiones son las que hay marcar.
    • 'pecera': (Solo centralitas). Mensaje que se escuchará en la extensión si tiene asociada una cola de llamadas (p. ej. "Su llamada es importante, por favor espere hasta que haya un operador disponible").
    • 'pecera_2': (Solo centralitas). Si la extensión tiene asociada una cola de llamadas y esta cola permite que el llamante marque # # para salir de ella, este es el mensaje que se escuchará a partir del primer minuto de espera, para informar o recordar al llamante que esta opción está disponible (p. ej. "Si desea salir de la cola de llamadas, marque almohadilla almohadilla").
    • 'cp_marque': (Solo centralitas). Mensaje de bienvenida de la centralita cuando hay códigos postales. Debe indicar al llamante que marque su código postal.
    • 'cp_mal': (Solo centralitas). Mensaje que suena cuando el código postal es incorrecto.
    • 'cp_nohay': (Solo centralitas). Mensaje que suena cuando el código postal es correcto pero no está asociado con una extensión (no hay servicio para ese código postal).
    • 'botonweb': Mensaje que se activará cuando le llamen a través de su botón web. P. ej.: "Estamos transfiriendo su llamada".'
    • 'aviso_salida': Mensaje que se reproducirá cuando se establezca una llamada saliente, tal como en Locución para llamadas salientes. En este caso no hace falta especificar 'tipo_ov'.
  • 'destino_mensaje': debe ser el número virtual o la extensión a la que se le sube el mensaje. Puede especificarse "todos" para que se suba a todos los números virtuales o extensiones.
  • 'tipo_entrada': puede ser 'texto' si se manda un mensaje escrito para su posterior síntesis de voz; 'fichero' si se manda un fichero (se admiten MP3 o WAV); o 'borrar' para eliminar un mensaje de voz previamente subido.
    • si tipo_entrada=fichero, deben enviarse además los campos:
      • 'fichero', con el fichero correspondiente (el envío debe ser POST+multipart)
      • 'tipo_fichero', con el tipo de fichero enviado ('mp3' o 'wav')
    • si tipo_entrada=texto, se pueden enviar 1 o varios textos numerados desde el 0 (vw_texto0, vw_texto1...), con los siguientes parámetros
      • 'vw_elementos=N', donde N es un número mayor o igual a 1. Indica el número de textos que se envían.
      • 'vw_textoX=hola+que+tal', donde X es un número entre 0 y N-1. Contiene el texto que deseamos sintetizar. Debe estar codificado con URLEncode.
      • 'vw_vozX', donde X es un número entre 0 y N-1. Contiene un número que representa la voz que se va a usar para sintetizar el texto enviado. Por ejemplo, si queremos usar a Jorge, haríamos vw_voz0=2. Las voces son:
        • Español: 1 - Carmen, 2 - Jorge, 3 - Juan, 4 - Leonor, 5 - Francisca (Chile), 6 - Diego (Argentina), 7 - Esperanza (México), 8 - Carlos (América Latina), 9 - Soledad (América Latina), 10 - Ximena (América Latina)
        • Catalán: 11 - Jordi, 12 - Montserrat, 13 - Empar (Valencia)
        • Gallego: 14 - Carmela
        • Vasco: 15 - Arantxa
        • Inglés: 16 - Allison (USA), 17 - Dave (USA), 18 - Steven (USA), 19 - Susan (USA), 20 - Catherine (UK), 21 - Elizabeth (UK), 22 - Simon (UK), 23 - Alan (Australia), 24 - Grace (Australia), 25 - Veena (India)
        • Alemán: 26 - Katrin, 27 - Stefan
        • Francés: 28 - Bernard, 29 - Florence, 30 - Jolie, 31 - Charlotte (Canadá), 32 - Olivier (Canadá)
        • Portugués: 33 - Amalia, 34 - Eusebio, 35 - Fernanda (Brasil), 36 - Gabriela (Brasil), 37 - Felipe (Brasil)
        • Italiano: 38 - Federica, 39 - Giulia, 40 - Luca, 41 - Marcello, 42 - Matteo, 43 - Paola, 44 - Roberto, 45 - Silvana, 46 - Valentina
        • Griego: 47 - Afroditi, 48 - Nikos
        • Sueco: 49 - Annika, 50 - Sven
        • Chino: 51 - Linlin, 52 - Lisheng
        • Holandés: 53 - Saskia, 54 - Willem
        • Polaco: 55 - Krzysztof, 56 - Zosia
        • Turco: 57 - Kerem, 58 - Selin, 59 - Zeynep
        • Danés: 60 - Frida, 61 - Magnus
        • Noruego: 62 - Henrik, 63 - Vilde
        • Ruso: 64 - Dmitri, 65 - Olga
        • Finlandés: 66 - Marko, 67 - Milla
        • Árabe: 68 - Laila, 69 - Tarik
        • Rumano: 69 - Ioana
        • Esperanto: 70 - Ludoviko
        • Japonés: 71 - Misaki, 72 - Show
        • Koreano: 73 - Junwoo, 74 - Yumi
      • 'vw_velocidadX' (opcional), donde X es un número 0 y N-1. Puede ser entre -3 (muy lento) y 3 (muy rápido). Por defecto es 0 (normal).

Tenga en cuenta que el número de síntesis de texto a voz está limitada por día.

Parámetros opcionales

  • 'solo_para_llamante=XXXXXXXXX', donde XXXXXXXXX es el número de teléfono del llamante al cual se le va poner el mensaje de voz (en el mensaje durante el desvío).
  • 'solo_para_receptor=XXXXXXXXX', donde XXXXXXXXX es el número de centralita donde va a sonar el mensaje de voz (en el mensaje de centralita y en la locución de aviso).
  • 'con_horario=1', para especificar el horario del mensaje. Dispone de los siguientes parámetros:
    • 'hora_inicio': 00-23
    • 'min_inicio': 00-59
    • 'hora_final': 00-23
    • 'min_final': 00-59
    • 'lunes=1', 'martes=1', 'miercoles=1', 'jueves=1', 'viernes=1', 'sabado=1', 'domingo=1', 'festivos=1'

Ejemplos API de mensajes de voz

Ponemos "Deje un mensaje" en el buzón de voz del número virtual 902009955 de la cuenta 999111222, con la voz de Leonor.

https://scgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?principal=999111222&pass=MiClaveSecr&tipo_ov=numero_virtual&tipo_mensaje=buzon&destino_mensaje=902009955&tipo_entrada=texto&vw_elementos=1&vw_texto0=Deje+un+mensaje&vw_voz0=4

Borrar el anterior mensaje:

https://scgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?principal=999111222&pass=MiClaveSecr&tipo_ov=numero_virtual&tipo_mensaje=buzon&destino_mensaje=902009955&tipo_entrada=borrar

Subimos el fichero C:/mensaje.mp3 como mensaje de la centralita 902009955 de lunes a viernes de 09:00 a 18:00.

https://scgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?principal=999111222&pass=MiClaveSecr&tipo_ov=centralita&tipo_mensaje=centralita&destino_mensaje=todos&solo_para_receptor=902009955&tipo_entrada=fichero&&fichero=C:\mensaje.mp3&tipo_fichero=mp3

Ponemos un mensaje compuesto en el buzón de voz del número virtual 902009955 de la cuenta 999111222. Primero dice "Bienvenido a Duocom" con la voz de Jorge. Después dice "Deje su mensaje" con la voz de Leonor.

https://scgi.duocom.es/cgi-bin/telefacil2/api_subir_voz?
  principal=999111222&pass=MiClaveSecr&tipo_ov=numero_virtual&tipo_mensaje=buzon&destino_mensaje=902009955&tipo_entrada=texto&vw_elementos=2&
  vw_texto0=Bienvenido+a+Duocom&vw_voz0=2&
  vw_texto1=Deje+un+mensaje&vw_voz1=4

Resultado

De devuelve un código XML. Si no hay error, pondrá lo siguiente;

<voz>
  <error>0</error>
</voz>

Si hay error, mostrará algo como esto:

<voz>
  <error>234</error>
  <msgerr>Explicación del error</msgerr>
</voz>

Notas API de mensajes de voz

Tenga presente que, aunque la aplicación web es accesible mediante una URL, no debe poner nunca enlaces a esta aplicación directamente en el código fuente de sus páginas web, ya que sus visitantes podrían descubrir datos sensibles como su número de usuario y su contraseña simplemente mirando el código HTML.

La aplicación web debe ser llamada siempre desde el servidor, usando para ello alguna de las librerías que permite llamadas a servicios HTTPS.





Indice

Página principal >> Desarrolladores >> API de mensajes de voz.