No Brasil, segundo o Censo Demográfico do IBGE de 2010, há aproximadamente 45 milhões de pessoas que apresentam pelo menos uma das deficiências investigadas. Esse número representa 23,9% da população brasileira. 

Aqui você encontrará:

1. Primeiro Passo
2. Text to Speech
3. Como funcionam as chamadas para esta API
4. Criando a aplicação Node.js

Além disso, outro estudo realizado pelo IBGE informa que 18,6% da população brasileira possui algum tipo de deficiência visual. Desse total, 6,5 milhões apresentam deficiência visual severa, sendo que 506 mil têm perda total da visão (0,3% da população) e 6 milhões, grande dificuldade para enxergar (3,2%). 

Esses dados são extremamente relevantes quando nos preocupamos com a acessibilidade em um momento que todas as atividades são executadas dentro de casa, pelo celular ou computador. Para isso, as organizações precisam se adequarem aos padrões da acessibilidade digital. 

O que é Acessibilidade Digital?

Acessibilidade digital se refere a eliminação de barreiras na web. Para que uma organização se torne uma boa referência em acessibilidade digital ela precisa incluir recursos que possibilitam a navegação, a compreensão e a interação de qualquer pessoa, sem auxilio, no ambiente digital.  

Quando se promove uma inclusão digital voltada para deficientes, as organizações agregam benefícios em seus negócios, já que conseguem atingir uma grande porcentagem da população brasileira que necessita desse suporte.  

Além disso, páginas quem possuem uma boa acessibilidade digital são indexadas com mais facilidade por mecanismos de busca. Desta forma, sua empresa ficará bem posicionada no mercado.  

Como promover acessibilidade digital com notificação de voz?

Utilizar mecanismos de voz é uma boa opção para iniciar o processo de acessibilidade. Pensando nisso, desenvolvemos um tutorial integrando API de Voz da Zenvia em colaboração com a API de Open Banking do Bradesco. O objetivo desse produto é permitir que deficientes visuais possam consultar valores de tarifas de transferências por voz. 

Primeiro Passo

Para criar a conta de acesso à Zenvia APIs, basta entrar no site da Total Voice, preencher as informações e clicar em “CRIAR“.

Após criar a conta, é preciso confirmar o número de celular e o endereço de e-mail para ter acesso ao painel. Após confirmar suas informações é possível acessar o painel e adquirir o Access Token para se autenticar nas requisições à API, você precisará desta informação mais tarde.

Iremos utilizar o recurso TTS (Text To Speech) e as informações sobre os endpoints da API estão disponíveis na documentação.

Text to Speech

A funcionalidade de TTS (Text to Speech) da API de voz da Zenvia nos permite enviar uma uma mensagem de texto e ela transforma o texto em áudio falado e reproduz em uma ligação telefônica para o número indicado na chamada. Assim, quando o número destino atende o mesmo irá escutar uma voz falando a mensagem escrita.

Também podem ser enviadas algumas opções adicionais, tais como aguardar uma resposta do usuário, gravar o áudio da ligação ou colocar um número bina que aparecerá no momento da ligação. Para fins didáticos, vamos utilizar apenas o básico do recurso.

O acesso à API está disponível em Node.js através de uma dependência chamada totalvoice-node, porém ela não tem suporte a typescript e para fins didáticos e para que este tutorial possa ajudar as pessoas que não utilizam Node.js, vamos fazer as chamadas através de requisições http (Hypertext Transfer Protocol).

Como funcionam as chamadas para esta API

A API recebe as requisições através do URL (Uniform Resource Locator) base https://api2.totalvoice.com.br e vamos utilizar o endpoint /tts para acessar o recurso Text to Speech.

Para que a API reconheça o que queremos e quem está solicitando, precisamos enviar uma requisição POST com os seguintes headers:

Content-Type: application/json
access-token: <SEU_ACCESS_TOKEN_DISPONÍVEL_NO_PAINEL>

E um JSON no corpo da requisição neste modelo:

{
    "numero_destino": "11999999999",
    "mensagem": "Mensagem que deseja ser dita no torpedo de voz."
}

Criando a aplicação Node.js

1- Instale o Node.js no seu computador (de preferência a versão LTS);

1.1- opcional – Instale o yarn. O Node.js possui um gerenciador de pacotes padrão chamado npm (Node Package Manager), porém existe um gerenciador diferente chamado yarn. No restante deste artigo, haverão as opções de instalação para ambos gerenciadores de pacote como no passo a seguir.

2- Inicie o projeto criando o package.json com o seguinte comando no terminal:

npm init -y
yarn init -y

3- Instale o ts-node, ts-node-dev e o typescript como dependências de desenvolvimento:

npm i ts-node ts-node-dev typescript -D
yarn add ts-node ts-node-dev typescript -D

3.1 – Instale o arquivo de configuração do typescript:

