Voice

Realice una llamada a un número específico a través de la API de voz de seven. En la versión más simple, puede especificar un texto que se leerá al destinatario a través de nuestra pasarela de Texto a Voz (TTS). Para aplicaciones avanzadas, tiene la opción de enviar el texto en formato SSML.

Enviar llamada de voz

Cree una nueva llamada TTS a un número de teléfono.

curl -X POST https://gateway.seven.io/api/voice \
-H "X-Api-Key: IHR_API_SCHLÜSSEL" \
-H "Accept: application/json" \
-d "to=49176123456789" \
-d "text=Hallo Welt!"

{
    "success": "100",
    "total_price": 0.045,
    "balance": 3509.236,
    "debug": false,
    "messages": [
{
    "id": 1384013,
    "sender": "sender",
    "recipient": "49176123456789",
    "text": "Hallo Welt!",
    "price": 0.045,
    "success": true,
    "error": null,
    "error_text": null
}
    ]
}

Anruf beenden

Este punto final termina una llamada activa. Solo se pueden terminar las llamadas cuyo estado es in-progress.

curl -X POST https://gateway.seven.io/api/voice/123456/hangup \
-H "X-Api-Key: SU_CLAVE_API" \
-H "Accept: application/json"

{
    "success": true,
    "error": null
}

SSML

Con el Speech Synthesis Markup Language (SSML) puede controlar la generación de voz. Utilice SSML para reproducir archivos de audio, cambiar la voz y el idioma, incorporar pausas y mucho más.

Puede encontrar información detallada sobre el uso de SSML y los comandos posibles en la documentación de Microsoft.

### Pausas

¿Desea un poco más de pausa en un punto específico? Puede controlar las pausas a su gusto.

