• Crie as suas próprias integrações com a Voys
• Os quatro blocos de construção
• API: o seu software pede algo a nós
• Notificações de chamada: nós enviamos algo para si
• Webhook do plano de marcação: nós perguntamos algo enquanto o telefone ainda está a tocar
• Clique para chamar: ligue com um clique
• APIs num relance
• O que se pode construir com isto?
• Construir por conta própria ou usar algo já feito?
• Responsabilidade e suporte
• FAQ

Crie as suas próprias integrações com a Voys

Quer que o seu CRM mostre quem está a chamar antes de atender? Ou que uma chamada perdida apareça automaticamente no Slack? É possível. A Voys tem quatro blocos de construção que permitem que o seu software e o nosso sistema telefónico conversem entre si: APIs, notificações de chamada, o webhook do plano de marcação e Clique para chamar.

Esta página vai além do básico: aqui também encontra URLs base, endpoints e exemplos de pedidos.

Convém saber antes de começar:

1. Esta página explica o que é possível fazer com as nossas APIs, mas não é uma especificação técnica. Os endpoints, campos e exemplos podem mudar. A documentação atual encontra-se sempre no portal OpenAPI, por isso use-o como referência quando começar a desenvolver (ou partilhe-o com o seu programador).
2. Tenha em atenção que o que construir com estas APIs, e como o faz, é da sua responsabilidade. A Voys disponibiliza a plataforma e a documentação, mas não podemos dar suporte a integrações personalizadas que construa (ou que alguém construa por si). Pode ler mais sobre isto no final da página.

Os quatro blocos de construção

API: o seu software pede algo a nós

Uma API é um balcão onde o seu software pode buscar ou deixar dados: histórico de chamadas, contatos, quem está disponível. O seu sistema pergunta, nós respondemos.

A Voys tem treze APIs, divididas em duas gerações, cada uma com o seu próprio endereço:

• As APIs mais recentes funcionam em api.eu-production.holodeck.voys.nl (Contactbook, User status, Call transcription storage).
• As restantes funcionam em api.voys.nl/api/v2 (Call, Call recording, Users, VoIP accounts, Caller ID numbers, Webphone user e as APIs de parceiro para onboarding).

A autenticação funciona da mesma forma em todo o lado: um cabeçalho Authorization: Bearer <o-seu-token> ou Authorization: Token <o-seu-token>. Por exemplo, é assim que obtém o seu próprio histórico de chamadas das últimas cinco semanas:

GET https://api.voys.nl/api/v2/call/personalized/
Authorization: Bearer <your-token>

Isto devolve, entre outras coisas, direction, answered, start_time, duration_in_seconds e quem chamou quem. A lista completa de endpoints e campos está no portal OpenAPI.

Notificações de chamada: nós enviamos algo para si

Isto funciona ao contrário: no momento em que algo acontece numa chamada, enviamos automaticamente essa informação para um URL à sua escolha. O seu software não precisa de perguntar. Nós reportamos por iniciativa própria, como um pedido POST com um corpo JSON.

Há seis momentos por chamada: created (apenas entrada), ringing, in progress, warm transfer, cold transfer e ended (com um motivo: completed, busy, no answer, failed, cancelled ou abandoned). Tem o Voys Intelligence ativado? Então seguem-se mais dois após o fim da chamada: call_transcription quando a transcrição fica pronta, e summary quando o resumo de IA fica pronto.

Cada notificação inclui pelo menos um call_id, timestamp, status, direction e detalhes sobre quem chama e o destino. Também pode usar esse call_id para obter a gravação ou transcrição da mesma chamada através das APIs correspondentes, portanto as notificações e as APIs trabalham em conjunto aqui.

Pode configurar isto no Freedom: Integração -> Notificações de chamada -> Adicionar. Escolha Custom para o seu próprio URL, ou Robin para uma integração direta.

Webhook do plano de marcação: nós perguntamos algo enquanto o telefone ainda está a tocar

Isto parece-se muito com as notificações de chamada, mas funciona ao contrário. E acontece suficientemente cedo para ainda fazer algo com a chamada: enquanto alguém está a chamar, enviamos um pedido GET ao seu servidor a perguntar para onde a chamada deve ir. Isto só funciona para chamadas recebidas, e num ponto exato do plano de marcação. É o único momento em que o seu sistema pode realmente influenciar a chamada.

É fácil confundir os dois, por isso aqui está a diferença: o webhook encaminha a chamada (GET, apenas entrada, pede uma decisão), enquanto as notificações apenas reportam o que aconteceu (POST, qualquer direção, sem influência na chamada). Pode usá-los lado a lado na mesma chamada sem qualquer problema.

Clique para chamar: ligue com um clique

Isto permite que o seu software inicie uma chamada a partir do próprio dispositivo, app ou Telefone web de alguém. Imagine um botão de chamada ao lado de cada número de telefone no seu CRM.

• Endereço: https://api.voipgrid.nl/api/clicktodial/. Convém saber: este é um domínio diferente do resto.
• Autenticação: Authorization: Token <endereço-de-e-mail>:<o-seu-token>. Isto funciona de forma ligeiramente diferente das outras APIs: o endereço de e-mail do utilizador faz parte dela, separado por dois pontos.