npx typescript --init

4- Crie um arquivo src/server.ts para testarmos a aplicação:

console.log('Hello World!')

5- Abra o arquivo package.json e insira o script para iniciar o servidor assim como na área grifada em cinza:

{
  "name": "zenvia-voice-bradesco",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "dev": "ts-node-dev --transpile-only --ignore-watch node_modules --respawn src/server.ts"
  },
  "devDependencies": {
    "ts-node": "^9.1.1",
    "ts-node-d": "^1.1.1",
    "typescript": "^4.1.3"
  }
}

5.1- Sempre que você quiser executar a aplicação basta executar no terminal:

npm run dev
yarn dev

6- Instale o Express e o dotenv para criarmos nossa API:

npm i express dotenv && npm i --save-dev @types/express
yarn add express dotenv  && yarn add @types/express -D

7- Instale o Axios para realizarmos as requisições http:

npm i axios
yarn add axios

8- Vamos começar criando o arquivo de configuração do Axios para chamarmos as APIs do Bradesco e da Zenvia services/api.ts:

import axios from 'axios'
  export const apiBradesco = axios.create({
   baseURL: 'https://api.bradesco.com/open-banking/discovery/v1',
  })
  export const apiZenvia = axios.create({
   baseURL: 'https://api2.totalvoice.com.br',
  })

9- Crie um arquivo chamado .env, nele conterá seu token de acesso em uma variável de ambiente, coloque seu token logo após o sinal de =:

VOICE_TOKEN=

10- Volte para o arquivo src/server.ts, ele será o nosso arquivo de configuração do servidor para criarmos nossa API:

import express from 'express'
import bodyParser from 'body-parser'
import routes from './routes'
// Inicializa o express
const app = express()
// Indica para o express usar o JSON parsing do body-parser
app.get('/sendCode/:phone', handleSendCode)
// Indica para o express escutar a porta 4000
app.listen(4000, () => console.log('Servidor rodando na porta 4000.'))

11- Agora, crie o arquivo src/routes.ts que irá conter nossas rotas:

import express, { Request, Response } from 'express' 
const routes = express.Router() routes.get('/:phone', async (request: Request, response: Response) => {
    response.send('Sucesso!')
})
export default routes

Acabamos de criar uma API terá a rota /:phone que aceita o envio do número de destino no seu URL, exemplo: http://localhost:4000/11999999999.

11- Crie uma pasta chamada functions e dentro dela crie os arquivos formatDateTime.ts, formatDuration.ts e formatUnavailableEndpoints.ts com os respectivos códigos:

