Voice

Inicie uma chamada para um número específico através da API de voz da seven. Na versão mais simples, você pode especificar um texto que será lido para o destinatário através do nosso gateway de Texto-para-Fala (TTS). Para aplicações avançadas, você tem a opção de enviar o texto no formato SSML.

Enviar chamada de voz

Crie uma nova chamada TTS para um número de telefone.

curl -X POST https://gateway.seven.io/api/voice \
-H "X-Api-Key: SUA_CHAVE_API" \
-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
}
    ]
}

Encerrar chamada

Este endpoint encerra uma chamada ativa. Somente chamadas com status in-progress podem ser encerradas.

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

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

SSML

Através da Speech Synthesis Markup Language (SSML), você pode controlar a geração de fala. Use SSML para tocar arquivos de áudio, alterar a voz e o idioma, inserir pausas e muito mais.

Informações detalhadas sobre o uso de SSML e os comandos possíveis podem ser encontradas na documentação da Microsoft.

Pausas

Deseja uma pausa maior em um determinado ponto? Você pode controlar as pausas conforme necessário.

Agora vem uma pausa.
<break time="2s" />
A pausa acabou.

Diferentes Vozes

Com SSML, você tem a possibilidade de selecionar diferentes vozes. Você pode distinguir o gênero entre feminino (female), masculino (male) ou voz infantil (child). Além disso, muitas línguas internacionais estão disponíveis para, por exemplo, dialetos ingleses, francês, árabe, asiático, croata ou russo. As vozes infantis não estão disponíveis em todos os idiomas. Para a tag Voice, o atributo name é composto pelo código da região (de-DE, ou en-US) e o gênero. Exemplo "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>

Frases e Parágrafos

Com as tags p e s, você pode estruturar um parágrafo e as frases contidas nele.

<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 e Números

Para códigos, recomenda-se a leitura como letras e caracteres individuais. Números podem ser diferenciados em inteiros, dígitos individuais e ordinais. A seguir, três exemplos do uso diário.

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

Para a entrega de um código, é melhor ler caractere por caractere e um pouco mais devagar. Observe neste exemplo que o "p" minúsculo também é lido apenas como "P". Por isso, separamos o código de exemplo "LK9p7U" em duas tags 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>

Inteiros são sintetizados sem tag. A síntese de fala reconhece automaticamente valores monetários e lê "13,50 Euro" como "13 Euros e 50 Centavos".

<voice name="de-de-female">
  A soma é de 13,50 Euros.
</voice>

Para medidas de comprimento ou peso, é melhor escrever as unidades por extenso.

<voice name="de-de-female">
  O edifício tem 18 metros de altura. O peixe pesa 3,5 quilos.
</voice>

Reprodução de um arquivo de áudio

No seu SSML, você pode reproduzir arquivos de áudio de qualquer fonte.

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

Você também pode combinar a sintetização do seu texto com a reprodução de um arquivo de mídia externa.

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

Repetição de uma tag de voz

Para a tag voice, o atributo loop é usado para definir o número de repetições. Com o atributo opcional loop-info, você pode anunciar cada repetição.

<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) é um método para transmitir dígitos através da rede telefônica. Também é conhecido como discagem multifrequencial. Com DTMF, você pode solicitar que o receptor pressione uma tecla no telefone. Isso pode ser usado, por exemplo, para confirmar uma reserva ou encaminhar uma chamada para um determinado departamento. Para avaliar sinais DTMF, você pode usar a tag DTMF no SSML.

Avaliação de pressionamento de tecla DTMF sem a tag <dtmf/>

Se uma tecla numérica for pressionada durante a chamada e a chamada não estiver explicitamente em uma tag <dtmf/>, o sinal DTMF será enviado para a URL do webhook configurada na sua conta e exibido no campo "voice-dtmf". Informações sobre como configurar webhooks podem ser encontradas em nossa página de Webhook.

{
  "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
  }
}

Avaliação de pressionamento de tecla DTMF com a tag <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>

Você pode usar a tag <dtmf/> para solicitar que o receptor pressione uma tecla no telefone. Com os atributos min, max e wait, você pode definir o número de dígitos esperados, o número máximo de dígitos e o tempo de espera em milissegundos. Com o atributo digits, você pode determinar os dígitos permitidos como uma expressão regular. Mais sobre isso no exemplo a seguir para digit. A mensagem de erro para entradas inválidas pode ser definida como o atributo invalid e para uma despedida ao desligar, você pode usar exit. Um atributo importante para diálogos mais complexos é callback. Com ele, você define uma URL para o webhook para a qual a entrada DTMF será enviada como um payload JSON.

Exemplo

<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>

Assim que uma entrada válida for feita, o webhook será enviado para a URL especificada com os seguintes dados, onde digits é a sequência de dígitos inserida:

{
  "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"
  }
}

Resposta do seu Webhook

Você pode agora controlar o fluxo da chamada através da resposta do seu webhook, permitindo assim uma gestão de chamadas em cascata. Por exemplo, deixe o webhook reproduzir outro anúncio, conectar a chamada a outro destino, ou simplesmente encerrar a chamada. Para isso, retorne o próximo anúncio ou o comando para encerrar a chamada como uma resposta JSON. Se desejar sintetizar um novo texto, você pode enviá-lo novamente como texto SSML ou TEXT.

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

Exemplos de Respostas

Por favor, note que nem sempre as estruturas JSON completas são mostradas aqui, apenas as partes relevantes.

Encerre a chamada:

{
   "hangup": true
}

Reproduza outro anúncio. Aqui você também pode usar qualquer SSML:

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

Defina novos dígitos:

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

Encaminhe para um telefone:

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

Exemplos de Respostas para Transferência de Chamada

Para o encaminhamento de chamadas, existem duas possibilidades diferentes. Você pode encaminhar a chamada diretamente para outro número de telefone (sem digit) ou vinculá-la a uma tecla (com digit). Quando a tecla é pressionada ou o número esperado é inserido, a chamada é encaminhada para o número de telefone armazenado e todos os anúncios em andamento são interrompidos.

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

digit pode ser uma expressão regular. Esta é iniciada com um til ~. Aqui, por exemplo, é esperada a tecla asterisco ou o número 9 três vezes:

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

Se você não enviar uma resposta ou enviar uma resposta inválida, a chamada será encerrada automaticamente.

Status do Chamado

Você receberá o status atual do chamado imediatamente a cada alteração via webhook.