POST https://api.voipgrid.nl/api/clicktodial/
Authorization: Token name@company.com:<your-token>
Content-Type: application/json

{ "b_number": "+31612345678" }

Isto devolve um callid. Quer verificar como está a correr a chamada? Então consulte GET /api/clicktodial/{callid}/. Receberá um estado: a ligar (dialing_a, dialing_b), ligado (connected) ou terminado/falhado (disconnected, failing_a, failing_b). Ainda mais fácil: deixe as notificações de chamada informá-lo quando a chamada toca, é atendida ou termina.

APIs num relance

Dez das treze APIs são para o seu próprio software. As outras três (partner client, phone number e onboarding dial plan) são para parceiros que fazem onboarding de novos clientes, por isso deixámo-las de fora aqui.

Encontra todos os detalhes, campos e parâmetros de cada API no portal OpenAPI.

O que se pode construir com isto?

Reconhecer automaticamente quem está a ligar. Quando alguém telefona, o sistema procura o número na lista de contatos partilhada (Contactbook API) e mostra o nome e detalhes do cliente antes sequer de atender. Quer encaminhar a chamada conforme quem está a ligar? Então combine isto com o webhook do plano de marcação.

Chamada perdida, alerta instantâneo. Chega uma notificação ended com motivo no-answer ao URL. Procura-se o número através da Contactbook API e publica-se o nome e número no canal da equipa.

Ligar a partir do CRM, com estado em direto. Um colega clica num número e a integração envia um POST para o Clique para chamar. Em vez de fazer polling com GET /clicktodial/{callid}/, pode deixar que as notificações de chamada (ringing, in-progress, ended) atualizem o registo no CRM.

Gravação, transcrição e resumo vão parar automaticamente ao registo do cliente. Tem o Voys Intelligence ativado? Então chega uma notificação call recording created após a chamada, com um recording_url pronto a usar, seguida de call_transcription e summary assim que ficarem prontos. Depois, basta obter as versões finais através da Call Transcription Storage API e adicioná-las ao registo.

Construir por conta própria ou usar algo já feito?

Tem um programador? Pode começar já no portal OpenAPI, onde encontra a documentação técnica atual das treze APIs. Qualquer pessoa pode encontrar o seu próprio token API no Freedom, nas configurações pessoais (API token). Esse token é a chave que o software usa para se identificar junto de nós, por isso trate-o como uma palavra-passe: guarde-o bem e certifique-se de que nunca acaba em código que outros possam ver.

Não tem programador à mão? Não há problema, não tem de começar do zero. Já existem integrações prontas para ferramentas populares, como Zapier, Slack, HubSpot, Bubble, ROBIN e Microsoft Teams. Antes de pedir a alguém para construir algo, dê uma vista de olhos a esta página de ajuda sobre Integrações. Pode já existir uma solução para o seu sistema.

Responsabilidade e suporte

A Voys fornece as APIs, as notificações de chamada, o webhook e a documentação de tudo isto. Cabe-lhe a si decidir o que constrói com elas, com quem constrói e como. Isso também significa que a responsabilidade é sua.

Na prática, isto significa:

• Podemos ajudar com: se a API está acessível, se o token funciona, se o Voys Intelligence está ativado, ou se um endpoint ou código de estado não corresponde à documentação.
• Não podemos ajudar com: erros no próprio código, um fluxo Zapier criado por si que deixou de funcionar, ou uma integração construída por terceiros que já não tem manutenção.

Está emperrado e não tem a certeza de que lado está o problema? Não hesite em contactar-nos. Estamos disponíveis para pensar consigo, embora construir e manter a própria integração fique do seu lado (ou do programador).

FAQ

Preciso de saber programar? Não. Esta página ajuda a perceber o que é possível e, de forma geral, como funciona. A construção propriamente dita fica a cargo de um programador, ou então usa-se uma integração já pronta.

O meu token API está seguro? Sim, desde que o mantenha secreto. Qualquer pessoa com esse token pode obter dados ou alterar configurações em seu nome. Acha que o token pode ter sido exposto? Pode solicitar um novo no Freedom.

Por que não recebo resumos das minhas chamadas? Em quase todos os casos, é porque o Voys Intelligence ainda não está ativado. Vale a pena verificar isso primeiro, antes de procurar mais.

Posso apagar automaticamente uma gravação ou transcrição? Isso não é possível, mas também não é preciso: expiram automaticamente após o período de retenção.

E se a minha integração deixar de funcionar? Verifique primeiro se o problema está do nosso lado: o estado da API, se o token ainda é válido, ou configurações como o Voys Intelligence. O problema está no próprio código ou numa integração de terceiros? Então será necessário resolvê-lo (ou o programador). Pode ler mais em "Responsabilidade e suporte" acima.

Existem limites de taxa e o que acontece com um 429? Alguns endpoints (como Call Recording) devolvem um 429 throttled se forem chamados com demasiada frequência. Não publicámos os limites exatos, nem se está incluído um cabeçalho Retry-After. Para prevenir, é melhor implementar uma repetição com backoff.

Posso verificar se uma gravação, transcrição ou resumo já está pronto? De momento não: não há um campo de estado nem um filtro "desde X". A boa notícia é que a notificação de chamada avisa automaticamente quando algo fica pronto, por isso não é preciso fazer polling.