export const formatDateTime = (datetime: string): string => {
   const splittedDatetime = datetime.split('T')
   const splittedDate = splittedDatetime[0].split('-')
   const splittedTime = splittedDatetime[1].split(':')
 
   return `${parseInt(splittedDate[2])} do ${parseInt(splittedDate[1])} de ${parseInt(splittedDate[0])} às ${parseInt(splittedTime[0])} ${
     splittedTime[0] === '01' || splittedTime[0] === '00' ? 'hora' : 'horas'
   } e ${parseInt(splittedTime[1])} ${
     splittedTime[1] === '01' || splittedTime[1] === '00' ? 'minuto' : 'minutos'
   }`

export const formatDuration = (duration: string): string => {
   const splittedDuration = duration.replace(/[PTM\s]/g, '').split('H')
   
   return `${
     splittedDuration[0] === '0' ? '' : splittedDuration[0] === '1'
       ? splittedDuration[0] + ' hora e'
       : splittedDuration[0] + ' horas e'
   } ${parseInt(splittedDuration[1])} ${
     splittedDuration[1] === '1' || splittedDuration[1] === '01' ? 'minuto' : 'minutos'
   }`

export const formatUnavailableEndpoints = (unavailableEndpoints: string[]): string => {
   let response = ''
   unavailableEndpoints.forEach((endpoint) => {
     response += ', ' + endpoint.split('/')[endpoint.split('/').length - 1]
   })
   
   return response
 }

12- Crie a função generateMessage no arquivo functions/generateMessage.ts que gera a mensagem que será enviada para Zenvia APIs, a partir do retorno da API do Bradesco e das funções que criamos anteriormente:

import { formatUnavailableEndpoints } from './formatUnavailableEndpoints'
  import { formatDateTime } from './formatDateTime'
  import { formatDuration } from './formatDuration'
  
  export const generateMessage = (outages: any[]): string => {
    if (outages.length === 0) {
      return 'Olá! Estou aqui para te informar de que não há nenhuma manutenção agendada.'
    }
  
    let response: string[] = []
    outages.forEach((outage) => {
      response.push( `Há uma manutenção agendada para o dia ${formatDateTime(
        outage.outageTime
      )}, com uma duração de ${formatDuration(outage.duration)}. O motivo é ${
        outage.explanation
      }. Ficarão indisponíveis os endpoints${formatUnavailableEndpoints(
        outage.unavailableEndpoints
      )}.`)
    })
  
    return response.join(' ')
  }

13- Crie a função callToUser, que faz a chamada à API da Zenvia no arquivo functions/callToUser.ts:

import { Response } from 'express'
  import { config } from 'dotenv'
  import api from '../config/api'
  
  // Inicializa o dotenv para podermos acessar informações do arquivo .env
  config()
  
  const callToUser = (mensagem: string, numero_destino: string, response: Response) => {
    api
      .post(
        '/tts',
        {
          numero_destino,
          mensagem,
        },
        {
          headers: {
            'Content-Type': 'application/json',
            'access-token': `${process.env.VOICE_TOKEN}`,
          },
        }
      )
      .then((res: any) => {
        // Armazena o campo sucesso da resposta da API de voz
        const { sucesso } = res.data
  
        // Verifica se o sucesso é verdadeiro
        if (sucesso === true) {
          // Se sim, exibe status de sucesso no console da aplicação
          console.log('Sucesso! A chamada está sendo realizada.')
  
          // Retorna uma resposta de sucesso para quem chamou nossa API
          response.send(
            `Sucesso, resposta da API de torpedos de voz: ${JSON.stringify(
              res.data,
              null,
              4
            )}`
          )
        } else {
          // Se não, exibe status de erro no console da aplicação
          console.log('Erro na chamada.')
  
          // Retorna uma resposta de erro para quem chamou nossa API
          response.send(
            `Erro na chamada para a API de torpedos de voz: ${JSON.stringify(
              res.data,
              null,
              4
            )}`
          )
        }
      })
      .catch((error: any) => {
        // Caso não seja possível chamar a API de voz, exibe um status de erro no console
        console.log('Error:', error)
  
        // Retorna uma resposta de erro para quem chamou nossa API
        response.send('Erro desconhecido ao chamar a API de voz.')
      })
  }
  

14- A parte operacional está pronta, agora precisamos colocar em prática no nosso servidor, então vá até o arquivo src/routes. e configure a rota para que chame toda esta parte operacional:

import { generateMessage } from './functions/generateMessage'
  import express, { Request, Response } from 'express'
  import { apiBradesco } from './services/api'
  import callToUser from './functions/callToUser'
  
  const routes = express.Router()
  
  routes.get('/:phone', async (request: Request, response: Response) => {
    try {
      // Faz uma consulta à API outages do Bradesco e pega a variável outages vinda da resposta da api
      const { data: { data: { outages }, }, } = await apiBradesco.get('/outages')
      // Chama a função que Gera a mensagem de acordo com o retorno da API do Bradesco
      const message = generateMessage(outages)
  
      // Armazena o telefone passado no URL da nossa API em uma variável
      const { phone } = request.params
      console.log('Iniciando o processo de efetuar a ligação...')
  
      // Chama a função que faz a chamada à Zenvia APIs
      callToUser(message, phone, response)
    } catch (error) {
      console.log('error:', error)
      response.send('Erro desconhecido.')
    }
  })
  export default routes

Sua aplicação está pronta. Para testá-la, basta realizar uma chamada GET ao URL http://localhost:4000/<número_do_celular>, se tudo estiver certo, você receberá uma ligação no número passado no URL com a mensagem gerada pela API sobre manutenções nas APIs Bradesco. Você pode fazer o teste usando o próprio navegador.

O objetivo de uma API é justamente a troca de dados entre diferentes sistemas e aplicativos, o que acaba por automatizar muitos processos manuais e acelera a criação de novas funcionalidades, sendo consideradas capacitadoras de eficiência e inovação em muitas empresas. 

Todos os setores de uma organização podem ser beneficiados através da adoção de APIs. Os benefícios não apenas agregam valor para a equipe interna, mas também mais qualidade à experiência do usuário final. 

Benefícios da acessibilidade digital com notificação de voz

Com um mercado cada vez mais concorrente, conectar marcas e consumidores é fundamental. Por isso, garantir a acessibilidade digital é imprescindível. APIs de comunicação como a de Voz proporcionam uma série de facilidades a empresa e ao cliente. 

À partir da API de Voz, o desenvolvedor consegue criar interações e construir soluções com chamadas ou torpedos de voz conectadas à sua aplicação.

Além da autenticação de 2 fatores, esta API permite envio de mensagem de voz, checagem de números de telefone, a construção de uma central PABX na nuvem e acesso a relatórios em tempo real para conhecer o status das chamadas. 

Para usar a API de Voz Zenvia, após criar sua conta na plataforma, é preciso utilizar o access-token e informar os números de origem e destino. Com isso o usuário pode fazer sua primeira ligação.

Você pode acessar o projeto final da aplicação produzida neste tutorial no nosso repositório do github.