```xml
Ahora viene una pausa.

La pausa ha terminado.

Diferentes voces

Con SSML tiene la posibilidad de seleccionar diferentes voces. Puede distinguir el género entre femenino (female), masculino (male) o voz infantil (child). También están disponibles muchos idiomas internacionales para, por ejemplo, dialectos ingleses, francés, árabe, asiático, croata o ruso. Las voces infantiles no están disponibles en todos los idiomas. Para la etiqueta Voice, el atributo name se compone del código de región (de-DE, o en-US) y el género. Ejemplo "en-us-female".

<voice name="en-gb-female">"Great Britain, whose children we are, and whose language we speak,
should no longer be our standard; for the taste of her writers is already corrupted,
and her language on the decline." -Noah Webster, 1789 </voice>

Oraciones y párrafos

Con las etiquetas p y s puede estructurar un párrafo y las oraciones contenidas en él.

<p>
  <s>Hello, this is the audio book of the little girl with the red balloon!</s>
  <s>I have them read to me every night to fall asleep.</s>
</p>

Códigos y números

Para los códigos se recomienda la lectura como letras y caracteres individuales. Los números se pueden distinguir en números enteros, dígitos individuales y ordinales. A continuación, tres ejemplos de uso diario.

<voice name="de-de-female">
    Der Bestätigungscode lautet:
    <prosody rate="slow">
    <say-as interpret-as="characters">967354</say-as>
    </prosody>
</voice>

Para la entrega de un código, es mejor leerlo carácter por carácter y un poco más lento. Tenga en cuenta en este ejemplo que la "p" minúscula también se lee solo como "P". Por eso dividimos el código de ejemplo "LK9p7U" en dos etiquetas say-as:

<voice name="de-de-female">
  Ihr Code lautet:
  <prosody rate="x-slow">
    <say-as interpret-as="characters">LK9</say-as>klein P
    <say-as interpret-as="characters">7U</say-as>
  </prosody>
</voice>

Los números enteros los sintetizamos sin etiqueta. La síntesis de voz reconoce automáticamente las cantidades de dinero y lee "13,50 Euro" como "13 euros 50 céntimos".

<voice name="de-de-female">
  La suma es de 13,50 euros.
</voice>

Para las medidas de longitud o peso, es mejor escribir las unidades completas.

<voice name="de-de-female">
  El edificio tiene 18 metros de altura. El pez pesa 3,5 kilos.
</voice>

Salida de un archivo de audio

En su SSML, puede reproducir archivos de audio de cualquier fuente.

<audio src="https://static.seven.io/sample.mp3" />

También puede combinar la síntesis de su texto y la reproducción de un archivo multimedia externo.

<voice name="de-de-child">
  Hallo, hör dir das mal an
  <audio src="https://static.seven.io/sample.mp3" />
</voice>

Repetición de una etiqueta de voz

Para la etiqueta voice, se utiliza el atributo loop para establecer el número de repeticiones. Con el atributo opcional loop-info, puede anunciar cada repetición.

<voice name="de-de-female" loop="2" loop-info="Ich wiederhole">
    Der Bestätigungscode lautet:
    <say-as interpret-as="characters">5684</say-as>
</voice>

DTMF

DTMF (Dual-Tone Multi-Frequency) es un método para transmitir dígitos a través de la red telefónica. También se conoce como marcación multifrecuencia. Con DTMF, puede solicitar al receptor que presione una tecla en el teléfono. Esto puede ser, por ejemplo, para confirmar una reserva o para transferir una llamada a un departamento específico. Para evaluar señales DTMF, puede usar la etiqueta DTMF en SSML.

Evaluación de la pulsación de teclas DTMF sin la etiqueta <dtmf/>

Si durante la llamada se presiona una tecla numérica y la llamada no se encuentra explícitamente en una etiqueta <dtmf/>, la señal DTMF se enviará a la URL del webhook almacenada en su cuenta y se mostrará en el campo "voice-dtmf". Puede encontrar información sobre cómo configurar webhooks en nuestra página de Webhooks.

{
  "webhook_event": "voice_dtmf",
  "webhook_timestamp": "2024-08-02T07:28:59+02:00",
  "data": {
    "id": 0,
    "callerId": "4943160049851",
    "recipient": "4943160049851",
    "status": "completed",
    "system": "4915170517246",
    "timestamp": 1722576539,
    "duration": 2.76,
    "pricePerMinute": 0.045,
    "dtmf_digit": 9,
    "total_price": 0.045
  }
}

Evaluación de la pulsación de teclas DTMF con la etiqueta <dtmf/>

<dtmf callback="https://ihre-url.de/dtmf_callback"
    min="2"
    max="2"
    wait="5000"
    invalid="Ungültige Eingabe."
    exit="Danke! Auf Wiederhören">
Bitte geben Sie zwei Zahlen an.
</dtmf>

Puede usar la etiqueta <dtmf/> para solicitar al receptor que presione una tecla en el teléfono. Con los atributos min, max y wait, puede establecer el número de dígitos esperados, el número máximo de dígitos y el tiempo de espera en milisegundos. A través del atributo digits, puede determinar los dígitos permitidos como una expresión regular. Más sobre esto en el siguiente ejemplo para digit. Puede almacenar el mensaje de error para entradas no válidas como el atributo invalid y para una despedida al colgar puede usar exit. Un atributo importante para diálogos más complejos es callback. Con esto, establece una URL para el webhook a la que se enviará la entrada DTMF como una carga útil JSON.

Ejemplo

<bridge number="+49176123456789" digit="*"/>
<voice name="de-de-female">
  <dtmf 
    callback="https://ihre-url.de/dtmf-callback" 
    digits="^[0-9#*]+"
    min="2"
    max="2"
    wait="5000" 
    invalid="Ungültige Eingabe. Bitte versuchen sie es noch einmal."
    short="Bitte geben Sie zwei Zahlen an."
    exit="Danke! Auf Wiederhören">
    Hier ist ihr seven voice service. Bitte geben Sie zwei Zahlen an. Mit der Sterntaste werden Sie mit einem Mitarbeiter verbunden.
  </dtmf>
</voice>

Tan pronto como se realice una entrada válida, el webhook se enviará a la URL especificada con los siguientes datos, donde digits es la secuencia de dígitos ingresada:

{
  "webhook_event": "dtmf",
  "webhook_timestamp": "2024-11-05T10:23:04+01:00",
  "data": {
    "id": "1732712",
    "callerId": "4943130149270",
    "recipient": "49176123456789",
    "foreign_id": "MyForeignId",
    "voice_name": "de-DE-KatjaNeural",
    "digits": "65"
  }
}

Respuesta de su Webhook

Ahora puede controlar el flujo de la llamada a través de la respuesta de su webhook y así realizar un control de llamadas en cascada. Por ejemplo, deje que el webhook reproduzca otro anuncio, conecte la llamada o simplemente termine la llamada. Para ello, devuelva el siguiente anuncio o el comando para finalizar la llamada como respuesta JSON. Si desea sintetizar nuevo texto, puede enviarlo nuevamente en formato de texto SSML o TEXT.

{
  "status": 200,
  "content_type": "application/ssml+xml",
  "content": "<voice name=\"de-de-female\">Danke für Ihre Eingabe. Auf Wiederhören.</voice>"
}

Respuestas de ejemplo

Tenga en cuenta que aquí no siempre se muestran las estructuras JSON completas, sino solo las partes relevantes.

Termine la llamada:

{
   "hangup": true
}

Reproduzca otro anuncio. Aquí también puede usar cualquier SSML:

{
   "ssml": "<voice name=\"de-de-female\">Danke für Ihre Eingabe. Auf Wiederhören.</voice>",
   "hangup": true,
   "min": 1,
   "max": 3,
   "tries": 5
}

Establezca nuevos dígitos:

{
   "digits": "^[3-5#*]+"
}

Redirija a un teléfono:

{
   "bridge": {
      "number": "+49176123456789"
   }
}

Respuestas de ejemplo para la transferencia de llamadas

Para la transferencia de llamadas hay dos posibilidades diferentes. Puede transferir la llamada directamente a otro número de teléfono (sin digit) o vincularla a una tecla (con digit). Cuando se presiona la tecla o se ingresa el número esperado, la llamada se transfiere al número de teléfono registrado y se interrumpen todos los anuncios en curso.

<bridge number="+49176123456789" digit="*"/>

digit puede ser una expresión regular. Esta se inicia con una tilde ~. Aquí, por ejemplo, se espera la tecla de asterisco o el número 9 tres veces:

<bridge number="+49176123456789" digit="*~9{3}"/>

Si no envía una respuesta válida, la llamada se terminará automáticamente.

Estado de la llamada

Recibirá el estado actual de la llamada inmediatamente con cada cambio a través de Webhook.