Receber uma ligação com a Voice API e o Swift

Neste tutorial, você criará um aplicativo em Swift capaz de receber chamadas telefônicas usando o Vapor e a API Nexmo Voice. Você pode seguir este tutorial tanto no macOS quanto no Ubuntu.

Para ver a solução completa, confira este repositório do GitHub.

Pré-requisitos

• O CLI da Nexmo — você usará isso para criar uma aplicação, adquirir um número e vincular os dois

• Swift 4.1 ou superior — no macOS, o Xcode 9.3 ou superior já dá conta do recado

O Plano

Este tutorial irá guiá-lo pelas seguintes etapas:

• Conheça os Concepts da Nexmo

• Criar um novo projeto no Vapor

• Adicione uma rota para a resposta por Voice

• Exponha o aplicativo usando o ngrok

• Adquira um número da Nexmo

• Crie uma aplicação Nexmo para usar com o número

• Teste seu aplicativo

Concepts da Nexmo

Antes de entrarmos nos detalhes da montagem, aqui estão alguns Concepts que você precisa entender.

A aplicativo da Nexmo permite que você utilize facilmente os produtos da Nexmo; neste caso, a Voice API para criar aplicativos de voz na nuvem.

Uma aplicação da Nexmo requer duas URLs como parâmetros:

• answer_url - A Nexmo enviará uma solicitação para esta URL assim que a chamada for atendida

• event_url - A Nexmo envia informações sobre eventos de forma assíncrona para esta URL quando o status da chamada muda; isso, em última análise, define o fluxo da chamada

Ambas as URLs precisam retornar JSON e seguir o referência do Nexmo Call Control Object (NCCO) . No exemplo abaixo, você definirá um NCCO que lê um texto predefinido para uma chamada recebida, utilizando a função módulo de conversão de texto em fala .

A número virtual da Nexmo será associado ao aplicativo e servirá como o “ponto de entrada” para ele — esse é o número para o qual você ligará para testar o aplicativo.

Para obter mais informações sobre o aplicativo Nexmo, acesse a Referência da API.

Novo Projeto Vapor

Você usará o Vapor para criar um aplicativo web simples em Swift — caso ainda não tenha o Vapor instalado, faça o download executando este comando:

Estão disponíveis instruções detalhadas de instalação para MacOS e Ubuntu.

Na linha de comando, navegue até o local adequado onde deseja que seu projeto fique armazenado (por exemplo, o diretório “Documentos”) e crie um novo aplicativo Vapor:

Se você estiver usando o macOS, é possível vapor criar automaticamente um projeto do Xcode para você (a -y opção abrirá automaticamente o projeto do Xcode):

Compile e execute para testar seu aplicativo, garantindo que o Run esquema esteja selecionado. Assim que tudo estiver compilado, o servidor será iniciado e você verá uma mensagem no console:

Server starting on http://localhost:8080

Acesse essa URL no seu navegador e uma It works! deverá aparecer uma mensagem.

Adicionar a rota

Agora você vai adicionar uma rota que servirá como answer_url para o aplicativo Nexmo. http://localhost:8080/webhooks/answer responderá com o seguinte objeto JSON:

[
    {
        "action":"talk",
        "text":"<speak>To be <break strength='weak' \/> or not to be <break strength='weak' \/> that is the question.<\/speak>"
    }
]

Um projeto Vapor armazena suas rotas no routes.swift arquivo dentro do Sources/App grupo. Abra esse arquivo, apague todas as rotas existentes e defina a nova rota:

import Vapor

public func routes(_ router: Router) throws {
    router.get("/webhooks/answer") { request -> String in
        let talk = Action(
            action: "talk",
            text: "<speak>To be <break strength='weak' /> or not to be <break strength='weak' /> that is the question.</speak>")
        let encoder = JSONEncoder()
        guard let data = try? encoder.encode([talk]) else { return "error encoding" }
        return String(data: data, encoding: .utf8) ?? "error"
    }
}

Action é uma estrutura simples estrutura em Swift para armazenar os detalhes da ação NCCO — defina-a após o closure do roteador:

struct Action: Encodable {
    var action: String
    var text: String
}

Ao codificar Action em conformidade com Encodable, você garante que o JSONEncoder possa usá-lo.

Compile e execute o aplicativo e teste a saída da nova rota em: http://localhost:8080/webhooks/answer.

Agora você tem uma URL que será usada como o answer_url.

Divulgue seu aplicativo

Para que a Nexmo consiga acessar seu aplicativo Vapor, ela precisa acessar uma URL disponível publicamente — seu aplicativo é executado em seu computador e só pode ser acessado dentro da sua rede local.

ngrok é um utilitário simples que disponibiliza seu servidor web local por meio de URLs públicas.

Com o ngrok instalado, execute o seguinte comando:

Anote o endereço de encaminhamento, pois você precisará dele ao configurar sua conta — veja abaixo um exemplo de resultado — o endereço de encaminhamento é https://7ffc0230.ngrok.io.

Comprar um número

Esse será o número para o qual você ligará para se conectar ao seu aplicativo Nexmo. O exemplo abaixo usa um número dos EUA, mas há números disponíveis para outros países disponíveis.

Observação: Ao se cadastrar para um Account Nexmo, €2,00 são creditados no seu saldo, o que será mais do que suficiente para obter um número.

Para adquirir um novo número, use a CLI do Nexmo:

Anote o novo número que lhe foi atribuído no momento da compra; você precisará dele mais tarde.

Criar uma aplicação Nexmo

Agora você vai integrar tudo criando um nova aplicação Nexmo usando o endereço de encaminhamento do ngrok:

Observação: O segundo parâmetro da URL, http://your-ngrok-forwarding-address/webhooks/events, não existe e você nunca vai realmente usá-lo, mas é necessário especificar uma URL de evento ao criar um aplicativo Nexmo.

A saída gerada pelo comando acima incluirá o ID do novo aplicativo (por exemplo: Aplicativo criado: 39083ced-5275-423d-8a1f-9db528c106b1). Você precisará desse ID de aplicativo para vincular seu número de telefone ao aplicativo — você pode usar a CLI do Nexmo para fazer isso:

O aplicativo enviará agora uma solicitação para o seu http://your-ngrok-forwarding-address/webhooks/answer ao receber uma ligação telefônica.

Teste seu aplicativo

Do seu celular, ligue para o seu número da Nexmo para ouvir a pergunta mais importante de todas.

Conclusão

Com apenas algumas linhas de código, você criou um aplicativo capaz de receber uma ligação e reproduzir uma mensagem para quem está ligando. Existem outras maneiras de interagir com quem está ligando e outras tags da Linguagem de Marcação para Síntese de Fala (SSML) que você pode usar.

E agora, para onde vamos?

Quer saber mais? Confira nossa documentação sobre Nexmo Developer , onde você pode conhecer o fluxo de chamadas, Voice API e Objetos de Controle de Chamadas da Nexmo.